openai-agents-python 沙盒智能体记忆Sandbox Agent Memory实战指南启用、读取、生成与隔离【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python沙盒智能体记忆Sandbox Agent Memory是 openai-agents-python 中一类独立于对话式Session记忆的持久化机制它把一次沙盒运行中的经验、用户偏好和纠错反馈提炼成工作区内的文件供后续运行学习复用从而降低 token 消耗、人工干预和任务描述成本。本文基于官方中文文档 docs/zh/sandbox/memory.md 为主线结合仓库源码与完整示例系统讲解记忆的启用、读取、生成、多轮对话与多智能体隔离布局读完即可在自己的沙盒智能体工作流中落地一次修复、永久受益的记忆能力。注意沙盒智能体目前处于Beta 阶段文档明确标注。在正式发布之前API 细节、默认值和支持的功能可能发生变化未来也会提供更高级的功能。什么是沙盒记忆与 SDK 对话式 Session 的区别官方文档开篇即给出定义记忆可让未来的沙盒智能体运行从先前的运行中学习。它独立于 SDK 的对话式Session记忆——后者用于存储消息历史记录而沙盒记忆会将先前运行中的经验提炼为沙盒工作区中的文件如MEMORY.md、memory_summary.md、rollout_summaries/本质上是文件系统层面的长期知识库。启用记忆可以为未来运行降低三类成本智能体成本如果智能体花费很长时间才完成某个工作流下一次运行所需的探索应该会更少从而减少 token 使用量和完成时间用户成本如果用户纠正了智能体或表达了偏好未来的运行可以记住这些反馈从而减少人工干预上下文成本如果智能体之前完成过某项任务而用户希望在此基础上继续推进则用户无需查找先前的对话或重新输入所有上下文任务描述可以更短。两个官方示例贯穿全文examples/sandbox/memory.py完整的两轮运行示例——修复一个 bug、生成记忆、恢复快照并在后续验证器运行中使用该记忆examples/sandbox/memory_multi_agent_multiturn.py采用独立记忆布局的多轮、多智能体示例。启用记忆把Memory()添加为沙盒智能体的能力启用方式非常直接将Memory()作为一项能力capability添加到SandboxAgent中from pathlib import Path import tempfile from agents.sandbox import LocalSnapshotSpec, SandboxAgent from agents.sandbox.capabilities import Filesystem, Memory, Shell agent SandboxAgent( nameMemory-enabled reviewer, instructionsInspect the workspace and preserve useful lessons for follow-up runs., capabilities[Memory(), Filesystem(), Shell()], ) with tempfile.TemporaryDirectory(prefixsandbox-memory-example-) as snapshot_dir: sandbox await client.create( manifestmanifest, snapshotLocalSnapshotSpec(base_pathPath(snapshot_dir)), )能力依赖为什么需要Shell()和Filesystem()文档明确了两条依赖规则源码也在Memory.required_capability_types()中做了校验见 src/agents/sandbox/capabilities/memory.py如果启用了读取Memory()需要Shell()——当注入的摘要信息不足时智能体需要能够读取和搜索记忆文件当启用实时记忆更新时默认启用还需要Filesystem()——这样当智能体发现记忆已过时或用户要求更新记忆时它可以更新memories/MEMORY.md。产物存储位置与复用前提默认情况下记忆产物存储在沙盒工作区的memories/目录下。要在后续运行中复用这些产物需要保留并复用整个已配置的记忆目录方式有两种保持使用同一个实时沙盒会话从已持久化的会话状态或快照中恢复例如上例中的LocalSnapshotSpecclient.resume(sandbox.state)。全新的空白沙盒最初没有任何记忆。读取与生成的开关Memory(generateNone)与Memory(readNone)Memory()默认同时启用记忆读取和生成。但在两种典型场景下需要关闭其一Memory(generateNone)只读不写。适用于内部智能体、子智能体、检查器或一次性工具智能体执行的运行——它们通常不会提供太多有价值的信息不应污染记忆库Memory(readNone)只写不读。适用于运行应生成供日后使用的记忆但用户不希望该运行受现有记忆影响的场景。源码中对这一约束也有兜底校验如果read与generate同时为None会直接抛出ValueError(Memory requires at least one ofreadorgenerate.)见 src/agents/sandbox/capabilities/memory.py。读取记忆渐进式披露Progressive Disclosure记忆读取采用渐进式披露策略避免一次性把全部历史塞进上下文运行开始时注入摘要SDK 会将一个简短摘要memory_summary.md注入智能体的开发者提示词其中包含普遍有用的技巧、用户偏好以及可用记忆的索引。这给智能体足够的上下文去判断先前工作是否可能相关按需搜索索引当先前工作看起来相关时智能体会使用当前任务中的关键词在已配置的记忆索引memories_dir下的MEMORY.md中进行搜索按需打开详情只有在任务需要更多细节时它才会打开已配置的rollout_summaries/目录下相应的先前运行摘要。摘要注入的源码细节在 src/agents/sandbox/capabilities/memory.py 的instructions()方法中可以看到具体实现读取{memories_dir}/memory_summary.md若文件不存在WorkspaceReadNotFoundError或内容为空则不注入任何提示词注入前会经过truncate_text(..., TruncationPolicy.tokens(_MEMORY_SUMMARY_MAX_TOKENS))截断常量_MEMORY_SUMMARY_MAX_TOKENS 15_000同文件第 15 行即摘要上限约 1.5 万 token最终通过render_memory_read_prompt(memory_dir..., memory_summary..., live_update...)渲染成一段开发者提示词其中会注明记忆目录路径和是否允许实时更新。记忆可能过时live_update实时更新记忆可能会过时。智能体会被要求仅将记忆视为参考并以当前环境为准。默认情况下记忆读取会启用live_updateMemoryReadConfig.live_update: bool True见 src/agents/sandbox/config.py因此如果智能体发现记忆已过时可以在同一次运行中更新已配置的MEMORY.md。何时应禁用实时更新文档给出的建议是当智能体应读取记忆但不应在运行期间修改记忆时例如对延迟敏感的运行——关闭实时更新可以省去写文件的耗时但代价是过时记忆的债务会累积直到下一次整合才可能被纠正示例 examples/sandbox/memory.py 的注释对此有详细说明。生成记忆两阶段流水线与工作区布局一次运行结束后沙盒运行时会将该运行片段追加到对话文件中累积的对话文件会在沙盒会话关闭时被处理。这一调度逻辑由 src/agents/sandbox/memory/manager.py 中的SandboxMemoryGenerationManager实现运行期间把结果序列化为 rollout JSONLenqueue_result会话关闭前的flush()钩子触发阶段一提取与最终的一次阶段二整合。记忆生成分为两个阶段阶段 1对话提取Phase 1: conversation extraction。记忆生成模型处理一个累积的对话文件并生成对话摘要系统、开发者和推理内容会被省略如果对话过长则会截断对话以适应上下文窗口同时保留开头和结尾。模型还会生成原始记忆提取内容raw memory extract——从对话中提取的精简笔记供阶段 2 整合阶段 2布局整合Phase 2: layout consolidation。整合智能体读取某个记忆布局的原始记忆在需要更多依据时打开对话摘要并将其中的模式提取到MEMORY.md和memory_summary.md中。默认工作区布局workspace/ ├── sessions/ │ └── rollout-id.jsonl └── memories/ ├── memory_summary.md ├── MEMORY.md ├── raw_memories.md (intermediate) ├── phase_two_selection.json (intermediate) ├── raw_memories/ (intermediate) │ └── rollout-id.md ├── rollout_summaries/ │ └── rollout-id_slug.md └── skills/其中标记为(intermediate)的文件是中间产物raw_memories/保存每次 rollout 的原始记忆由阶段 1 生成格式包含rollout_id、updated_at、rollout_path、rollout_summary_file、terminal_state见 src/agents/sandbox/memory/manager.pyrollout_summaries/保存对应运行的对话摘要phase_two_selection.json记录阶段 2 整合时选择了哪些记忆。用MemoryGenerateConfig配置记忆生成from agents.sandbox import MemoryGenerateConfig from agents.sandbox.capabilities import Memory memory Memory( generateMemoryGenerateConfig( max_raw_memories_for_consolidation128, extra_promptPay extra attention to what made the customer more satisfied or annoyed, ), )MemoryGenerateConfig的完整字段及源码默认值见 src/agents/sandbox/config.py如下字段默认值说明max_raw_memories_for_consolidation256阶段 2 整合时最多考虑的近期原始记忆数量取值必须大于 0 且不超过 4096源码__post_init__校验phase_one_modelgpt-5.4-mini阶段 1 单次 rollout 提取所使用的模型phase_one_model_settingsModelSettings(reasoningReasoning(effortmedium))阶段 1 的模型设置推理强度 medium接受ModelSettings实例或其字段字典phase_two_modelgpt-5.5阶段 2 记忆整合所使用的模型phase_two_model_settingsModelSettings(reasoningReasoning(effortmedium))阶段 2 的模型设置extra_promptNone附加到内置记忆提取/整合提示词末尾的开发者指引extra_prompt的用法用它告诉记忆生成器哪些信号对你的使用场景最重要。例如面向市场推广GTM的智能体可以让它重点保留客户和公司详细信息。源码注释src/agents/sandbox/config.py给出了三条实用建议用几条聚焦的要点或简短段落而非大段额外说明尽量控制在约 5k token 以内通常越短越好阶段 1 的记忆生成模型已经收到一个大型内置提示词 截断后的对话过大的extra_prompt会挤占真正需要总结的证据空间。遗忘机制让记忆跟上最新环境如果近期原始记忆数量超过max_raw_memories_for_consolidation默认 256阶段 2 将只保留最新对话中的记忆并删除较旧的记忆。新旧顺序以对话最后更新时间为准源码中取自 rollout payload 的updated_at字段。这种遗忘机制有助于让记忆反映最新环境避免过时经验长期占据整合空间。多轮对话SDKSession 同一个实时沙盒会话对于多轮沙盒聊天需要把常规 SDKSession与同一个实时沙盒会话结合使用from agents import Runner, SQLiteSession from agents.run import RunConfig from agents.sandbox import SandboxRunConfig conversation_session SQLiteSession(gtm-q2-pipeline-review) sandbox await client.create(manifestagent.default_manifest) async with sandbox: run_config RunConfig( sandboxSandboxRunConfig(sessionsandbox), workflow_nameGTM memory example, ) await Runner.run( agent, Analyze data/leads.csv and identify one promising GTM segment., sessionconversation_session, run_configrun_config, ) await Runner.run( agent, Using that analysis, write a short outreach hypothesis., sessionconversation_session, run_configrun_config, )关键点两次运行都传入同一个 SDK 对话会话sessionconversation_session因此共享同一个session.session_id两次运行都会追加到同一个记忆对话文件这不同于sandbox参数——它标识的是实时工作区不会用作记忆对话 ID沙盒会话关闭时阶段 1 会处理累积的对话因此可以从整个交流过程而不是两个孤立的轮次中提取记忆。记忆对话 ID 的解析顺序如果希望多次Runner.run(...)调用形成一次记忆对话需要在这些调用中传入一个稳定标识符。当记忆将一次运行与某个对话关联时按以下顺序解析conversation_id——当你将其传入Runner.run(...)时session.session_id——当你传入 SDKSession例如SQLiteSession时RunConfig.group_id——当上述两者均不存在时每次运行生成的 ID——当不存在稳定标识符时此时每次Runner.run()各自成为独立的记忆对话。记忆隔离布局用MemoryLayoutConfig区分不同智能体记忆隔离基于MemoryLayoutConfig而不是智能体名称。具有相同布局和相同记忆对话 ID 的智能体会共享一个记忆对话和一份整合后的记忆具有不同布局的智能体则会分别保存各自的运行文件、原始记忆、MEMORY.md和memory_summary.md即使它们共享同一个沙盒工作区。当多个智能体共享一个沙盒但不应共享记忆时使用独立布局from agents import SQLiteSession from agents.sandbox import MemoryLayoutConfig, SandboxAgent from agents.sandbox.capabilities import Filesystem, Memory, Shell gtm_agent SandboxAgent( nameGTM reviewer, instructionsAnalyze GTM workspace data and write concise recommendations., capabilities[ Memory( layoutMemoryLayoutConfig( memories_dirmemories/gtm, sessions_dirsessions/gtm, ) ), Filesystem(), Shell(), ], ) engineering_agent SandboxAgent( nameEngineering reviewer, instructionsInspect engineering workspaces and summarize fixes and risks., capabilities[ Memory( layoutMemoryLayoutConfig( memories_dirmemories/engineering, sessions_dirsessions/engineering, ) ), Filesystem(), Shell(), ], ) gtm_session SQLiteSession(gtm-q2-pipeline-review) engineering_session SQLiteSession(eng-invoice-test-fix)这样可以防止 GTM 分析被整合到工程错误修复记忆中反之亦然。MemoryLayoutConfig字段与隔离的源码实现MemoryLayoutConfigsrc/agents/sandbox/config.py只有两个字段默认值均为顶层目录名字段默认值说明memories_dirmemories整合后记忆文件MEMORY.md、memory_summary.md等存放目录sessions_dirsessions每次 rollout 的 JSONL 对话产物存放目录源码对路径做了严格校验src/agents/sandbox/capabilities/memory.py必须是相对于沙盒工作区根目录的相对路径不能是绝对路径、不能包含..逃逸根目录、不能为空。在 src/agents/sandbox/memory/manager.py 的get_or_create_memory_generation_manager中可以看到隔离的落地方式记忆生成管理器以(memories_dir, sessions_dir)为 key 按会话登记同一沙盒会话内若两个Memory能力使用了相同的memories_dir或相同的sessions_dir但布局不同会抛出UserError提示改用不同的目录以隔离记忆或使用相同布局以共享记忆——这从机制上保证了布局不混淆。完整示例实战两轮运行 快照恢复 记忆验证官方示例 examples/sandbox/memory.py 完整演示了记忆的闭环其流程如下构建清单Manifest用Manifest(entries{...})构造一个带 bug 的示例项目acme-metricsreport.py中format_invoice_total的计算逻辑错误total subtotal tax_rate并附带一个会失败的测试第一轮运行提示词为Inspect workspace and fix invoice total bug in src/acme_metrics/report.py.智能体修复 bug当async with sandbox块退出、沙盒会话关闭时阶段 1/阶段 2 自动生成记忆产物快照恢复通过client.resume(sandbox.state)在新的沙盒会话中恢复同一工作区——这样第二轮运行依赖的是记忆而非进程内状态第二轮运行提示词为Add a regression test for the previous bug you fixed.智能体从注入的memory_summary.md得知第一轮的修复细节直接写出回归测试打印产物树示例末尾的_print_memory_tree会输出sessions/、memories/MEMORY.md、memory_summary.md、raw_memories/、rollout_summaries/等目录的内容便于直观验证记忆生成结果。运行方式示例代码支持--model参数python examples/sandbox/memory.py --model gpt-5.6-sol多智能体多轮场景可运行python examples/sandbox/memory_multi_agent_multiturn.py --model gpt-5.6-sol该示例在同一个沙盒工作区内分别演示了 GTM 智能体两轮对话memories/gtm布局与工程智能体单轮修复memories/engineering布局并在结尾打印两个布局各自的目录树与 JSONL 会话内容可直接对照本文的布局章节理解隔离效果。小结沙盒智能体记忆把运行经验变成了工作区内的可复用文件读取侧用渐进式披露 实时更新保证低成本、不过时生成侧用两阶段流水线对话提取 → 布局整合把原始对话提炼为MEMORY.md与memory_summary.md多轮对话靠稳定的记忆对话 IDconversation_id→session.session_id→group_id→ 随机 ID聚合多智能体隔离靠MemoryLayoutConfig的不同memories_dir/sessions_dir实现。值得留意的工程细节包括记忆产物仅在沙盒会话关闭时处理阶段 1 逐 rollout、阶段 2 统一整合见 src/agents/sandbox/memory/manager.py 的flush实现max_raw_memories_for_consolidation提供基于更新时间的遗忘机制摘要注入有 1.5 万 token 截断保护。相关单元测试见 tests/sandbox/test_memory.py可进一步了解各配置项的行为边界。由于该功能处于 Beta 阶段生产环境落地前请关注默认值与 API 的后续演进。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
