2026/9/12 1:14:51
FEATURED · 精选文章 
openai-agents-python 沙箱 Agent 记忆机制全解让每次运行都站在上一次的肩膀上【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonSandbox Agent 记忆Agent memory是 openai-agents-python 为沙箱代理提供的一项能力它把过往运行中沉淀的经验、用户偏好与修复过程蒸馏成工作区内的记忆文件让后续运行自动复习历史、减少探索成本。本文基于 docs/sandbox/memory.md 展开结合 capabilities/memory.py、config.py、memory/manager.py 等源码与 examples/sandbox/memory.py 完整示例讲透记忆的启用、读取、生成、多轮会话与多 Agent 隔离读完你就能在自己的沙箱工作流中落地一次修复、永久受益的记忆机制。什么是 Sandbox Agent 记忆在沙箱sandbox场景中一个 Agent 往往需要执行修 bug、写回归测试、分析数据、做 GTM 调研这类多步任务。如果没有记忆每次运行都要从零开始探索工作区、重新踩一遍坑。Sandbox Agent 记忆正是为解决这个问题而生记忆让未来的沙箱 Agent 运行能从之前的运行中学习。它与 SDK 的会话Session记忆是两回事——后者存储的是消息历史message history而前者把过往运行中提炼出的经验教训lessons蒸馏成沙箱工作区中的文件。也就是说Session 记忆回答我们刚才聊了什么Agent 记忆回答这个项目/任务有什么值得记住的规律。两者互补可以同时使用。记忆能为未来运行降低三类成本Agent 成本如果 Agent 上次完成某个工作流花了很长时间下一次运行就不需要那么多探索从而减少 token 消耗和完成时间。用户成本如果用户纠正过 Agent 或表达过偏好未来的运行能记住这些反馈减少人工干预。上下文成本如果 Agent 之前完成过某个任务、用户想在此基础上继续就不需要翻找旧对话或重新输入全部上下文任务描述可以更短。注意沙箱 Agent 目前处于Beta 阶段。API、默认值和所支持的能力在正式发布GA前可能变化未来还会加入更多高级特性。完整的两轮运行示例修复 bug → 生成记忆 → 恢复快照 → 后续验证运行使用记忆见 examples/sandbox/memory.py多轮、多 Agent、带独立记忆布局的示例见 examples/sandbox/memory_multi_agent_multiturn.py。启用记忆把 Memory() 加入 capabilities启用记忆非常简单给SandboxAgent的capabilities列表加上Memory()即可。从 memory.py 示例 看一个会读、会写记忆的 Agent 通常同时具备三项能力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()看 capabilities/memory.py 中required_capability_types()的实现就清楚了只要read读取开启就要求Shell()——当注入的摘要信息不够用时Agent 需要能读取和搜索记忆文件当live update实时更新开启默认开启时还要求Filesystem()——Agent 发现记忆过期或用户要求更新记忆时需要能就地修改memories/MEMORY.md。同时 capabilities/memory.py 在model_post_init中做了硬性校验read和generate至少开启一个否则抛出ValueError(Memory requires at least one ofreadorgenerate.)layout.memories_dir和layout.sessions_dir必须是相对沙箱工作区根目录的非空路径、不能是绝对路径、不能包含..越界。记忆文件的默认位置与复用条件默认情况下记忆产物存放在沙箱工作区的memories/目录下。要在后续运行中复用它们必须保留并复用整个配置的 memories 目录方式有两种保持同一个 live sandbox 会话从持久化的 session state 或快照snapshot恢复。一个全新的空沙箱记忆是空的。只读与只写两种模式Memory()默认同时开启读取和生成记忆。但某些场景下你可能只想用其中一半能力Memory(generateNone)只读不写。适合内部 Agent、子 Agent、检查器checker或一次性工具 Agent——它们的运行本身不产生太多值得沉淀的信号Memory(readNone)只写不读。本次运行要为将来生成记忆但用户不希望本次运行被已有记忆影响。在 capabilities/memory.py 中read和generate分别对应MemoryReadConfig与MemoryGenerateConfig两个配置对象设None即关闭对应方向。读取记忆渐进式披露progressive disclosure记忆读取采用渐进式披露策略避免把全部历史一股脑塞给模型运行开始时SDK 把一份简短摘要memory_summary.md包含通用技巧、用户偏好和可用记忆的索引注入 Agent 的 developer prompt。这份摘要在 capabilities/memory.py 中从memories_dir/memory_summary.md读取并经过 token 截断上限_MEMORY_SUMMARY_MAX_TOKENS 15_000。它给 Agent 足够的上下文判断之前的工作是否可能与当前任务相关。当相关工作看起来相关时Agent 在配置的记忆索引MEMORY.md位于memories_dir下中按当前任务的关键词搜索。只有当任务确实需要更多细节时才打开配置的rollout_summaries/目录下对应的历史运行摘要prior rollout summaries。记忆会过期live_update 机制记忆可能过时。Agent 被明确指示把记忆当作参考而非真理以当前环境为准。默认情况下记忆读取开启了live_update因此如果 Agent 发现记忆过期可以在同一次运行中就更新配置的MEMORY.md。这一点在 memory/prompts.py 的MEMORY_LIVE_UPDATE_INSTRUCTIONS中有非常明确的约束记忆与当前工作区状态、工具输出、环境或用户反馈冲突时当前证据优先发现记忆过期后必须用本地证据核实正确替换内容用当前证据继续任务并在同一轮内、最终回复之前更新MEMORY.md——这是任务完成的一部分不是可选的清理。而MemoryReadConfig(live_updateFalse)则让 Agent 只读不修prompt 会换成MEMORY_READ_ONLY_INSTRUCTIONS Never update memories. You can only read them.。何时关掉实时更新memory.py 示例 的注释给出建议当运行对延迟敏感时关闭它可以省去记忆修复的几秒开销但代价是过时记忆的欠账会累积到下一次 consolidation而那次 consolidation 未必能发现过期同时 Agent 也无法在运行中响应用户记住这件事/修改记忆的即时要求。生成记忆两阶段管线记忆生成是异步、后台的。机制如下每次运行结束后沙箱运行时把该运行段run segment追加到一个会话conversation文件中累积的会话文件在沙箱会话关闭时被处理。从 memory/manager.py 的类注释可以确认这条链路SandboxMemoryGenerationManager在沙箱会话期间把运行段追加到按 rollout 组织的 JSONL 文件会话关闭时对每个 rollout 执行 phase-1 抽取再做一次 phase-2 consolidation。enqueue_result负责把运行结果序列化入队flush在会话关闭时被调用通过register_pre_stop_hook注册见 manager.py最终触发两阶段处理。Phase 1会话抽取conversation extraction一个记忆生成模型处理一个累积的会话文件生成会话摘要conversation summary系统内容system、开发者内容developer和推理内容reasoning会被剔除会话太长时会被截断以适配上下文窗口保留开头和结尾原始记忆摘录raw memory extract从会话中提炼的紧凑笔记供 Phase 2 整合。Phase 2布局整合layout consolidation一个整合 Agent 读取某个记忆布局memory layout的全部原始记忆需要更多证据时打开对应的会话摘要然后把规律提炼写入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/其中sessions/下是按 rollout 组织的 JSONL 会话文件文件名规则见 manager.pyrollout ID 必须是仅含字母、数字、.、_、-的文件安全 IDmemories/下的memory_summary.md、MEMORY.md是最终消费的产物raw_memories.md、phase_two_selection.json、raw_memories/、rollout_summaries/是中间产物。skills/目录为技能类记忆预留。MemoryGenerateConfig配置生成行为用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, ), )关键参数定义见 config.py参数默认值说明max_raw_memories_for_consolidation256Phase 2 整合时考虑的最大近期原始记忆条数。若近期原始记忆超过该值只保留来自最新会话的记忆、移除更早的新近按会话最后更新时间判定。这是一种遗忘机制帮助记忆始终反映最新环境。取值必须大于 0 且不超过 4096否则抛ValueErrorphase_one_modelgpt-5.4-miniPhase 1 单 rollout 抽取使用的模型phase_one_model_settingsModelSettings(reasoningReasoning(effortmedium))Phase 1 的模型设置接受ModelSettings实例或其字段的字典phase_two_modelgpt-5.5Phase 2 记忆整合使用的模型phase_two_model_settingsModelSettings(reasoningReasoning(effortmedium))Phase 2 的模型设置extra_promptNone追加到抽取与整合 prompt 中的开发者自定义指导。用于告诉记忆生成器哪些信号对你的场景最重要——比如 GTM Agent 应重点关注客户与公司细节extra_prompt使用建议来自 config.py 与 memory.py 示例 的注释除了标准的用户偏好、失败恢复、任务摘要信号外用少量针对性 bullet 或短段落说明额外要保留的细节尽量控制在约 5k token 以内、通常越短越好。因为 Phase 1 的生成模型已经接收了内置大 prompt 加截断会话的完整上下文过长的 extra prompt 会挤占你真正希望它总结的证据空间。多轮对话SDK Session 与沙箱会话的组合多轮沙箱对话的正确姿势是把普通 SDKSession和同一个 live sandbox 会话一起使用。这样模型能看见之前的轮次记忆也能把多轮当作一次对话来抽取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两次运行会追加到同一个记忆会话文件。这不同于SandboxRunConfig(sessionsandbox)中的 sandbox 参数——后者标识的是 live 工作区不用作记忆会话 ID。当沙箱会话关闭时Phase 1 看到的是累积的完整对话能从整个交流中抽取记忆而不是两个孤立的 turn。记忆会话 ID 的解析顺序如果希望多个Runner.run(...)调用归入同一个记忆会话就在这些调用中传入一个稳定标识符。记忆把运行与会话关联时按以下顺序解析memory.py 示例 注释也印证了这一逻辑conversation_id——当你显式传给Runner.run(...)时session.session_id——当你传入 SDKSession如SQLiteSession时RunConfig.group_id——以上都没有时生成的每运行独立 ID——没有任何稳定标识符时。也就是说想要多轮共享一份记忆最省事的方式就是复用同一个 SDKSession。用不同布局隔离不同 Agent 的记忆记忆隔离基于MemoryLayoutConfig而不是 Agent 名称布局相同 记忆会话 ID 相同的 Agent → 共享一个记忆会话和一份整合后的记忆布局不同的 Agent → 即使共用同一个沙箱工作区也会各自保留独立的 rollout 文件、原始记忆、MEMORY.md和memory_summary.md。多个 Agent 共享一个沙箱但不该共享记忆时为每个 Agent 配置独立的布局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)MemoryLayoutConfig只有两个字段见 config.pymemories_dir默认memories整合后记忆文件的目录和sessions_dir默认sessions按 rollout 组织的 JSONL 产物目录。上例中 GTM 分析的记忆不会被整合进工程 bug 修复的记忆反之亦然——这正是 examples/sandbox/memory_multi_agent_multiturn.py 演示的场景同一个沙箱工作区内GTM analyst 与 Engineering fixer 各用一套memories/gtmsessions/gtm、memories/engineeringsessions/engineering。同布局冲突的保护在 memory/manager.py 中还有一个值得注意的细节同一个沙箱会话内如果多个Memory能力要复用同一个memories_dir或sessions_dir但生成配置不同会抛出UserError提示要么换一个memories_dir做隔离、要么用相同布局来共享记忆。同时同会话内相同布局的多个Memory会共享同一个记忆生成管理器manager.py保证一致性与幂等。实战闭环从修复到复用的两轮示例把以上机制串起来一个典型的记忆闭环长这样完整代码见 examples/sandbox/memory.pyRun 1Agent 在沙箱中修复report.py的发票总额计算 bug运行结束、沙箱会话关闭时触发后台记忆生成产出memories/MEMORY.md、memory_summary.md、raw_memories/、rollout_summaries/等产物恢复快照用await client.resume(sandbox.state)从持久化的快照恢复一个新沙箱会话工作区连同memories/一起保留Run 2同一个 Agent 在新会话中面对为上次修的 bug 补回归测试的提示——它会在运行开始时自动读到注入的memory_summary.md摘要必要时搜索MEMORY.md并打开rollout_summaries/基于上次的经验直接定位文件、快速完成测试编写而不再从零探索。示例还提供了一个实用的调试手段_print_memory_tree会打印生成的全部记忆产物树和内容方便你验证记忆确实落盘、内容是否符合预期。小结与使用建议默认配置即合理Memory()Filesystem()Shell()三件套默认支持读、写、实时更新记忆开箱即用按角色裁剪能力子 Agent、检查器用Memory(generateNone)避免噪音记忆临时任务用Memory(readNone)防止被旧记忆带偏多轮对话务必复用 SDK Session让多轮运行归入同一个记忆会话Phase 1 才能从完整对话中抽取多 Agent 共享沙箱时用MemoryLayoutConfig隔离布局让 GTM 分析与工程修复的记忆井水不犯河水extra_prompt要短而精聚焦你最在意的信号客户满意度、bug 根因、失败恢复步骤等别用长篇大论挤占模型对会话证据的注意力max_raw_memories_for_consolidation是遗忘旋钮环境变化快就调小让记忆更快反映最新状态。Sandbox Agent 记忆是让沙箱工作流从每次冷启动走向热启动的关键基础设施。配合 docs/sandbox/guide.md 的沙箱整体指南和 docs/sessions/index.md 的 SDK 会话文档你可以把它与消息历史记忆组合使用构建出真正具备长期学习能力的多 Agent 系统。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
openai-agents-python 沙箱 Agent 记忆机制全解：让每次运行都站在上一次的肩膀上
openai-agents-python 沙箱 Agent 记忆机制全解让每次运行都站在上一次的肩膀上【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonSandbox Agent 记忆Agent memory是 openai-agents-python 为沙箱代理提供的一项能力它把过往运行中沉淀的经验、用户偏好与修复过程蒸馏成工作区内的记忆文件让后续运行自动复习历史、减少探索成本。本文基于 docs/sandbox/memory.md 展开结合 capabilities/memory.py、config.py、memory/manager.py 等源码与 examples/sandbox/memory.py 完整示例讲透记忆的启用、读取、生成、多轮会话与多 Agent 隔离读完你就能在自己的沙箱工作流中落地一次修复、永久受益的记忆机制。什么是 Sandbox Agent 记忆在沙箱sandbox场景中一个 Agent 往往需要执行修 bug、写回归测试、分析数据、做 GTM 调研这类多步任务。如果没有记忆每次运行都要从零开始探索工作区、重新踩一遍坑。Sandbox Agent 记忆正是为解决这个问题而生记忆让未来的沙箱 Agent 运行能从之前的运行中学习。它与 SDK 的会话Session记忆是两回事——后者存储的是消息历史message history而前者把过往运行中提炼出的经验教训lessons蒸馏成沙箱工作区中的文件。也就是说Session 记忆回答我们刚才聊了什么Agent 记忆回答这个项目/任务有什么值得记住的规律。两者互补可以同时使用。记忆能为未来运行降低三类成本Agent 成本如果 Agent 上次完成某个工作流花了很长时间下一次运行就不需要那么多探索从而减少 token 消耗和完成时间。用户成本如果用户纠正过 Agent 或表达过偏好未来的运行能记住这些反馈减少人工干预。上下文成本如果 Agent 之前完成过某个任务、用户想在此基础上继续就不需要翻找旧对话或重新输入全部上下文任务描述可以更短。注意沙箱 Agent 目前处于Beta 阶段。API、默认值和所支持的能力在正式发布GA前可能变化未来还会加入更多高级特性。完整的两轮运行示例修复 bug → 生成记忆 → 恢复快照 → 后续验证运行使用记忆见 examples/sandbox/memory.py多轮、多 Agent、带独立记忆布局的示例见 examples/sandbox/memory_multi_agent_multiturn.py。启用记忆把 Memory() 加入 capabilities启用记忆非常简单给SandboxAgent的capabilities列表加上Memory()即可。从 memory.py 示例 看一个会读、会写记忆的 Agent 通常同时具备三项能力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()看 capabilities/memory.py 中required_capability_types()的实现就清楚了只要read读取开启就要求Shell()——当注入的摘要信息不够用时Agent 需要能读取和搜索记忆文件当live update实时更新开启默认开启时还要求Filesystem()——Agent 发现记忆过期或用户要求更新记忆时需要能就地修改memories/MEMORY.md。同时 capabilities/memory.py 在model_post_init中做了硬性校验read和generate至少开启一个否则抛出ValueError(Memory requires at least one ofreadorgenerate.)layout.memories_dir和layout.sessions_dir必须是相对沙箱工作区根目录的非空路径、不能是绝对路径、不能包含..越界。记忆文件的默认位置与复用条件默认情况下记忆产物存放在沙箱工作区的memories/目录下。要在后续运行中复用它们必须保留并复用整个配置的 memories 目录方式有两种保持同一个 live sandbox 会话从持久化的 session state 或快照snapshot恢复。一个全新的空沙箱记忆是空的。只读与只写两种模式Memory()默认同时开启读取和生成记忆。但某些场景下你可能只想用其中一半能力Memory(generateNone)只读不写。适合内部 Agent、子 Agent、检查器checker或一次性工具 Agent——它们的运行本身不产生太多值得沉淀的信号Memory(readNone)只写不读。本次运行要为将来生成记忆但用户不希望本次运行被已有记忆影响。在 capabilities/memory.py 中read和generate分别对应MemoryReadConfig与MemoryGenerateConfig两个配置对象设None即关闭对应方向。读取记忆渐进式披露progressive disclosure记忆读取采用渐进式披露策略避免把全部历史一股脑塞给模型运行开始时SDK 把一份简短摘要memory_summary.md包含通用技巧、用户偏好和可用记忆的索引注入 Agent 的 developer prompt。这份摘要在 capabilities/memory.py 中从memories_dir/memory_summary.md读取并经过 token 截断上限_MEMORY_SUMMARY_MAX_TOKENS 15_000。它给 Agent 足够的上下文判断之前的工作是否可能与当前任务相关。当相关工作看起来相关时Agent 在配置的记忆索引MEMORY.md位于memories_dir下中按当前任务的关键词搜索。只有当任务确实需要更多细节时才打开配置的rollout_summaries/目录下对应的历史运行摘要prior rollout summaries。记忆会过期live_update 机制记忆可能过时。Agent 被明确指示把记忆当作参考而非真理以当前环境为准。默认情况下记忆读取开启了live_update因此如果 Agent 发现记忆过期可以在同一次运行中就更新配置的MEMORY.md。这一点在 memory/prompts.py 的MEMORY_LIVE_UPDATE_INSTRUCTIONS中有非常明确的约束记忆与当前工作区状态、工具输出、环境或用户反馈冲突时当前证据优先发现记忆过期后必须用本地证据核实正确替换内容用当前证据继续任务并在同一轮内、最终回复之前更新MEMORY.md——这是任务完成的一部分不是可选的清理。而MemoryReadConfig(live_updateFalse)则让 Agent 只读不修prompt 会换成MEMORY_READ_ONLY_INSTRUCTIONS Never update memories. You can only read them.。何时关掉实时更新memory.py 示例 的注释给出建议当运行对延迟敏感时关闭它可以省去记忆修复的几秒开销但代价是过时记忆的欠账会累积到下一次 consolidation而那次 consolidation 未必能发现过期同时 Agent 也无法在运行中响应用户记住这件事/修改记忆的即时要求。生成记忆两阶段管线记忆生成是异步、后台的。机制如下每次运行结束后沙箱运行时把该运行段run segment追加到一个会话conversation文件中累积的会话文件在沙箱会话关闭时被处理。从 memory/manager.py 的类注释可以确认这条链路SandboxMemoryGenerationManager在沙箱会话期间把运行段追加到按 rollout 组织的 JSONL 文件会话关闭时对每个 rollout 执行 phase-1 抽取再做一次 phase-2 consolidation。enqueue_result负责把运行结果序列化入队flush在会话关闭时被调用通过register_pre_stop_hook注册见 manager.py最终触发两阶段处理。Phase 1会话抽取conversation extraction一个记忆生成模型处理一个累积的会话文件生成会话摘要conversation summary系统内容system、开发者内容developer和推理内容reasoning会被剔除会话太长时会被截断以适配上下文窗口保留开头和结尾原始记忆摘录raw memory extract从会话中提炼的紧凑笔记供 Phase 2 整合。Phase 2布局整合layout consolidation一个整合 Agent 读取某个记忆布局memory layout的全部原始记忆需要更多证据时打开对应的会话摘要然后把规律提炼写入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/其中sessions/下是按 rollout 组织的 JSONL 会话文件文件名规则见 manager.pyrollout ID 必须是仅含字母、数字、.、_、-的文件安全 IDmemories/下的memory_summary.md、MEMORY.md是最终消费的产物raw_memories.md、phase_two_selection.json、raw_memories/、rollout_summaries/是中间产物。skills/目录为技能类记忆预留。MemoryGenerateConfig配置生成行为用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, ), )关键参数定义见 config.py参数默认值说明max_raw_memories_for_consolidation256Phase 2 整合时考虑的最大近期原始记忆条数。若近期原始记忆超过该值只保留来自最新会话的记忆、移除更早的新近按会话最后更新时间判定。这是一种遗忘机制帮助记忆始终反映最新环境。取值必须大于 0 且不超过 4096否则抛ValueErrorphase_one_modelgpt-5.4-miniPhase 1 单 rollout 抽取使用的模型phase_one_model_settingsModelSettings(reasoningReasoning(effortmedium))Phase 1 的模型设置接受ModelSettings实例或其字段的字典phase_two_modelgpt-5.5Phase 2 记忆整合使用的模型phase_two_model_settingsModelSettings(reasoningReasoning(effortmedium))Phase 2 的模型设置extra_promptNone追加到抽取与整合 prompt 中的开发者自定义指导。用于告诉记忆生成器哪些信号对你的场景最重要——比如 GTM Agent 应重点关注客户与公司细节extra_prompt使用建议来自 config.py 与 memory.py 示例 的注释除了标准的用户偏好、失败恢复、任务摘要信号外用少量针对性 bullet 或短段落说明额外要保留的细节尽量控制在约 5k token 以内、通常越短越好。因为 Phase 1 的生成模型已经接收了内置大 prompt 加截断会话的完整上下文过长的 extra prompt 会挤占你真正希望它总结的证据空间。多轮对话SDK Session 与沙箱会话的组合多轮沙箱对话的正确姿势是把普通 SDKSession和同一个 live sandbox 会话一起使用。这样模型能看见之前的轮次记忆也能把多轮当作一次对话来抽取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两次运行会追加到同一个记忆会话文件。这不同于SandboxRunConfig(sessionsandbox)中的 sandbox 参数——后者标识的是 live 工作区不用作记忆会话 ID。当沙箱会话关闭时Phase 1 看到的是累积的完整对话能从整个交流中抽取记忆而不是两个孤立的 turn。记忆会话 ID 的解析顺序如果希望多个Runner.run(...)调用归入同一个记忆会话就在这些调用中传入一个稳定标识符。记忆把运行与会话关联时按以下顺序解析memory.py 示例 注释也印证了这一逻辑conversation_id——当你显式传给Runner.run(...)时session.session_id——当你传入 SDKSession如SQLiteSession时RunConfig.group_id——以上都没有时生成的每运行独立 ID——没有任何稳定标识符时。也就是说想要多轮共享一份记忆最省事的方式就是复用同一个 SDKSession。用不同布局隔离不同 Agent 的记忆记忆隔离基于MemoryLayoutConfig而不是 Agent 名称布局相同 记忆会话 ID 相同的 Agent → 共享一个记忆会话和一份整合后的记忆布局不同的 Agent → 即使共用同一个沙箱工作区也会各自保留独立的 rollout 文件、原始记忆、MEMORY.md和memory_summary.md。多个 Agent 共享一个沙箱但不该共享记忆时为每个 Agent 配置独立的布局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)MemoryLayoutConfig只有两个字段见 config.pymemories_dir默认memories整合后记忆文件的目录和sessions_dir默认sessions按 rollout 组织的 JSONL 产物目录。上例中 GTM 分析的记忆不会被整合进工程 bug 修复的记忆反之亦然——这正是 examples/sandbox/memory_multi_agent_multiturn.py 演示的场景同一个沙箱工作区内GTM analyst 与 Engineering fixer 各用一套memories/gtmsessions/gtm、memories/engineeringsessions/engineering。同布局冲突的保护在 memory/manager.py 中还有一个值得注意的细节同一个沙箱会话内如果多个Memory能力要复用同一个memories_dir或sessions_dir但生成配置不同会抛出UserError提示要么换一个memories_dir做隔离、要么用相同布局来共享记忆。同时同会话内相同布局的多个Memory会共享同一个记忆生成管理器manager.py保证一致性与幂等。实战闭环从修复到复用的两轮示例把以上机制串起来一个典型的记忆闭环长这样完整代码见 examples/sandbox/memory.pyRun 1Agent 在沙箱中修复report.py的发票总额计算 bug运行结束、沙箱会话关闭时触发后台记忆生成产出memories/MEMORY.md、memory_summary.md、raw_memories/、rollout_summaries/等产物恢复快照用await client.resume(sandbox.state)从持久化的快照恢复一个新沙箱会话工作区连同memories/一起保留Run 2同一个 Agent 在新会话中面对为上次修的 bug 补回归测试的提示——它会在运行开始时自动读到注入的memory_summary.md摘要必要时搜索MEMORY.md并打开rollout_summaries/基于上次的经验直接定位文件、快速完成测试编写而不再从零探索。示例还提供了一个实用的调试手段_print_memory_tree会打印生成的全部记忆产物树和内容方便你验证记忆确实落盘、内容是否符合预期。小结与使用建议默认配置即合理Memory()Filesystem()Shell()三件套默认支持读、写、实时更新记忆开箱即用按角色裁剪能力子 Agent、检查器用Memory(generateNone)避免噪音记忆临时任务用Memory(readNone)防止被旧记忆带偏多轮对话务必复用 SDK Session让多轮运行归入同一个记忆会话Phase 1 才能从完整对话中抽取多 Agent 共享沙箱时用MemoryLayoutConfig隔离布局让 GTM 分析与工程修复的记忆井水不犯河水extra_prompt要短而精聚焦你最在意的信号客户满意度、bug 根因、失败恢复步骤等别用长篇大论挤占模型对会话证据的注意力max_raw_memories_for_consolidation是遗忘旋钮环境变化快就调小让记忆更快反映最新状态。Sandbox Agent 记忆是让沙箱工作流从每次冷启动走向热启动的关键基础设施。配合 docs/sandbox/guide.md 的沙箱整体指南和 docs/sessions/index.md 的 SDK 会话文档你可以把它与消息历史记忆组合使用构建出真正具备长期学习能力的多 Agent 系统。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
)
