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本文围绕 openai-agents-python 沙箱智能体的Memory()能力展开系统讲解它如何把一次运行中沉淀的经验修复的 bug、用户的偏好、任务的失败教训蒸馏成工作区文件供后续运行复用从而降低智能体成本、用户成本与上下文成本。读完本文你将掌握内存的启用与依赖约束、渐进式公开的读取机制、两阶段内存生成管线、MemoryGenerateConfig/MemoryLayoutConfig的完整配置方法以及如何通过多轮对话与布局隔离在多智能体场景下正确组织记忆。说明本文基于 docs/sandbox/memory.md含韩文版 docs/ko/sandbox/memory.md、中文版 docs/zh/sandbox/memory.md撰写并以仓库源码 src/agents/sandbox/memory/ 与 examples/sandbox/ 作为实现层面的佐证。沙箱智能体目前仍处于 Beta 阶段API 细节、默认值与支持的能力在正式发布前可能发生变化。一、什么是沙箱智能体内存与对话式 Session 记忆的本质区别在 openai-agents-python 中内存memory让未来的沙箱智能体运行能够从先前的运行中学习。它独立于 SDK 的对话式Session记忆——后者只负责存储消息历史而沙箱内存把先前运行得到的经验蒸馏distill成沙箱工作区中的文件成为跨运行、可持久复用的工作记忆。从源码结构看内存能力位于 src/agents/sandbox/capabilities/memory.py其底层读写、两阶段生成与目录管理分别由 src/agents/sandbox/memory/ 下的manager.py、phase_one.py、phase_two.py、storage.py、prompts.py协作完成。内存降低的三类成本智能体成本Agent cost若智能体上次花很长时间才完成某个工作流下一次运行需要更少的探索从而降低 token 消耗与完成时间用户成本User cost若用户纠正过智能体或表达了偏好未来运行能记住这些反馈减少人工干预上下文成本Context cost若智能体此前已完成某项任务、用户想在此基础上继续无需重新查找旧线程或重输全部上下文任务描述可以更短。权威示例入口完整的两运行示例修复 bug → 生成内存 → 恢复快照 → 后续验证运行使用该内存examples/sandbox/memory.py采用独立内存布局的多轮、多智能体示例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)), )能力依赖规则源码可验证Memory类的required_capability_types()在 src/agents/sandbox/capabilities/memory.py 中明确定义了依赖关系只要启用了读取read非None就必须有Shell()注入的摘要不足以回答问题时智能体需要读取和检索内存文件当实时更新live update开启时默认开启还必须搭配Filesystem()智能体发现陈旧内存或用户要求更新内存时需要有能力改写memories/MEMORY.md。内存制品存储位置与复用前提默认情况下内存制品存放在沙箱工作区的memories/目录下。要在后续运行中复用它们必须保留并复用完整的、配置好的内存目录具体途径有三保持同一个实时live沙箱会话或从持久化的会话状态session state恢复或从快照snapshot恢复。一个全新创建的空沙箱内存从零开始。按需裁剪读取与生成Memory()默认同时启用读取与生成。以下两种裁剪方式适用于不同场景Memory(generateNone)只读取、不生成新内存。适合内部智能体、子智能体、检查器checker或一次性工具智能体的运行——这些运行不会产生太多值得沉淀的新信号Memory(readNone)只生成、不读取。适合需要为后续运行生成内存、但本次运行不希望被既有内存影响的场景。注意Memory在model_post_init中会校验read与generate至少启用其一两者都为None会抛出ValueError见 src/agents/sandbox/capabilities/memory.py。三、内存读取渐进式公开Progressive Disclosure与实时更新内存读取采用渐进式公开策略避免在每次运行都把全部历史塞进上下文运行开始时SDK 会把一份精炼摘要memory_summary.md通常是有用技巧、用户偏好与可用内存的概览注入到智能体的开发者提示developer prompt中。这份摘要足以让智能体判断先前的工作是否可能与当前任务相关。发现相关时智能体用当前任务的关键词去检索配置的内存索引——即memories_dir下的MEMORY.md。仅当任务需要更多细节时才打开配置的rollout_summaries/目录下对应的历史 rollout 摘要文件。从实现看摘要注入由 src/agents/sandbox/capabilities/memory.py 的instructions()完成它读取memory_summary_path用truncate_text以 token 策略截断上限常量_MEMORY_SUMMARY_MAX_TOKENS 15_000再通过render_memory_read_prompt拼接读取提示文件不存在时返回None不注入内容为空时不注入。陈旧内存与 live_update内存可能过时、与当前环境不一致。SDK 指示智能体只把内存当作参考指引以当前环境为准。默认情况下内存读取开启了live_update智能体一旦发现陈旧内存可以在同一轮运行中更新配置的MEMORY.md若你希望智能体只读不改例如对延迟敏感的运行应关闭实时更新。提示词层面对这两种模式的约束分别定义在 src/agents/sandbox/memory/prompts.py只读模式注入Never update memories. You can only read them.实时更新模式则要求智能体在检测到冲突时必须同轮完成核实替换 → 依据当前证据继续任务 → 在本轮结束前编辑MEMORY.md的完整动作序列。四、内存生成两阶段管线与默认工作区布局一次运行结束后沙箱运行时会把该运行片段run segment追加到对话文件conversation file中累积的对话文件在沙箱会话关闭时统一处理。内存生成分两个阶段阶段一对话提取conversation extraction。内存生成模型phase-one model处理一份累积的对话文件生成对话摘要。系统system、开发者developer与推理reasoning内容会被剔除对话过长时按上下文窗口截断保留开头与结尾。同时产出一份raw memory 提取物——从对话中抽取的紧凑笔记供阶段二整合。阶段二布局整合layout consolidation。整合智能体consolidation agent读取某个内存布局的全部 raw memories需要更多证据时打开对话摘要把其中的模式抽取到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/该布局由SandboxMemoryStorage.ensure_layout()在 src/agents/sandbox/memory/storage.py 中实际创建它会并行mkdirsessions_dir、memories_dir、raw_memories/、rollout_summaries/、skills/并确保MEMORY.md与memory_summary.md两个空文件存在。使用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阶段二整合时最多考虑的最近raw memories 数量必须在(0, 4096]区间内否则抛ValueErrorphase_one_modelgpt-5.4-mini阶段一单 rollout 提取使用的模型phase_one_model_settingsModelSettings(reasoningReasoning(effortmedium))阶段一模型设置接受ModelSettings实例或其字段字典phase_two_modelgpt-5.5阶段二内存整合使用的模型phase_two_model_settingsModelSettings(reasoningReasoning(effortmedium))阶段二模型设置extra_promptNone追加到提取与整合提示中的开发者自定义指引extra_prompt的正确用法用extra_prompt告诉内存生成器对你的用例而言哪些信号最重要。例如对 GTM 智能体而言客户与公司细节是关键。源码 src/agents/sandbox/memory/prompts.py 会把extra_prompt包裹进DEVELOPER-SPECIFIC EXTRA GUIDANCE区块插入到阶段一提取提示与阶段二整合提示中。官方建议见 src/agents/sandbox/config.py 与 examples/sandbox/memory.py 注释保持简短最好几条聚焦的要点总长度远低于约 5k tokens——阶段一模型本就要在同一上下文窗口中处理大量内置提示与被截断的对话过大的附加提示会挤占真正需要总结的证据空间。遗忘机制Forgetting当最近的 raw memories 数量超过max_raw_memories_for_consolidation时阶段二只保留最新对话中的内存移除更旧的。最新以对话最后一次更新的时间updated_at为准。这一遗忘机制确保内存始终反映最新的环境。实现上storage.py 的build_phase_two_input_selection()会扫描raw_memories/目录按updated_at排序无时间戳的条目排最后截取前 N 条作为本次整合输入并将淘汰列表写入phase_two_selection.json。五、多轮对话让多次Runner.run汇聚成一条内存对话多轮沙箱对话的正确姿势是使用常规 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。由于阶段一在沙箱会话关闭时才审视累积的对话内存得以从整段交流中提取而不是把两次孤立轮次分开处理。内存对话 ID 的解析顺序若希望多个Runner.run(...)调用合并为一条内存对话请在多次调用间传递一个稳定标识符。内存把一次运行关联到对话时按以下顺序解析传入Runner.run(...)的conversation_id传入 SDKSession如SQLiteSession时的session.session_id以上都没有时使用RunConfig.group_id仍无稳定标识符时为每次运行生成独立的 per-run ID。从管理器实现看src/agents/sandbox/memory/manager.py每次运行的结果会被序列化并以rollout-id.jsonl的形式追加写入sessions_dirrollout ID 必须匹配^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$的文件安全格式manager.py。六、多智能体内存隔离用MemoryLayoutConfig而非智能体名内存隔离的依据是MemoryLayoutConfig而不是智能体名称拥有相同布局 相同内存对话 ID的智能体共享一条内存对话与一份整合后的内存布局不同的智能体即使共用同一个沙箱工作区也会各自维护独立的 rollout 文件、raw memories、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)MemoryLayoutConfig只有两个字段src/agents/sandbox/config.py字段默认值说明memories_dirmemories整合后内存文件所在目录sessions_dirsessions每个 rollout 的 JSONL 制品所在目录路径校验同样在 src/agents/sandbox/capabilities/memory.pymemories_dir/sessions_dir必须是相对于沙箱工作区根目录的相对路径——绝对路径、包含..逃逸、或空路径都会抛ValueError。这样配置后GTM 分析不会被整合进工程 bug 修复的内存中反之亦然。布局级的管理器复用逻辑见 src/agents/sandbox/memory/manager.py同一沙箱会话内相同(memories_dir, sessions_dir)的生成管理器会被复用若同一memories_dir或sessions_dir已被占用但配置不同会抛出UserError提示改用不同目录或相同布局。七、源码级实现解析从运行结束到内存落盘结合 src/agents/sandbox/memory/ 目录可以把运行 → 内存的完整链路串起来运行结果入队每次Runner.run结束后SandboxMemoryGenerationManager.enqueue_result()把结果序列化为 rollout payload追加写入sessions/rollout-id.jsonlmanager.py会话关闭触发处理沙箱会话关闭时触发flush()该管理器在初始化时通过session.register_pre_stop_hook(self.flush)注册了 pre-stop 钩子见 manager.py把所有 rollout 文件排入队列并等待 worker 处理完毕阶段一逐 rollout 提取worker 为每个 rollout 渲染阶段一提示phase_one.py 会把 terminal 元数据整理成 JSON并用TruncationPolicy.tokens(150_000)截断 rollout 内容、在截断时插入明显的省略标记调用 phase-one 模型产出rollout_slug、rollout_summary与raw_memory三者皆为空则跳过validate_rollout_artifacts随后写入memories/raw_memories/rollout-id.md与memories/rollout_summaries/rollout-id_slug.md阶段二整合所有 rollout 处理完后_run_phase_two()基于max_raw_memories_for_consolidation构建输入选择、重建聚合文件raw_memories.md然后调用阶段二整合智能体max_turns500见 phase_two.py把模式写入MEMORY.md与memory_summary.md最后持久化phase_two_selection.json。这些行为均有测试覆盖例如 tests/sandbox/test_memory.py约 1950 行对 rollout 文件命名、阶段一提示渲染、内存生成管理器注册与布局冲突等进行了系统验证。八、完整两运行实战修复 bug → 生成内存 → 快照恢复后复用examples/sandbox/memory.py 演示了内存的端到端价值核心流程如下构建工作区清单Manifest中放入一个带 bug 的src/acme_metrics/report.pyformat_invoice_total把税率当加数直接相加、pyproject.toml、README 与一个测试构建带内存的智能体SandboxAgent的capabilities[Memory(), Filesystem(), Shell()]其中Memory()同时启用读写与实时更新第 1 次运行提示词为检查工作区并修复src/acme_metrics/report.py中的发票总额 bug在async with sandbox:块内执行RunConfig(sandboxSandboxRunConfig(sessionsandbox), workflow_name...)会话退出时后台生成内存制品快照恢复resumed_sandbox await client.resume(sandbox.state)用同一个本地快照目录开启新沙箱会话——确保第 2 次运行依赖的是落盘的内存而非进程内状态第 2 次运行提示词为为之前修复的 bug 添加回归测试智能体通过读取第 1 次运行沉淀的内存bug 原因、修复方式直接完成任务打印内存树脚本末尾输出sessions/、memories/MEMORY.md、memory_summary.md、raw_memories.md、raw_memories/、rollout_summaries/的实际生成情况便于直观核对默认布局。该示例的注释还给出调优建议read.live_updateFalse可省去运行中修复陈旧内存的耗时但陈旧内存会累积到下次整合generate.extra_prompt应保持简短。运行方式python examples/sandbox/memory.py --model model默认模型gpt-5.6-sol实际以你的环境可用模型为准。九、注意事项与适用前提Beta 功能沙箱智能体处于 Beta 阶段API 细节、默认值与支持能力在正式发布前可能调整依赖完整性启用读取时必须配置Shell()开启实时更新默认时还必须配置Filesystem()否则能力校验无法通过内存复用前提只有保持同一 live 沙箱会话或从持久化会话状态/快照恢复才能复用已生成的内存目录全新空沙箱内存为空路径安全memories_dir与sessions_dir必须是工作区内的相对路径禁止绝对路径与..逃逸模型与 token 约束阶段一有 150k token 的 rollout 截断上限保留头尾、插入省略标记extra_prompt建议控制在约 5k tokens 以内避免挤占对话证据的上下文空间记忆的时效性内存只是指引而非真理智能体被明确要求以当前工作区证据为准live_update与阶段二的遗忘机制共同保证内存持续跟随最新环境。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
