跳转到内容

智能体记忆

记忆让未来的沙盒智能体运行能够从先前运行中学习。它不同于 SDK 的对话式会话记忆，后者用于存储消息历史。记忆会将先前运行的经验提炼为沙盒工作区中的文件，因此请将生成的记忆产物视为留存数据，并应用与工作区相同的敏感性和留存策略。

记忆可以降低未来运行中的三类成本：

  1. 智能体成本：如果智能体花了很长时间才完成某个工作流，下一次运行应当需要更少的探索。这可以减少 token 用量和完成时间。
  2. 用户成本：如果用户纠正了智能体或表达了偏好，未来的运行可以记住这些反馈。这可以减少人工干预。
  3. 上下文成本：如果智能体之前完成过某项任务，而用户想在该任务基础上继续推进，用户就不需要查找之前的线程或重新输入全部上下文。这会让任务描述更简短。

记忆的启用

Section titled “记忆的启用”

将 memory() 作为能力添加到沙盒智能体。

启用记忆
import {
  filesystem,
  Manifest,
  memory,
  SandboxAgent,
  shell,
} from '@openai/agents/sandbox';


const manifest = new Manifest({
  entries: {
    'README.md': {
      type: 'file',
      content: '# Memory demo\n\nA workspace for follow-up runs.\n',
    },
  },
});


const agent = new SandboxAgent({
  name: 'Memory-enabled reviewer',
  model: 'gpt-5.5',
  instructions:
    'Inspect the workspace, verify important claims, and preserve useful lessons for follow-up runs.',
  defaultManifest: manifest,
  capabilities: [filesystem(), shell(), memory()],
});

如果启用了读取，memory() 需要 shell()，以便智能体在注入的摘要不够时读取和搜索记忆文件。当默认启用实时记忆更新时，它还需要 filesystem()，以便智能体在发现过时记忆或用户要求更新记忆时更新 memories/MEMORY.md。

默认情况下，记忆产物会存储在沙盒工作区的 memories/ 下。若要在后续运行中复用它们，请通过保持同一个实时沙盒会话，或从持久化的会话状态或快照恢复，来保留并复用整个已配置的记忆目录；全新的空沙盒会以空记忆开始。

memory() 会同时启用读取和生成记忆。对于应读取记忆但不应生成新记忆的智能体，请使用 memory({ generate: false })：例如内部智能体、子智能体、检查器，或运行不会增加太多信号的一次性工具智能体。当运行应为之后生成记忆，但用户不希望该运行受到现有记忆影响时，请使用 memory({ read: null })。

配置只读记忆
import { memory } from '@openai/agents/sandbox';


const readOnlyMemory = memory({
  read: { liveUpdate: false },
  generate: false,
});

记忆读取

Section titled “记忆读取”

记忆读取使用渐进式披露。在运行开始时，SDK 会向智能体的开发者提示中注入一小段摘要（memory_summary.md），其中包含通常有用的提示、用户偏好和可用记忆。这为智能体提供足够的上下文，用于判断先前工作是否相关。

当先前工作看起来相关时，智能体会使用当前任务中的关键词搜索已配置的记忆索引（memoriesDir 下的 MEMORY.md）。只有当任务需要更多细节时，它才会打开已配置的 rollout_summaries/ 目录下对应的先前 rollout 摘要。

记忆可能会过时。智能体会被指示仅将记忆视为指导，并信任当前环境。默认情况下，记忆读取会启用 liveUpdate，因此如果智能体发现过时记忆，它可以在同一次运行中更新已配置的 MEMORY.md。当智能体应读取记忆但不应在运行期间修改记忆时，可以禁用实时更新，例如运行对延迟敏感时。

记忆生成

Section titled “记忆生成”

一次运行完成后，沙盒运行时会将该运行片段追加到对话文件中。累积的对话文件会在沙盒会话关闭时被处理。这些对话文件可能包含用户输入、assistant 和工具项、中断以及最终输出，因此对于敏感工作负载，请使用适当的记忆存储和留存策略。

记忆生成分为两个阶段：

  1. 阶段 1：对话提取。生成记忆的模型会处理一个累积的对话文件，并生成对话摘要。系统、开发者和推理内容会被省略。如果对话过长，会在保留开头和结尾的同时截断，以适配上下文窗口。它还会生成原始记忆摘录：来自对话的紧凑笔记，供阶段 2 整合。
  2. 阶段 2：布局整合。整合智能体会读取某个记忆布局的原始记忆，在需要更多证据时打开对话摘要，并将模式提取到 MEMORY.md 和 memory_summary.md 中。

默认工作区布局如下：

workspace/
├── sessions/
│   └── <rollout-id>.jsonl
└── memories/
    ├── memory_summary.md
    ├── MEMORY.md
    ├── raw_memories.md
    ├── raw_memories/
    └── rollout_summaries/

你可以使用 memory({ generate: ... }) 配置记忆生成：

配置记忆生成
import { memory } from '@openai/agents/sandbox';


const memoryCapability = memory({
  generate: {
    maxRawMemoriesForConsolidation: 128,
    phaseOneModel: 'gpt-5.4-mini',
    phaseTwoModel: 'gpt-5.4',
    extraPrompt:
      'Prioritize workflow corrections, verification commands, and user preferences.',
  },
});

使用 extraPrompt 告诉记忆生成器哪些信号对你的使用场景最重要，例如面向 GTM 智能体的客户和公司详细信息。

如果近期原始记忆超过 maxRawMemoriesForConsolidation，阶段 2 会只保留来自最新对话的记忆，并删除较旧的记忆。新近程度基于对话最后一次更新的时间。这种遗忘机制有助于让记忆反映最新环境。

多轮对话

Section titled “多轮对话”

对于多轮沙盒聊天，请将常规 SDK Session 与同一个实时沙盒会话一起使用：

将一个 SDK 会话与一个沙盒会话配合使用
import { MemorySession, run } from '@openai/agents';
import {
  filesystem,
  Manifest,
  memory,
  SandboxAgent,
  shell,
} from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';


const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Memory-enabled reviewer',
  model: 'gpt-5.5',
  instructions: 'Inspect the workspace before answering.',
  capabilities: [filesystem(), shell(), memory()],
});


const conversation = new MemorySession({ sessionId: 'workspace-review' });
const sandbox = await new UnixLocalSandboxClient().create({ manifest });


try {
  await run(agent, 'Analyze data/leads.csv.', {
    session: conversation,
    sandbox: { session: sandbox },
  });
  await run(agent, 'Write a follow-up recommendation.', {
    session: conversation,
    sandbox: { session: sandbox },
  });
} finally {
  await sandbox.close?.();
}

两次运行都会追加到同一个记忆对话文件中，因为它们传入了同一个 SDK 对话会话，因此共享同一个会话 ID。这不同于沙盒，后者用于标识实时工作区，不会用作记忆对话 ID。阶段 1 会在沙盒会话关闭时看到累积的对话，因此它可以从整个交流中提取记忆，而不是从两个孤立的轮次中提取。

如果你希望多个 run(...) 调用成为同一个记忆对话，请在这些调用之间传入稳定标识符。当记忆将一次运行与某个对话关联时，会按以下顺序解析：

  1. conversationId，当你将其传给 run(...) 时。
  2. SDK session ID，当你传入 SDK Session 时。
  3. groupId，当上述两者都不存在时。
  4. 生成的单次运行 ID，当不存在稳定标识符时。

不同布局对不同智能体记忆的隔离

Section titled “不同布局对不同智能体记忆的隔离”

记忆隔离基于 MemoryLayoutConfig，而不是智能体名称。具有相同布局和相同记忆对话 ID 的智能体会共享一个记忆对话和一个整合后的记忆。具有不同布局的智能体会保留各自独立的 rollout 文件、原始记忆、MEMORY.md 和 memory_summary.md，即使它们共享同一个沙盒工作区也是如此。

当多个智能体共享一个沙盒但不应共享记忆时，请使用单独的布局：

使用单独的记忆布局
import { memory } from '@openai/agents/sandbox';


const engineeringMemory = memory({
  layout: {
    memoriesDir: 'memories/engineering',
    sessionsDir: 'sessions/engineering',
  },
});


const financeMemory = memory({
  layout: {
    memoriesDir: 'memories/finance',
    sessionsDir: 'sessions/finance',
  },
});

这可以防止一个领域的分析被整合到另一个领域的记忆中，反之亦然。