基于 openai-agents-python Sandbox 构建仓库代码评审 Agent从挂载 Git 仓库到结构化评审产物与自动化评估【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读本文以examples/sandbox/tutorials/repo_code_review示例为主线完整讲解如何用 openai-agents-python 的 Sandbox 能力构建一个「代码评审 Agent」它能把一个真实的公开 Git 仓库以固定 ref 挂载进隔离工作区在沙箱里运行测试、检查项目结构与 diff并输出带行号的结构化评审意见、Markdown 评审报告以及可落地的 patch 文件。读完本文你将掌握GitRepo清单条目、SandboxAgent能力声明、结构化最终输出RepoReviewResult、脚本化产物写入以及用evals.py对 Agent 行为做确定性校验的完整套路并可直接把这套范式迁移到自己的仓库评审、CI 检查等编码 Agent 场景。这个 Demo 要解决什么问题代码评审是编码 Agent 的典型高价值场景但把它做「可信」并不容易Agent 需要看到真实的代码工作树、能真实运行测试、能对照 diff 给出有依据的意见最后还要把结果整理成开发者可以直接行动act on的产物。repo_code_review示例把这些要素收敛为一个可复现、可评估的完整闭环其目标一句话概括见 READMEReview a small public git repository, run its tests, leave line-level review comments in the structured output, and write a patch-oriented review artifact.它的设计有几个刻意为之的取舍评审契约刻意收窄intentionally narrow评审结果被约束为恰好两条 finding——一条针对 CI 工作流repo/.github/workflows/test.yml一条针对repo/src/sample/simple.py缺失的类型注解。约束越窄越容易用脚本验证 Agent 是否真的「按规矩办事」这也正是 evals 存在的意义。演示脚本化、确定性退出main.py在脚本化评审结束后直接退出生成产物与评估契约保持确定性方便接入 CI 或作为回归测试。演示的形态输入、运行时原语与工作流README 的 Demo shape 一节把整个演示拆成了四个维度理解它们就理解了这类编码 Agent 应用的可复用骨架维度具体内容输入pypa/sampleproject在固定 git ref 上作为repo/挂载进工作区运行时原语沙箱本地 bashShell、可选文件编辑Filesystem/apply_patch、类型化最终输出RepoReviewResult工作流单评审 Agent 足够任务是一个线性的 inspect → test → patch → summarize 循环不需要 handoff草稿空间评审者可用scratchpad/记录笔记或草拟 diff最终把评审对象交回给 wrapper 持久化「不需要 handoff」这一点很关键任务链路是线性的多 Agent 编排handoff在这里是多余复杂度README 明确写了 there is no handoff because the task is a linear inspect - test - patch - summarize loop。这与仓库中 multi_agent.md 等文档讨论的复杂多智能体编排形成了互补关系——复杂场景才需要编排线性任务一个 Agent 足矣。运行方式Unix-local 与 Docker 两种沙箱后端README 给出了两套运行命令都要求从仓库根目录执行。Unix-local默认uv run python examples/sandbox/tutorials/repo_code_review/main.py uv run python examples/sandbox/tutorials/repo_code_review/evals.pyDocker 后端先构建一次共享的教程镜像再给main.py传--dockerdocker build -t sandbox-tutorials:latest -f examples/sandbox/tutorials/Dockerfile . uv run python examples/sandbox/tutorials/repo_code_review/main.py --docker uv run python examples/sandbox/tutorials/repo_code_review/evals.py两种后端由 misc.py 的create_sandbox_client_and_session统一封装非 Docker 时构造UnixLocalSandboxClient并直接client.create(manifestmanifest)Docker 时构造DockerSandboxClient并传入DockerSandboxClientOptions(imageimage)默认镜像名是Dockerfile中约定的sandbox-tutorials:latestDEFAULT_SANDBOX_IMAGE见 misc.py。该函数还会读取当前 Docker context兼容 Docker Desktop、Colima 等设置DOCKER_HOST避免硬编码某个 daemon 提供商。教程镜像本身examples/sandbox/tutorials/Dockerfile以python:3.14-slim为基础内置了uv固定版本 0.11.7、git、ripgrep、poppler-utils并预装了pypdf。这些工具与评审任务一一对应git 负责克隆被评审仓库ripgrep 用于在沙箱里快速检索代码评审提示词里明确建议用rg检查文件这也解释了为什么在沙箱内跑uv run python -m unittest discover -s tests是可行的。预期产物Expected artifactsmain.py运行结束后会在示例目录下生成output/目录包含output/review.md—— 人类可读的 Markdown 评审总结output/findings.jsonl—— 每行一条 finding 的 JSON便于机器消费与评估output/fix.patch可选—— 若评审者给出了修复补丁则落盘为 git diff。产物的写盘逻辑在 main.py 的write_review_artifacts中review_markdown直接写入review.mdfindings列表逐条model_dump(modejson)后按行写入findings.jsonl键按字母序排序保证输出稳定fix_patch非空时才写fix.patch。源码拆解Manifest 与 GitRepo 仓库挂载main.py的第一步是构造沙箱清单Manifest它决定了工作区里「有什么」manifest Manifest( entries{ AGENTS.md: File(contentAGENTS_MD.encode(utf-8)), repo: GitRepo(repoREPO_NAME, refREPO_REF), } )这里出现了两类清单条目File(content...)直接以内存内容在沙箱工作区生成一个AGENTS.md即把评审守则作为工作区文件提供给 Agent而不是只塞进 system prompt。GitRepo(repo..., ref...)把外部仓库挂载为工作区的repo/目录。示例使用的REPO_NAME pypa/sampleproject、REPO_REF 621e4974ca25ce531773def586ba3ed8e736b3fcmain.py——固定到具体 commit保证了每次评审面对的代码完全一致这是「确定性评审 可评估」的基石。GitRepo是框架内置的清单条目类型定义在 src/agents/sandbox/entries/artifacts.pyclass GitRepo(BaseEntry): type: Literal[git_repo] git_repo is_dir: bool True host: str github.com repo: str # owner/name (or any host-specific path) ref: str # tag/branch/sha subpath: str | None None从实现看artifacts.pyGitRepo.apply会在沙箱会话里先校验git可用不可用会抛GitMissingInImageError并附带镜像信息然后构造https://{host}/{repo}.git的克隆地址如果ref看起来是 commit 哈希会先走_fetch_commit_reffetch 指定 commit 后再 checkout失败则回退到按 tag/branch 克隆_clone_named_ref。这意味着示例里的长 SHA ref 走的是「精确 checkout 到指定 commit」的路径而不是简单的分支克隆。此外subpath字段支持只挂载仓库子目录可用于更大仓库的局部评审。评审 Agent能力、强制工具调用与结构化输出SandboxAgent是这次评审的执行者main.pyagent SandboxAgent( nameCode Reviewer, modelmodel, instructionsAGENTS_MD, capabilities[Shell(), Filesystem()], model_settingsModelSettings(tool_choicerequired), output_typeRepoReviewResult, )几个值得展开的点能力声明Shell()让 Agent 能在沙箱里执行 bash跑测试、rg检索、查看文件Filesystem()提供受控的文件读写。能力Capability是框架在 src/agents/sandbox/capabilities 中定义的可组合运行时能力这里只声明了评审真正需要的两种遵循最小权限思路。tool_choicerequired强制每次模型调用都必须使用工具。对编码类 Agent 这是常见且重要的设置——防止模型跳过「先看代码、跑测试」直接凭印象输出结论。注意 demo 没有声明apply_patch能力且提示词明确禁止修改被挂载仓库所以修复以fix_patch文本形式返回由外层持久化这与仓库只读、产物外置的设计一致。output_typeRepoReviewResult结构化最终输出。Runner.run_streamed结束时final_output就是该 Pydantic 模型实例wrapper 再把它落盘为三种产物。AGENTS_MDmain.py是写提示词的好范本值得逐条品味- Run uv run python -m unittest discover -s tests from repo/ and report a short result summary. - Return exactly two findings, using these exact file paths: - repo/.github/workflows/test.yml: mention nox and a concrete test-tooling/install concern. - repo/src/sample/simple.py: mention add_one and suggest - int type hints. - Do not return findings for pyproject.toml, noxfile.py, README files, or tests. - Do not edit the mounted repository. Return the suggested patch text in fix_patch. - Set fix_patch to a minimal git diff that only edits repo/src/sample/simple.py by changing def add_one(number): to def add_one(number: int) - int:. - If you inspect files with shell commands, use paths under repo/; use rg.它把「命令要精确到可直接执行」「finding 数量与路径精确约束」「负面清单不要评审哪些文件」「补丁的期望 diff」全部写成显式规则——这些规则与后面的 evals 是一一对应的提示词怎么写评估就怎么验。结构化输出协议RepoReviewResult 与 ReviewFinding评审结果被建模为两层 Pydantic 模型main.pyclass ReviewFinding(BaseModel): file: str # 工作区相对路径repo/ 下大小写以文件列表为准 line_number: int # 1-based 行号 comment: str # 针对该行的具体意见明显可修时附带 mini git-diff 建议 class RepoReviewResult(BaseModel): test_command: str # 实际执行的测试命令 test_result: str # 测试结果短摘要 findings: list[ReviewFinding] # 按严重度排序的 finding 列表 review_markdown: str # 人类可读的 Markdown 评审总结 fix_patch: str | None # 最小 git diff 补丁无修复则为 null这种「机器可读的强类型结果 人类可读的 Markdown 总结 可直接应用的 patch」的三件套结构正是把 Agent 输出接进后续流水线如 CI 评论、PR 机器人、Issue 生成的关键设计findings.jsonl给机器、review.md给人、fix.patch给工具链。字段上的Field(description...)也会进入模型的工具 schema指导模型按预期语义填充。运行编排流式运行与沙箱生命周期主流程main.py展示了 Sandbox 应用的标准生命周期client, sandbox await create_sandbox_client_and_session(manifestmanifest, use_dockeruse_docker, imageimage) try: async with sandbox: result Runner.run_streamed( agent, [{role: user, content: question}], max_turns25, run_configRunConfig( sandboxSandboxRunConfig(sessionsandbox), tracing_disabledTrue, workflow_nameRepo Review example, ), ) async for event in result.stream_events(): print_event(event) ... finally: await client.delete(sandbox)要点async with sandbox进入会话即启动沙箱后端Unix-local 进程或 Docker 容器退出时自动停止finally中client.delete(sandbox)负责彻底清理。Runner.run_streamedmax_turns25上限 25 轮工具调用循环防止评审 Agent 无限循环流式事件通过 misc.py 的print_event实时渲染成 Rich 面板工具调用、工具输出、消息、最终输出等方便观察 Agent 的一举一动。tracing_disabledTrue示例刻意关闭 tracing保证演示输出干净、退出确定。DEFAULT_QUESTIONmain.py把评审任务描述为一段自然语言指令与AGENTS_MD互为补充一段是运行时指令一段是工作区文件。确定性评估evals.py 如何校验评审质量evals.py是这套 demo 的验收测试它不依赖 LLM而是直接对落盘的产物做硬断言evals.py1. finding 数量与目标路径必须恰好 2 条且文件集合严格等于{repo/.github/workflows/test.yml, repo/src/sample/simple.py}——多了、少了、路径写错都直接失败。2. finding 内容关键词针对 workflow 的 comment 必须出现nox且必须命中{uv, pip, install, project, test}之一即必须描述具体的测试工具链/安装问题而不是泛泛而谈针对simple.py的 comment 必须同时包含add_one与- int即必须给出明确的类型注解建议。3. patch 约束fix.patch必须涉及src/sample/simple.py必须不涉及.github/workflows/test.yml与noxfile.py禁止把 patch 扩散到 CI 或配置文件必须包含目标改动def add_one(number: int) - int:。这些断言与提示词规则逐条对应形成「提示词约束 → 模型行为 → 产物断言」的闭环。跑完main.py后执行uv run python examples/sandbox/tutorials/repo_code_review/evals.py输出Repo review eval checks passed.即通过任一断言失败会抛出带明确信息的ValueError。这种把「Agent 输出可被确定性脚本验证」作为第一等公民的做法是把它接入 CI 回归的前提。源码级的原理支撑这一整套是怎么落地的从框架源码可以进一步印证这个 demo 用到的底层机制清单条目的物化Manifest的条目在会话启动时被逐条应用到沙箱工作区。GitRepo的applyartifacts.py实际执行 git clone/fetch失败时抛出结构化错误如GitCloneError、GitMissingInImageErrorFile条目则直接写文件。ManifestAppliermanifest_application.py以受限并发批量应用条目并返回MaterializationResult。能力的指令注入prepare_sandbox_agentruntime_agent_preparation.py会把 Manifest 目录结构、能力Shell/Filesystem的用法说明拼进系统指令Agent 因此知道工作区里有什么、能干什么。两种沙箱后端的实现差异UnixLocalSandboxClientunix_local.py在宿主机以受限方式执行命令DockerSandboxClientdocker.py则在容器内执行天然具备更强的隔离性。demo 默认走 Unix-local 以获得零依赖体验生产环境更推荐 Docker 后端。工作区路径安全会话对工作区外的读写做了路径校验见 workspace_paths.py 的normalize_path/ 读写检查这也是提示词里要求一切 shell 操作都走repo/路径的底层原因之一。如何把这套范式迁移到自己的评审场景repo_code_review的价值在于它是一个可复制的模板迁移时只需要改四处换仓库替换REPO_NAME与REPO_REF建议继续固定到 commit SHA必要时加subpath只评审子目录私有仓库需考虑沙箱后端的网络与认证条件。改评审契约调整AGENTS_MD中的 finding 数量、目标路径、必提关键词与负面清单同步修改RepoReviewResult/ReviewFinding的字段例如增加severity、suggestion等维度。换测试命令与运行时修改默认test_command如uv run python -m unittest discover -s tests并在 Docker 后端下把项目依赖预装进教程镜像参考 Dockerfile 追加uv pip install。同步更新 evalsEXPECTED_FINDING_PATHS、关键词集合、patch 约束必须与新契约一致否则评估会误报失败。小结repo_code_review是 openai-agents-python Sandbox 生态里「真实代码工作树 真实测试执行 确定性可评估产物」的最小完整示例Manifest/GitRepo负责把外部仓库以固定 ref 挂进沙箱SandboxAgentShell/Filesystem能力负责安全地执行检查类型化RepoReviewResult负责结构化输出write_review_artifacts负责落盘三件套产物evals.py负责把 Agent 行为锁进可回归的断言。理解这条链路之后无论是做 PR 自动评审、依赖审计、迁移重构检查还是测试补全 Agent都可以在这套骨架上快速搭建。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考