会话
会话为 Agents SDK 提供了一个持久化记忆层。将任何实现了 Session 接口的对象传给 Runner.run,SDK 就会处理其余工作。使用会话时,运行器会自动:
- 获取先前存储的对话条目,并将其添加到下一轮输入的开头。
- 在每次运行完成后,持久化新的用户输入和助手输出。
- 保留会话以供后续轮次使用,无论您是使用新的用户文本调用运行器,还是从中断的
RunState恢复运行。
这样就无需手动调用 toInputList(),也不必在轮次之间拼接历史记录。TypeScript SDK 内置了两种实现:面向 Conversations API 的 OpenAIConversationsSession,以及用于本地开发的 MemorySession。由于它们共用 Session 接口,您可以接入自己的存储后端。如果希望参考 Conversations API 之外的方案,可以查看 examples/memory/ 下的会话后端代码示例(Prisma、基于文件的存储等)。使用 OpenAI Responses 模型时,可以通过 OpenAIResponsesCompactionSession 包装任意会话,利用 responses.compact 自动压缩已存储的对话历史记录。
提示:要运行本页中的
OpenAIConversationsSession代码示例,请设置OPENAI_API_KEY环境变量(或在构造会话时提供apiKey),以便 SDK 调用 Conversations API。
如果希望 SDK 为您管理客户端记忆,请使用会话。如果您已经通过 conversationId 或 previousResponseId 使用 OpenAI 服务器管理的状态,通常就不需要再使用会话来管理同一份对话历史记录。
使用 OpenAIConversationsSession 将记忆与 Conversations API 同步,或替换为任何其他 Session 实现。
import { Agent, OpenAIConversationsSession, run } from '@openai/agents';
const agent = new Agent({ name: 'TourGuide', instructions: 'Answer with compact travel facts.',});
// Any object that implements the Session interface works here. This example uses// the built-in OpenAIConversationsSession, but you can swap in a custom Session.const session = new OpenAIConversationsSession();
const firstTurn = await run(agent, 'What city is the Golden Gate Bridge in?', { session,});console.log(firstTurn.finalOutput); // "San Francisco"
const secondTurn = await run(agent, 'What state is it in?', { session });console.log(secondTurn.finalOutput); // "California"复用同一个会话实例,可确保智能体在每轮开始前接收完整的对话历史记录,并自动持久化新条目。切换到其他 Session 实现时,无需更改其他代码。
对于本地演示、测试或进程内聊天状态,MemorySession 提供了相同的接口,且无需与 OpenAI 通信:
import { Agent, MemorySession, run } from '@openai/agents';
const agent = new Agent({ name: 'TourGuide', instructions: 'Answer with compact travel facts.',});
const session = new MemorySession();const result = await run(agent, 'What city is the Golden Gate Bridge in?', { session,});
console.log(result.finalOutput);OpenAIConversationsSession 构造函数选项:
| 选项 | 类型 | 说明 |
|---|---|---|
conversationId | string | 复用现有对话,而不是在需要时才创建对话。 |
client | OpenAI | 传入预先配置好的 OpenAI 客户端。 |
apiKey | string | 创建内部 OpenAI 客户端时使用的 API 密钥。 |
baseURL | string | OpenAI 兼容端点的基础 URL。 |
organization | string | 请求使用的 OpenAI 组织 ID。 |
project | string | 请求使用的 OpenAI 项目 ID。 |
MemorySession 构造函数选项:
| 选项 | 类型 | 说明 |
|---|---|---|
sessionId | string | 用于日志或测试的固定标识符。默认自动生成。 |
initialItems | AgentInputItem[] | 使用现有历史记录初始化会话。 |
logger | Logger | 覆盖用于调试输出的日志记录器。 |
MemorySession 将所有内容存储在本地进程内存中,因此进程退出后这些内容就会重置。
如果需要在构造会话之前预先创建对话 ID,请使用 startOpenAIConversationsSession(client?),并将返回的 ID 作为 conversationId 传入。
会话的核心行为
Section titled “会话的核心行为”运行器如何使用会话
Section titled “运行器如何使用会话”- 每次运行前,运行器会获取会话历史记录,将其与新一轮的输入合并,并将合并后的列表传给智能体。
- 非流式运行结束后,运行器会通过一次
session.addItems()调用,同时持久化原始用户输入和最新一轮的模型输出。 - 对于流式运行,运行器会先写入用户输入,并在该轮完成后追加流式输出。
- 从
RunResult.state恢复时(用于审批或其他中断),请继续传入同一个session。恢复的轮次会被添加到记忆中,而不会重新准备输入。
当输出护栏拒绝作为最终输出的函数工具结果时,运行器不会将被拒绝的原始结果添加到新的会话历史记录中。对于已识别的函数调用及其结果对,运行器会持久化一个可安全重放的占位内容;对于归属不明确的当前响应尾部条目,则会将其省略,而不是存储无法确认归属的输出。这项保护不会撤销外部工具的副作用,也不会清除应用在会话处理流程之外存储的数据。
查看和编辑历史记录
Section titled “查看和编辑历史记录”会话提供了简单的增删改查辅助方法,方便您构建”撤销""清空聊天”或审计功能。
import { OpenAIConversationsSession } from '@openai/agents';import type { AgentInputItem } from '@openai/agents-core';
// Replace OpenAIConversationsSession with any other Session implementation that// supports get/add/pop/clear if you store history elsewhere.const session = new OpenAIConversationsSession({ conversationId: 'conv_123', // Resume an existing conversation if you have one.});
const history = await session.getItems();console.log(`Loaded ${history.length} prior items.`);
const followUp: AgentInputItem[] = [ { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'Let’s continue later.' }], },];await session.addItems(followUp);
const undone = await session.popItem();
if (undone?.type === 'message') { console.log(undone.role); // "user"}
await session.clearSession();session.getItems() 返回已存储的 AgentInputItem[]。调用 popItem() 可移除最后一个条目,适用于用户在您重新运行智能体之前更正输入的场景。
自定义存储与合并行为
Section titled “自定义存储与合并行为”接入自己的存储
Section titled “接入自己的存储”实现 Session 接口,即可使用 Redis、DynamoDB、SQLite 或其他数据存储来保存记忆。只需实现五个异步方法。
import { Agent, run } from '@openai/agents';import { randomUUID } from '@openai/agents-core/_shims';import { getLogger } from '@openai/agents-core';import type { AgentInputItem, Session } from '@openai/agents-core';
/** * Minimal example of a Session implementation; swap this class for any storage-backed version. */export class CustomMemorySession implements Session { private readonly sessionId: string; private readonly logger: ReturnType<typeof getLogger>;
private items: AgentInputItem[];
constructor( options: { sessionId?: string; initialItems?: AgentInputItem[]; logger?: ReturnType<typeof getLogger>; } = {}, ) { this.sessionId = options.sessionId ?? randomUUID(); this.items = options.initialItems ? options.initialItems.map(cloneAgentItem) : []; this.logger = options.logger ?? getLogger('openai-agents:memory-session'); }
async getSessionId(): Promise<string> { return this.sessionId; }
async getItems(limit?: number): Promise<AgentInputItem[]> { if (limit === undefined) { const cloned = this.items.map(cloneAgentItem); this.logger.debug( `Getting items from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); return cloned; } if (limit <= 0) { return []; } const start = Math.max(this.items.length - limit, 0); const items = this.items.slice(start).map(cloneAgentItem); this.logger.debug( `Getting items from memory session (${this.sessionId}): ${JSON.stringify(items)}`, ); return items; }
async addItems(items: AgentInputItem[]): Promise<void> { if (items.length === 0) { return; } const cloned = items.map(cloneAgentItem); this.logger.debug( `Adding items to memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); this.items = [...this.items, ...cloned]; }
async popItem(): Promise<AgentInputItem | undefined> { if (this.items.length === 0) { return undefined; } const item = this.items[this.items.length - 1]; const cloned = cloneAgentItem(item); this.logger.debug( `Popping item from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); this.items = this.items.slice(0, -1); return cloned; }
async clearSession(): Promise<void> { this.logger.debug(`Clearing memory session (${this.sessionId})`); this.items = []; }}
function cloneAgentItem<T extends AgentInputItem>(item: T): T { return structuredClone(item);}
const agent = new Agent({ name: 'MemoryDemo', instructions: 'Remember the running total.',});
// Using the above custom memory session implementation hereconst session = new CustomMemorySession({ sessionId: 'session-123-4567',});
const first = await run(agent, 'Add 3 to the total.', { session });console.log(first.finalOutput);
const second = await run(agent, 'Add 4 more.', { session });console.log(second.finalOutput);自定义会话允许您在持久化之前实施保留策略、添加加密,或为每一轮对话附加元数据。
确保自定义持久化的原子性和幂等性
Section titled “确保自定义持久化的原子性和幂等性”如果后端能够以原子方式更新历史记录并记录操作标识符,请实现可选的 SessionHistoryTransactionAwareSession 接口。其 applyHistoryTransaction(...) 方法接收一个固定的 operationId,以及以下两种事务形式之一:
append_items追加一组历史记录条目。replace_suffix仅在当前存储的历史记录后缀仍与预期匹配时,才替换该后缀。
请在同一个后端事务中持久化操作标识符和历史记录变更。使用相同的操作标识符重复提交同一事务时,必须成功,但不能重复应用该事务。使用相同标识符提交不同内容,或在预期后缀已发生变化后应用 replace_suffix 时,必须失败,且不得更改历史记录。这样,运行器就能在重试和可恢复的输出护栏流程中,安全地协调已持久化的输出。
MemorySession 实现了这一约定,可供参考。现有的 Session 实现即使不实现此接口也仍然有效,但不会启用支持事务的持久化路径。
使用运行上下文限定自定义会话的作用域
Section titled “使用运行上下文限定自定义会话的作用域”当自定义会话需要使用当前的 RunContext 来进行存储路由或处理元数据时,请实现 RunContextAwareSession<TContext>,并将 acceptsRunContext 设为 true。运行器会将同一个上下文实例传给一次运行中的所有历史记录操作,包括流式持久化和恢复运行中的操作。仅实现 Session 的会话会保留现有的方法签名,调用时不会传入额外参数。
import { Agent, run, type AgentInputItem, type RunContext, type RunContextAwareSession,} from '@openai/agents';
type TenantContext = { tenantId: string;};
class TenantSession implements RunContextAwareSession<TenantContext> { readonly acceptsRunContext = true; private readonly itemsByTenant = new Map<string, AgentInputItem[]>();
async getSessionId(): Promise<string> { return 'shared-tenant-session'; }
async getItems( limit?: number, runContext?: RunContext<TenantContext>, ): Promise<AgentInputItem[]> { const items = this.getTenantItems(runContext); return limit === undefined ? [...items] : items.slice(-limit); }
async addItems( items: AgentInputItem[], runContext?: RunContext<TenantContext>, ): Promise<void> { this.getTenantItems(runContext).push(...items); }
async popItem( runContext?: RunContext<TenantContext>, ): Promise<AgentInputItem | undefined> { return this.getTenantItems(runContext).pop(); }
async clearSession(runContext?: RunContext<TenantContext>): Promise<void> { this.itemsByTenant.set(this.getTenantId(runContext), []); }
private getTenantItems( runContext: RunContext<TenantContext> | undefined, ): AgentInputItem[] { const tenantId = this.getTenantId(runContext); const items = this.itemsByTenant.get(tenantId) ?? []; this.itemsByTenant.set(tenantId, items); return items; }
private getTenantId( runContext: RunContext<TenantContext> | undefined, ): string { if (!runContext) { throw new Error('TenantSession requires a run context.'); } return runContext.context.tenantId; }}
const agent = new Agent<TenantContext>({ name: 'Assistant', instructions: 'Reply concisely.',});const session = new TenantSession();
await run(agent, 'Remember that my favorite color is green.', { context: { tenantId: 'tenant-a' }, session,});
await run(agent, 'What is my favorite color?', { context: { tenantId: 'tenant-a' }, session,});OpenAIResponsesCompactionSession 不会将运行上下文转发给其底层会话。如果要结合使用这些能力,请为每个上下文作用域保留一个独立的压缩会话实例。
控制历史记录与新条目的合并方式
Section titled “控制历史记录与新条目的合并方式”当您将 AgentInputItem 数组作为运行输入传入时,请提供 sessionInputCallback,以确定的方式将这些条目与已存储的历史记录合并。运行器会加载现有历史记录,在调用模型之前调用您的回调,并将返回的数组作为该轮的完整输入传给模型。这个钩子非常适合裁剪旧条目、去重工具结果,或仅突出您希望模型看到的上下文。
import { Agent, OpenAIConversationsSession, run } from '@openai/agents';import type { AgentInputItem } from '@openai/agents-core';
const agent = new Agent({ name: 'Planner', instructions: 'Track outstanding tasks before responding.',});
// Any Session implementation can be passed here; customize storage as needed.const session = new OpenAIConversationsSession();
const todoUpdate: AgentInputItem[] = [ { type: 'message', role: 'user', content: [ { type: 'input_text', text: 'Add booking a hotel to my todo list.' }, ], },];
await run(agent, todoUpdate, { session, // function that combines session history with new input items before the model call sessionInputCallback: (history, newItems) => { const recentHistory = history.slice(-8); return [...recentHistory, ...newItems]; },});对于字符串输入,运行器会自动合并历史记录,因此回调是可选的。回调仅在该轮输入已是条目数组时才会运行。
如果还使用了 conversationId 或 previousResponseId,请在回调结果中至少保留当前轮次的一个新条目。这些由服务器管理状态的 API 依赖当前轮次的增量。如果回调丢弃了所有新条目,SDK 会恢复原始的新输入并记录一条警告,而不是发送空增量。
处理审批与可恢复运行
Section titled “处理审批与可恢复运行”人工干预流程通常会暂停运行以等待审批:
import { Agent, MemorySession, Runner } from '@openai/agents';
const agent = new Agent({ name: 'Trip Planner', instructions: 'Plan trips and ask for approval before booking anything.',});
const runner = new Runner();const session = new MemorySession();
const result = await runner.run(agent, 'Search the itinerary', { session,});
if (result.interruptions?.length) { // ... collect user feedback, then resume the agent in a later turn. for (const interruption of result.interruptions) { result.state.approve(interruption); }
const continuation = await runner.run(agent, result.state, { session }); console.log(continuation.finalOutput);}当您从先前的 RunState 恢复时,新一轮会追加到同一份记忆记录中,以保持单一的对话历史记录。大多数人工干预(HITL)审批检查点都通过 RunState 完成往返传递,同时由会话保持对话历史记录的完整性。
当获批的函数工具结果可能成为最终输出时,输出护栏会施加更严格的边界限制。当前的 RunState 模式会在 SDK 能够确认归属时,准确记录当前响应中生成条目的归属,使受支持的、包含输出的审批检查点能够在保持会话历史记录完整的情况下恢复运行。在产生进一步的模型、工具或会话副作用之前,SDK 会验证这些归属信息。对于旧版快照,以及归属信息缺失、无效或不明确的检查点,SDK 仍会拒绝继续执行,以确保安全。当 SDK 报告此情况时,请从安全的输入开始一次新运行;不要通过重放原始条目来绕过这一限制。
进阶:历史记录压缩
Section titled “进阶:历史记录压缩”自动压缩 OpenAI Responses 历史记录
Section titled “自动压缩 OpenAI Responses 历史记录”OpenAIResponsesCompactionSession 可包装任意 Session,并使用 OpenAI Responses API 将较长的已存储历史记录替换为更短的等效对话条目列表。每轮持久化后,运行器都会将最新的 responseId 传入 runCompaction;当您的决策钩子返回 true 时,该方法会调用 responses.compact。根据 compactionMode 的设置,请求会基于最新的 Responses API 响应链或会话的当前条目构建。默认触发条件是在累积至少 10 个非用户条目后进行压缩;您可以覆盖 shouldTriggerCompaction,根据 token 数量或自定义启发式规则做出决策。压缩返回后,包装器会清空底层会话,并写入精简后的条目列表,因此请避免将其与 OpenAIConversationsSession 搭配使用,后者采用的是另一套服务器端历史记录管理流程。
import { Agent, MemorySession, OpenAIResponsesCompactionSession, run,} from '@openai/agents';
const agent = new Agent({ name: 'Support', instructions: 'Answer briefly and keep track of prior context.', model: 'gpt-5.4',});
// Wrap any Session to trigger responses.compact once history grows beyond your threshold.const session = new OpenAIResponsesCompactionSession({ // You can pass any Session implementation except OpenAIConversationsSession underlyingSession: new MemorySession(), // (optional) The model used for calling responses.compact API model: 'gpt-5.4', // (optional) your custom logic here shouldTriggerCompaction: ({ compactionCandidateItems }) => { return compactionCandidateItems.length >= 12; },});
await run(agent, 'Summarize order #8472 in one sentence.', { session });await run(agent, 'Remind me of the shipping address.', { session });
// Compaction runs automatically after each persisted turn. You can also force it manually.await session.runCompaction({ force: true });OpenAIResponsesCompactionSession 构造函数选项:
| 选项 | 类型 | 说明 |
|---|---|---|
client | OpenAI | 用于调用 responses.compact 的 OpenAI 客户端。 |
underlyingSession | Session | 用于存储的底层会话,压缩后会被清空并写入压缩后的条目。默认为供演示使用的内存会话,且不能是 OpenAIConversationsSession。 |
model | OpenAI.ResponsesModel | 用于压缩请求的模型。默认为 SDK 当前的默认 OpenAI 模型。 |
compactionMode | 'auto' | 'previous_response_id' | 'input' | 控制压缩使用服务器端响应链还是本地输入条目。 |
shouldTriggerCompaction | (context) => boolean | Promise<boolean> | 自定义触发钩子,可根据 responseId、compactionMode、候选条目和当前会话条目做出决策。 |
如果您已经使用 Responses API 响应 ID 将各轮串联起来,compactionMode: 'previous_response_id' 会很有用。compactionMode: 'input' 则会根据当前会话条目重新构建压缩请求,适用于响应链不可用,或希望以底层会话内容为准的情况。
runCompaction(args) 选项:
| 选项 | 类型 | 说明 |
|---|---|---|
responseId | string | 用于 previous_response_id 模式的最新 Responses API 响应 ID。 |
compactionMode | 'auto' | 'previous_response_id' | 'input' | 可选,用于在本次调用中覆盖已配置的模式。 |
store | boolean | 指示上一次运行是否存储了服务器状态。 |
force | boolean | 跳过 shouldTriggerCompaction 并立即压缩。 |
OpenAIResponsesCompactionSession 会串行执行通过同一包装器实例发起的变更操作。对 runCompaction()、addItems()、popItem() 和 clearSession() 的调用会按调用顺序执行,且某个操作被拒绝后队列仍会继续处理,因此后续通过包装器发起的变更不会与替换或回滚交错执行。成功的替换或回滚会使包装器缓存的历史记录与底层会话保持一致。如果替换和恢复都失败,请先恢复底层会话,再继续操作。这一顺序保证不会协调其他包装器实例,也不会协调对 underlyingSession 的直接修改;请在应用中自行协调这些访问路径。
自动压缩还会验证该次运行是否仍拥有它所读取的历史记录快照。如果在自动压缩开始前,另一个操作更改了包装器的历史记录,SDK 会保留较新的历史记录,并跳过此次压缩尝试。后续运行或显式调用 runCompaction() 可以压缩更新后的历史记录。
面向低延迟流式传输的手动压缩
Section titled “面向低延迟流式传输的手动压缩”压缩会清空并重写底层会话,因此 SDK 会等待压缩完成后,才将流式运行标记为完成。如果压缩耗时较长,result.completed 可能在最后一个输出 token 之后仍保持待完成状态数秒。为了实现低延迟流式传输或更快的轮次切换,请禁用自动压缩,并在轮次之间(或空闲时)自行调用 runCompaction。
import { Agent, MemorySession, OpenAIResponsesCompactionSession, run,} from '@openai/agents';
const agent = new Agent({ name: 'Support', instructions: 'Answer briefly and keep track of prior context.', model: 'gpt-5.4',});
// Disable auto-compaction to avoid delaying stream completion.const session = new OpenAIResponsesCompactionSession({ underlyingSession: new MemorySession(), shouldTriggerCompaction: () => false,});
const result = await run(agent, 'Share the latest ticket update.', { session, stream: true,});
// Wait for the streaming run to finish before compacting.await result.completed;
// Choose force based on your own thresholds or heuristics, between turns or during idle time.await session.runCompaction({ force: true });您可以随时调用 runCompaction({ force: true }),在归档或交接之前压缩历史记录。使用 DEBUG=openai-agents:openai:compaction 启用调试日志,以追踪压缩决策。