采用 OpenAI Agents SDK 之前，先写运行契约

OpenAI Agents SDK 很容易被误读成“更快搭多 Agent”。这个理解太浅。真正值得评估的地方，是它把 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 runtime。

不要从多 Agent 开始

多 Agent 最容易制造一种错觉：把任务拆给多个角色，系统就更专业。工程上经常相反。角色越多，越需要明确状态归属、工具权限、handoff 条件、失败恢复、trace 证据和最终责任人。

我会先只建一个 agent，而且只给它一个低风险工具。这个工具要满足三个条件：

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

这个最小 agent 跑通以后，再加第二个 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 试验我不会连接真实仓库写权限。更合理的顺序是：

1. 只挂载只读 demo repo，让 agent 总结 README 和文件结构；
2. 允许在临时目录里生成文件，但不允许写回原仓库；
3. 允许跑测试，但记录命令、退出码、stdout/stderr；
4. 允许生成 patch，但由人工或 CI 决定是否应用；
5. 最后才讨论是否给 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 安装烟测。