采用 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 200PROJECT_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.0Python 要求 3.10依赖包括 openai2.36.0,低于 3、pydantic2.12.2,低于 3、requests、websockets 和 mcp1.19.0,2。可选 extras 覆盖 voice、realtime、redis、SQLAlchemy、Dapr、MongoDB、多种 sandbox/provider 集成等。本地烟测暴露了一个很实际的采用边界macOS 默认 python3 是 3.9.6安装 openai-agents0.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 boundaryagent 能调用哪些工具哪些工具只能读哪些工具能写- Handoff ownerhandoff 后谁对最终输出负责原 agent 是否还能继续改写- Session scopesession 是 user、task、workspace 还是 run 级别- Guardrail actionguardrail 失败时是拒绝、重试、降级、人工确认还是写入事故日志- Trace retentiontrace 保存多久谁能看是否包含用户隐私或密钥片段- Sandbox permissionsandbox 能读哪些目录能否联网能否执行 shell能否写回仓库- Human approval哪些动作必须人工确认例如发帖、删文件、付款、发邮件、修改生产配置- Recovery rulerun 中断后从哪里恢复是否允许复用上一次 tool 输出。没有这些规则SDK 也只能帮你更快地制造不可解释的 agent 行为。## Sandbox Agent 的价值和风险README 中的 Sandbox Agents 是一个重要信号。它把 agent 从“回答问题”推进到“在一个可控计算环境里做事”。这对代码阅读、命令执行、补丁生成、长任务状态保持很有用。但 sandbox 不等于安全。它只是把风险集中到一个边界里边界本身仍然需要设计。第一轮 sandbox 试验我不会连接真实仓库写权限。更合理的顺序是1. 只挂载只读 demo repo让 agent 总结 README 和文件结构2. 允许在临时目录里生成文件但不允许写回原仓库3. 允许跑测试但记录命令、退出码、stdout/stderr4. 允许生成 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 primitivestools、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 安装烟测。