使用OpenAI Agents SDK前需先编写运行契约

提到 OpenAI Agents SDK，许多人首先想到的是“太好了，这下可以更快速地搭建多 Agent 系统了”。坦白说，这种理解过于表浅，没能抓住其真正的价值所在。

真正值得深入研究的，是这个 SDK 如何将 agent、tool、handoff、guardrail、session、tracing 和 sandbox 等运行时概念，统一整合到同一个 Python SDK 中。这意味着什么？它意味着开发团队首次有机会将 Agent 工作流从“一段 prompt 脚本”升级为“一个可审计、可管控、可回溯的工程单元”。如果你只把它当作一个搭积木的工具，那就错过了它最核心的潜力。

但这也意味着，第一轮采用不应该追求 agent 数量。不妨先问一个更关键的问题：当一个 agent 可以调用工具、可以委派任务给另一个 agent、可以保留 session、可以进入 sandbox、可以产生日志和 trace 的时候——谁对每一步操作负责？事情搞砸了，如何复盘？

Doramagic 项目页：https://doramagic.ai/zh/projects/openai-agents-python/
Doramagic 手册：https://doramagic.ai/zh/projects/openai-agents-python/manual/
上游项目：https://github.com/openai/openai-agents-python

评估之前，先看事实基础

先说清楚背景。2026-07-08 曼谷时间，本地日更目录中没有 openai-agents-python 的历史发布包。Doramagic 中英文项目页和手册均返回 HTTP 200，PROJECT_PACK 可访问，并列出了 quick start、prompt preview、human manual、AI context pack、boundary risk card、pitfall log、repo inspection、capability contract、evidence index、claim graph 等资产。

上游仓库仍然活跃。通过 GitHub API 采集到的快照是：27,726 stars、4,272 forks、65 open issues、MIT license，最近 push 时间为 2026-07-07T23:47:16Z，仓库更新时间为 2026-07-08T03:16:59Z。最新 GitHub release 是 v0.18.0，发布时间为 2026-07-07T06:01:55Z。

包元数据也很关键。pyproject.toml 声明包名为 openai-agents，版本 0.18.0，Python 要求 >=3.10，依赖包括 openai>=2.36.0,低于 3、pydantic>=2.12.2,低于 3、requests、websockets 和 mcp>=1.19.0,<2。可选 extras 覆盖 voice、realtime、redis、SQLAlchemy、Dapr、MongoDB、多种 sandbox/provider 集成等。

本地烟测暴露了一个很实际的采用边界：macOS 默认 python3 是 3.9.6，安装 openai-agents==0.18.0 会被 pip 拒绝，因为包要求 Python >=3.10。改用 python3.12 创建隔离 venv 后，安装成功，并且可以导入 Agent 和 Runner。所以，第一步不是写 agent，而是锁定 Python 运行时环境。

别急着搞多 Agent

多 Agent 架构最容易制造一种错觉：把任务拆给多个角色，系统就会变得更专业。但在工程实践中，事实往往相反。角色越多，就越需要明确谁负责状态管理、谁拥有工具权限、handoff 的条件是什么、失败后如何恢复、trace 证据在哪里、最终责任人是谁。

我通常建议，先只构建一个 agent，并且只给它一个低风险工具。这个工具需要满足三个条件：

输入输出可序列化，方便记录 trace；没有生产环境写权限，避免第一次试验就造成真实变更；有明确的失败模式——比如超时、空结果、权限拒绝、schema 不匹配。

这个最小 agent 跑通之后，再添加第二个。第二个 agent 不应该只是“一个专家角色”，而应该承担一个可验证的职责。例如，只负责审核 tool 输出，或者只负责生成测试用例，或者只负责判断是否需要人工干预。职责清晰，才能判断好坏。

运行契约，比 quickstart 重要得多

OpenAI Agents SDK 的 README 把核心概念列得很清楚：Agents、Sandbox Agents、Agents as tools / Handoffs、Tools、Guardrails、Human in the loop、Sessions、Tracing、Realtime Agents。每个概念都好理解，但真正落地的工作，是把这些概念变成团队内部的运行契约。

我会要求每个 agent workflow 至少写清楚八件事：

Tool boundary：agent 能调用哪些工具，哪些工具只能读，哪些工具能写。
Handoff owner：handoff 后谁对最终输出负责，原 agent 是否还能继续改写。
Session scope：session 是 user、task、workspace 还是 run 级别。
Guardrail action：guardrail 失败时是拒绝、重试、降级、人工确认，还是写入事故日志。
Trace retention：trace 保存多久，谁能看，是否包含用户隐私或密钥片段。
Sandbox permission：sandbox 能读哪些目录，能否联网，能否执行 shell，能否写回仓库。
Human approval：哪些动作必须人工确认——比如发帖、删文件、付款、发邮件、修改生产配置。
Recovery rule：run 中断后从哪里恢复，是否允许复用上一次 tool 输出。

没有这些规则，SDK 也只能帮你更快地制造不可解释的 agent 行为。

Sandbox Agent：价值很大，风险也大

README 中的 Sandbox Agents 是一个重要信号。它把 agent 从“回答问题”推进到“在一个可控计算环境里执行任务”。这对代码阅读、命令执行、补丁生成、长任务状态保持都很有用。

但 sandbox 不等于安全。它只是把风险集中到一个边界里，边界本身仍然需要精心设计。

第一轮 sandbox 试验，我不会连接真实仓库写权限。更合理的顺序是：

只挂载只读 demo repo，让 agent 总结 README 和文件结构；允许在临时目录里生成文件，但不允许写回原仓库；允许跑测试，但记录命令、退出码、stdout/stderr；允许生成 patch，但由人工或 CI 决定是否应用；最后才讨论是否给 agent 写权限。

这个顺序慢一点，但能避免“agent 成功改了文件，所以系统可用”的误判。真正的问题是：它改了什么？依据是什么？失败了能不能复盘？下一次 run 会不会继承错误状态？

最近 issue 划出的评估重点

最新 open issue 里有几个信号值得关注。不是因为它们会阻塞采用，而是因为它们告诉你评估时要盯哪里：

session history retrieval 是否应该按 run/turn 感知，而不是只按 item limit；sandbox provider 扩展仍在演进；eager tool dispatch 说明 tool execution 和 model streaming 的重叠仍有工程空间；FunctionTool 底层函数访问需要稳定 public access。

这些问题共同指向一个结论：不要只测“能不能跑 hello world”。应该测 session 截断后是否丢失关键上下文，handoff 后是否能追溯责任，tool schema 变化后是否会静默失败，sandbox provider 替换后权限模型是否仍然一致。

我会采用的最小路径

第一步，固定 Python 版本。本文实际烟测表明，python3.9 会失败，python3.12 可安装并导入。团队环境应明确写成 Python >=3.10，最好直接用 uv 或固定 venv 管理。

第二步，做一个单 agent、单 tool、无生产写权限的 workflow。输出必须包含 trace id、tool input、tool output 摘要、guardrail 结果和最终回答。

第三步，加入一个失败用例。不要只跑成功路径。至少测试 tool 超时、tool 返回空值、tool 抛异常、用户要求超出授权范围的操作。

第四步，才引入 handoff。handoff 的验收标准不是“另一个 agent 回答了”，而是 trace 能展示为什么转交、转交了什么上下文、转交后谁负责最终输出。

第五步，如果要用 sandbox agent，先从只读 repo 和临时目录开始。不要在第一轮就给生产仓库、密钥目录、真实发布账号或付费 API 动作权限。

结论

OpenAI Agents SDK 值得认真评估，因为它覆盖的不是单点能力，而是一组 agent runtime primitives：tools、handoffs、guardrails、sessions、tracing、sandbox、人类确认和 realtime。它的价值不在于让团队“更像在做多 Agent”，而在于让 agent 工作流有机会被审计、被限制、被复盘。

我的采用建议很直接：先把运行契约写清楚，再写 agent 数量。先让一个 agent 在低风险工具上稳定、可追踪、可恢复，再扩展到 handoff 和 sandbox。能跑 quickstart 是入口；能解释每一次工具调用和失败恢复，才是进入生产的开始。

来源说明：本文基于 Doramagic openai-agents-python 项目页/手册、Doramagic PROJECT_PACK、上游 README、pyproject.toml、GitHub API 快照，以及 2026-07-08 曼谷时间完成的本地 Python 3.9/3.12 安装烟测。