ChatSession management
An Agent call only handles the current turn. Without a session layer, developers must store history, associate it with an application user, reload it, and send the right context on every request. ChatSession solves that problem by giving the Agent SDK durable server-side conversation memory.
ChatSession is the Agent SDK adapter for the hosted Iztro conversation store. It follows the OpenAI Agents SessionABC contract and uses the /v2/platform/conversations API—not the separate managed /sessions API.
The Python and TypeScript packages expose the same conversation lifecycle with language-specific method names.
Associate a conversation with your user
- Python
- TypeScript
from iztro_agents import ChatSession
session = ChatSession(external_user_id="user_42")
import {ChatSession} from 'openai-iztro-agents';
const session = new ChatSession({externalUserId: 'user_42'});
external_user_id is your stable user-table ID. The conversation is created lazily on the first Runner.run, get_items, or add_items call. The server returns a conversation_id, exposed by the SDK as session.session_id.
Methods provided by ChatSession
| SDK method | What it does |
|---|---|
get_items(limit=None) | Read conversation items |
add_items(items) | Append items to the conversation |
pop_item() | Remove and return the last item |
clear_session() | Delete the hosted conversation and reset the local ID |
close() | Close the SDK HTTP client |
TypeScript uses camelCase equivalents: getItems, addItems, popItem, clearSession, getSessionId, and close.
To list all conversations owned by one external user, use the module helper:
- Python
- TypeScript
conversations = await ChatSession.list_user_conversations("user_42", limit=50)
const conversations = await ChatSession.listUserConversations('user_42', {limit: 50});
Resume, inspect, and clear
- Python
- TypeScript
from iztro_agents import ChatSession
session = ChatSession(conversation_id="conv_01...")
items = await session.get_items(limit=100)
last_item = await session.pop_item()
await session.clear_session()
await session.close()
import {ChatSession} from 'openai-iztro-agents';
const session = new ChatSession({conversationId: 'conv_01...'});
const items = await session.getItems(100);
const lastItem = await session.popItem();
await session.clearSession();
await session.close();
What is not part of this SDK class
ChatSession does not expose edit, resend, or fork methods. Those are managed message/revision operations on the separate /v2/platform/sessions/{session_id} API. Do not mix the two identifiers: SDK ChatSession uses conversation_id; managed Session API uses session_id.