会话

会话为 Agents SDK 提供了一个持久化记忆层。将任意实现了 Session 接口的对象传给 Runner.run，其余交由 SDK 处理。当会话存在时，runner 会自动：

1. 获取先前存储的对话条目，并将其预置到下一轮对话之前。
2. 在每次运行完成后持久化新的用户输入与助手输出。
3. 让会话在未来轮次中可用，无论是用新的用户文本调用 runner，还是从中断的 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。

---

入门

快速开始

使用 OpenAIConversationsSession 将记忆与 Conversations API 同步，或替换为任意其他 Session 实现。

将 Conversations API 用作会话记忆

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 实现无需更改其他代码。

OpenAIConversationsSession 构造函数选项：

Option	Type	Notes
conversationId	string	复用已存在的会话，而不是按需创建。
client	OpenAI	传入预配置的 OpenAI 客户端。
apiKey	string	创建内部 OpenAI 客户端时使用的 API key。
baseURL	string	OpenAI 兼容端点的基础 URL。
organization	string	请求所用的 OpenAI 组织 ID。
project	string	请求所用的 OpenAI 项目 ID。

如果需要在构造会话前预创建会话 ID，请使用 startOpenAIConversationsSession(client?) 并将返回的 ID 作为 conversationId 传入。

---

核心会话行为

runner 如何使用会话

• 在每次运行之前，会获取会话历史，将其与本轮的新输入合并，然后将合并后的列表传给您的智能体。
• 对于非流式运行，通过一次 session.addItems() 调用即可同时持久化最新轮次中的原始用户输入与模型输出。
• 对于流式运行，会先写入用户输入，并在该轮完成后追加流式输出。
• 当从 RunResult.state（用于审批或其他中断）恢复时，请继续传入相同的 session。恢复的该轮会被添加到记忆中，而无需重新准备输入。

---

查看与编辑历史

会话提供简单的 CRUD 辅助方法，以便构建“撤销”“清空聊天”或审计等功能。

读取与编辑已存储条目

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() 可移除最后一项——在重新运行智能体前，适合用于用户纠错。

---

自定义存储与合并行为

自带存储

实现 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 here
const 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);

自定义会话可让您在持久化前，对每一轮对话执行保留策略、添加加密或附加元数据。

---

控制历史与新条目如何合并

当您将 AgentInputItem 数组作为运行输入传入时，可提供 sessionInputCallback，以确定性地将其与存储的历史合并。runner 会加载现有历史，在模型调用之前调用您的回调，并将返回的数组作为该轮完整输入交给模型。此钩子非常适合裁剪旧条目、去重工具结果，或仅突出您希望模型看到的上下文。

使用 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];
  },
});

对于字符串输入，runner 会自动合并历史，因此该回调是可选的。

---

可恢复的运行

处理审批与可恢复运行

人工干预（Human in the loop，HITL）流程常会暂停运行以等待审批：

const result = await runner.run(agent, 'Search the itinerary', {
  session,
  stream: true,
});

if (result.requiresApproval) {
  // ... collect user feedback, then resume the agent in a later turn
  const continuation = await runner.run(agent, result.state, { session });
  console.log(continuation.finalOutput);
}

当您从先前的 RunState 恢复时，新的一轮会被追加到同一条记忆记录中，以保留单一的对话历史。HITL 流程保持完全兼容——审批检查点仍通过 RunState 往返，而会话则保持完整的对话记录。

---

进阶：对话记录压缩

自动压缩 OpenAI Responses 历史

OpenAIResponsesCompactionSession 可装饰任意 Session，并依赖 OpenAI Responses API 来保持对话记录精简。每次持久化轮次后，runner 会将最新的 responseId 传入 runCompaction，当您的决策钩子返回 true 时调用 responses.compact。默认触发条件是在累积至少 10 个非用户条目后进行压缩；可重写 shouldTriggerCompaction，基于 token 数或自定义启发式进行决策。该装饰器会清空并用压缩后的输出重写底层会话，因此请避免与 OpenAIConversationsSession 搭配使用，后者采用不同的服务器托管历史流程。

用 OpenAIResponsesCompactionSession 装饰会话

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.2',
});

// 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.2',
  // (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 构造函数选项：

Option	Type	Notes
client	OpenAI	用于 responses.compact 的 OpenAI 客户端。
underlyingSession	Session	用于以压缩条目清空/重写的底层会话存储（不得为 OpenAIConversationsSession）。
model	OpenAI.ResponsesModel	用于压缩请求的模型。
compactionMode	'auto' | 'previous_response_id' | 'input'	控制压缩是使用服务器响应链式模式还是本地输入条目。
shouldTriggerCompaction	(context) => boolean | Promise<boolean>	基于 responseId、compactionMode、候选条目与当前会话条目的自定义触发钩子。

runCompaction(args) 选项：

Option	Type	Notes
responseId	string	previous_response_id 模式下最新的 Responses API 响应 ID。
compactionMode	'auto' | 'previous_response_id' | 'input'	可按调用覆盖已配置的模式。
store	boolean	指示上一轮是否存储了服务器状态。
force	boolean	跳过 shouldTriggerCompaction，立即执行压缩。

低延迟流式传输的手动压缩

压缩会清空并重写底层会话，因此 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.2',
});

// 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 设为启用，以追踪压缩决策。