openai-agents-python 沙箱编码示例仓库解析从微型 Bug 仓库到自校验 Sandbox Agent 的完整闭环【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python在 openai-agents-python 的沙箱示例中examples/sandbox/docs/repo/下藏着一个刻意保持极小的示例仓库它只有一个带缺陷的 Shell 脚本、一个针对性测试脚本和一份任务书却完整演示了 Sandbox Agent沙箱编码 Agent检查仓库 → 加载技能 → 应用最小补丁 → 运行目标测试命令证明修复的端到端工作流。本文以该示例仓库为主干逐文件拆解其设计意图、缺陷契约、技能加载机制并深入到 examples/sandbox/docs/coding_task.py 与 src/agents/sandbox/capabilities/skills.py 的源码层面说明这套模式如何被确定性验证以及如何迁移到你自己的真实任务仓库。示例仓库的定位为沙箱编码示例提供确定性验证底座examples/sandbox/docs/repo/README.md全文极短却精准地交代了这个仓库的使命This tiny repo exists to supportexamples/sandbox/docs/coding_task.py. The task is intentionally small so a sandbox coding agent can inspect the repo, apply a minimal patch, and prove the fix with one targeted shell test command.翻译成设计语言就是三点它是配套示例而非独立项目存在的唯一目的是支撑 examples/sandbox/docs/coding_task.py 这个可运行示例该示例又服务于 docs/sandbox_agents.mdSandbox Agent 快速入门和 docs/sandbox/guide.md沙箱概念指南两篇官方文档。任务刻意保持极小让 Agent 能在有限的几步内完成检查 → 打补丁 → 验证不考验长链路推理而考验沙箱工具链文件系统、shell、apply_patch、技能加载是否被正确调用。验证是确定性的通过一个针对性 shell 测试命令即可判定修复是否成功从而可以在 Unix 本地沙箱运行中反复复现同样的结果。为什么用 Shell 而不是 Python/JavaScript 写这个示例官方文档给出了理由基于 Shell 的微型仓库可以在不同的 Unix 本地运行之间确定性地验证该示例见 docs/sandbox/guide.md。你的真实任务仓库当然可以是任何语言这里刻意选择 Shell 只是为了验证成本最低。仓库与配套文件全景examples/sandbox/docs/目录下围绕这个微型仓库共有七份文件形成一套完整的任务 技能 自校验运行器examples/sandbox/docs/ ├── repo/ # 微型任务仓库本文主角 │ ├── README.md # 仓库定位说明 │ ├── credit_note.sh # 带缺陷的实现脚本 │ ├── task.md # 交给 Agent 的任务书 │ └── tests/ │ └── test_credit_note.sh # 针对性测试含期望输出 ├── skills/ │ └── credit-note-fixer/ │ └── SKILL.md # 懒加载技能修复流程固化 ├── __init__.py └── coding_task.py # 自校验运行器含 4 重验证其中repo/就是本文关联文档所描述的Credit Note Example Repo——一个专为验证沙箱编码 Agent 而生的迷你仓库。核心缺陷credit_note.sh 的格式化问题任务仓库里的实现脚本credit_note.sh只有三行有效逻辑#!/bin/sh customer$1 amount$2 printf Credit note for %s: -$%s debit.\n $customer $amount它接收两个参数客户名与金额并打印一条信用票据credit note消息但存在两处故意植入的缺陷与 examples/sandbox/docs/repo/task.md 的描述一一对应标签错误输出里写的是debit借记标签而信用票据应输出credit贷记标签符号错误无论传入的金额是正是负输出都保留原始符号并硬编码一个前导负号-$%s而期望是始终把贷记金额显示为正数。也就是说当前实现无论输入12.50还是-12.50都会打印出-$12.50 debit.这种既带负号又带错误标签的结果。测试契约什么是修好了examples/sandbox/docs/repo/tests/test_credit_note.sh 定义了唯一被认可的修复标准脚本以set -eu开启严格模式共两个用例#!/bin/sh set -eu actual_positive$(sh credit_note.sh Northwind 12.50) if [ $actual_positive ! Credit note for Northwind: $12.50 credit. ]; then printf expected positive case to pass, got: %s\n $actual_positive 2 exit 1 fi actual_negative$(sh credit_note.sh Northwind -12.50) if [ $actual_negative ! Credit note for Northwind: $12.50 credit. ]; then printf expected negative case to pass, got: %s\n $actual_negative 2 exit 1 fi printf 2 passed\n测试契约的关键约束有三条正数输入sh credit_note.sh Northwind 12.50必须输出Credit note for Northwind: $12.50 credit.负数输入sh credit_note.sh Northwind -12.50也必须输出同样的结果金额取绝对值显示不带负号成功信号只有两个用例全部通过脚本最后才打印2 passed—— 这个字符串是运行器校验 Agent 是否成功的核心标志。相应地符合契约的最小修复是让脚本始终打印credit标签并把金额绝对值化例如将-12.50规范化为12.50。任务书明确要求使用最小的正确修复且不得修改测试期望。为什么测试要这样设计从验证角度看2 passed这个输出设计得非常讲究它是 examples/sandbox/docs/coding_task.py 中多处校验逻辑的共同锚点下文会看到。把成功信号固化为一行稳定字符串比解析任意测试框架的输出要可靠得多这正是一个针对性 shell 测试命令即可证明修复的设计意图所在。task.md交给 Agent 的任务书examples/sandbox/docs/repo/task.md 是 Agent 在沙箱内打开的第一份文件内容即任务本身要点包括指出credit_note.sh格式化错误的两个具体表现debit 标签、保留符号而非恒为正数要求做最小正确修复然后从repo/目录运行确切的验证命令sh tests/test_credit_note.sh特别约定若使用apply_patch补丁路径必须相对沙箱工作区根即文件应写成repo/credit_note.sh与repo/tests/test_credit_note.sh而不是 shell 当前目录下的相对路径强调不得修改测试期望。这份任务书本身是很好的提示工程范例它把bug 是什么、怎么改、用什么命令验证、路径语义是什么全部写清楚让 Agent 不需要猜测。credit-note-fixer 技能把修复流程固化为可加载的 SKILL.md仓库外紧挨着一份配套技能 examples/sandbox/docs/skills/credit-note-fixer/SKILL.md其 front-matter 声明了技能元数据--- name: credit-note-fixer description: Fix the tiny credit-note formatting bug and rerun the exact targeted test command. ---正文把五步工作流固化为技能说明读取repo/task.md检查repo/credit_note.sh与repo/tests/test_credit_note.sh做出最小正确修改保持输出标签为credit且金额为正若用apply_patch使用相对工作区根路径从repo/精确运行sh tests/test_credit_note.sh在最终答复中总结 bug、修复与确切的验证命令。这个技能与任务书形成呼应任务书定义做什么技能定义按什么流程做。在运行器中它被配置为懒加载lazy技能Agent 只有在被提示触发时才会通过load_skill调用按需加载避免把技能全文塞进每一轮上下文。coding_task.py把示例变成可自校验的闭环examples/sandbox/docs/coding_task.py 是这个示例的真正驱动者。它的 docstring 写明了用途给模型一个微型仓库加一个懒加载技能然后验证 Agent 是否编辑了仓库并运行了目标测试命令。全文围绕几个关键设计展开。1. 用 Manifest 把宿主机目录挂载进沙箱Agent 通过default_manifest声明全新沙箱会话的工作区内容default_manifestManifest( entries{ repo: LocalDir(srcEXAMPLE_DIR / repo), } )LocalDir来自agents.sandbox.entries把宿主机上的examples/sandbox/docs/repo/目录以repo为名挂载进沙箱工作区。这样 Agent 在沙箱内看到的路径就是repo/credit_note.sh、repo/task.md、repo/tests/test_credit_note.sh与任务书和技能中的路径约定完全一致。2. 通过 Capabilities 挂载懒加载技能源在默认能力之上追加Skills能力capabilitiesCapabilities.default() [ Skills( lazy_fromLocalDirLazySkillSource( # This is a host path read by the SDK process. # Requested skills are copied into skills_path in the sandbox. sourceLocalDir(srcEXAMPLE_DIR / skills), ) ), ],这里有一个值得注意的语义细节源码注释也强调了LocalDirLazySkillSource.source是由 SDK 进程读取的宿主机路径当 Agent 请求某个技能时该技能才会被复制进沙箱的skills_path。这正对应 src/agents/sandbox/capabilities/skills.py 中懒加载技能的实现——从源码结构看懒加载模式不会把技能正文预先注入上下文而是在会话中提供一个技能索引名称 描述 工作区路径并约定使用懒技能前先调用load_skill加载再打开其SKILL.md。3. 指令中的路径与行为约定运行器在instructions中写入了比快速入门更严格的约定先读repo/task.md编辑前使用$credit-note-fixer技能保持最小正确修改、保持既有行为、基于仓库事实作答明确apply_patch的路径相对沙箱工作区根而非 shell 工作目录因此要写成repo/credit_note.sh与repo/tests/test_credit_note.sh从repo/运行确切的验证命令sh tests/test_credit_note.sh并在最终答复中提及该命令。此外还设置了model_settingsModelSettings(tool_choicerequired)强制模型必须调用工具确保这个演示场景中工具调用链一定发生。4. 运行与四重校验主流程创建UnixLocalSandboxClient用client.create(manifestagent.default_manifest)启动沙箱然后以max_turns12运行 AgentRunConfig中把sandboxSandboxRunConfig(sessionsandbox)绑定到已启动的会话并关闭 tracing、设置工作流名称。运行结束后执行四重校验对应 examples/sandbox/docs/coding_task.py 中的断言逻辑必须调用过load_skill从result.new_items中过滤出ToolCallItem要求工具名列表包含load_skill否则报错必须调用过apply_patch工具名列表需包含apply_patch通过识别apply_patch_call类型的原始条目必须执行过目标测试命令遍历工具调用匹配exec_command的cmd含sh tests/test_credit_note.sh且workdir为repo目标测试必须输出2 passed跟踪目标命令调用之后紧跟的ToolCallOutputItem其输出必须包含2 passed。最后还有一道运行后独立复核运行器直接对沙箱执行sandbox.exec(cd repo sh tests/test_credit_note.sh, shellTrue)再次确认退出码为 0 且输出含2 passed并把修复后的repo/credit_note.sh全文读出来打印。也就是说即使 Agent 的中间行为有偏差只要最终工作区状态与目标命令输出达标复核仍能兜底验证。5. 运行方式该脚本可通过命令行参数运行默认模型与提示词已内置python examples/sandbox/docs/coding_task.py python examples/sandbox/docs/coding_task.py --model gpt-5.6-sol --prompt 自定义提示词其中--prompt的默认值为Open repo/task.md, use the $credit-note-fixer skill, fix the bug, run sh tests/test_credit_note.sh, and summarize the change.。运行成功时它会打印最终输出摘要、观察到的工具调用序列、验证命令、验证结果以及修复后的credit_note.sh全文。在官方文档中的位置快速入门与概念指南这个示例仓库承担着最小可复现教学用例的角色被两处官方文档引用docs/sandbox_agents.mdSandbox Agent 快速入门Create a local sandbox agent一节给出了精简版示例——把repo/通过Manifest挂载、把skills/通过Skills(lazy_fromLocalDirLazySkillSource(...))挂载然后直接用Runner.run驱动。并在文末注明该示例使用微型 Shell 仓库以支持跨 Unix 本地运行的确定性验证。docs/sandbox/guide.md在Common patterns等章节给出与coding_task.py对齐的完整版本含TARGET_TEST_CMD常量、tool_choicerequired、以及未设置SandboxRunConfig.cwd时补丁路径相对工作区根的明确说明并把该示例作为运行后检查工作区模式的参考实现。从文档结构可以推断这套示例承担了两个教学目的一是展示 Sandbox Agent 的最小可用配置Manifest Capabilities SandboxRunConfig 三件套二是展示可验证的编码任务闭环任务书 → 技能 → 补丁 → 目标测试。源码支撑Skills 能力的实现要点要理解为什么必须调用load_skill是一条合法校验可以看 src/agents/sandbox/capabilities/skills.py。该文件中维护了两套面向模型的技能使用说明常规模式_HOW_TO_USE_SKILLS_SECTION技能列表直接可用打开SKILL.md即可遵循工作流支持references/、scripts/、assets/等附属目录的按需加载懒加载模式_HOW_TO_USE_LAZY_SKILLS_SECTION会话只提供技能索引名称 描述 工作区路径并明确约定——使用懒技能前先调用load_skill加载该技能然后再打开其SKILL.md。这正是coding_task.py校验load_skill调用存在的依据在懒加载配置下任何按流程行事的 Agent 都必须先发出load_skill工具调用。两类说明还共享若干通用约束技能路径应视为技能根目录来解析相对引用、技能文件属于沙箱会话且可能被其他运行可见、任务输入输出应写在运行工作目录而非技能目录等。这些细节意味着技能能力不仅是把文件拷进沙箱还包含一整套关于发现、触发、渐进式披露与上下文卫生的协议最终以提示片段的形式注入模型上下文。把模式迁移到真实任务仓库这个微型示例最有价值的其实是它的可迁移骨架。把credit_note.sh换成任意语言的真实代码库只需保持以下结构任务书先行仓库内放一份task.md写清缺陷表现、最小修改要求、验证命令与路径语义单一验证命令把修好了收敛成一个确定的退出码或稳定输出串如本例的2 passed便于自动化校验技能固化流程把修复/开发流程写成SKILL.md通过LocalDirLazySkillSource挂载为懒加载技能降低每轮上下文开销清单挂载用Manifest(entries{repo: LocalDir(src...)})把宿主机目录映射为沙箱工作区路径自校验运行器参考coding_task.py的四重校验在运行后检查关键工具调用、目标命令输出并独立复核工作区状态。官方文档也提示了扩展方向同一份SandboxAgent定义可以只更换沙箱客户端Docker 或托管供应商、更换工作区来源Git 仓库、远程快照等或更换会话来源session、session_state、snapshot来适配不同场景见 docs/sandbox/guide.md 的 Common patterns 与 docs/sandbox/clients.md。小结examples/sandbox/docs/repo/这个刻意极小的示例仓库是理解 openai-agents-python 沙箱编码能力的最佳起点它以最小代价展示了 Sandbox Agent 检查仓库、加载技能、应用补丁、运行测试的完整闭环并通过coding_task.py的四重校验实现了可复现的确定性验证。从任务书、测试契约、技能文件到运行器与底层 Skills 实现每一环都有明确的文件可循——这套骨架可以直接套用到你自己的编码任务仓库上。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
