ChatSession 管理
一次 Agent 调用只处理当前轮次。没有会话层时，开发者必须自行保存历史、关联应用用户、重新读取历史，并在每次请求时传入正确上下文。ChatSession 为 Agent SDK 提供服务端持久对话记忆，解决这些重复工作。
ChatSession 是 Agent SDK 适配 Iztro 托管会话存储的类。它遵循 OpenAI Agents 的 SessionABC 协议，使用 /v2/platform/conversations API；不要把它与独立的托管 /sessions API 混淆。
Python 与 TypeScript SDK 提供相同的会话生命周期能力，只是方法命名遵循各自语言习惯。
将对话关联到你的用户
- 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 应使用你用户表中的稳定 ID。第一次执行 Runner.run、get_items 或 add_items 时才会创建对话。服务端返回 conversation_id，SDK 将其暴露为 session.session_id。
ChatSession 提供的方法
| SDK 方法 | 用途 |
|---|---|
get_items(limit=None) | 读取会话条目 |
add_items(items) | 向会话追加条目 |
pop_item() | 删除并返回最后一个条目 |
clear_session() | 删除托管对话并重置本地 ID |
close() | 关闭 SDK HTTP 客户端 |
TypeScript 使用驼峰命名：getItems、addItems、popItem、clearSession、getSessionId 和 close。
列出某个外部用户拥有的全部对话：
- Python
- TypeScript
conversations = await ChatSession.list_user_conversations("user_42", limit=50)
const conversations = await ChatSession.listUserConversations('user_42', {limit: 50});
恢复、查看与清除
- 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();
不属于该 SDK 类的操作
ChatSession 不提供 edit、resend 或 fork。它们是独立的 /v2/platform/sessions/{session_id} API 上的托管消息/版本操作。不要混用标识符：SDK 的 ChatSession 使用 conversation_id，托管 Session API 使用 session_id。