openai/openai-agents-python¶
仓库：openai/openai-agents-python
这个项目在系统里负责哪一层¶
这个项目负责的是 Agent runtime。它解决的不是“模型怎样多调几次函数”，而是“多步执行、工具调用、会话状态、人工审批和 trace 应该怎样被组织成正式运行时”。
如果你把 Agent 理解成“大一点的 prompt”，这个项目会直接把这个想法推翻。它把 Agent 相关复杂度拆成一组明确对象，而不是藏在几段提示词里。
先抓整体结构¶
最值得先抓的是这些对象：
Agent：定义角色边界、模型配置和可用能力。Tool：把外部能力接进运行时。Session：保存会话状态，不让历史散落在 UI 和 handler 里。Guardrails：在运行时补边界，不让模型建议直接变成动作。Tracing：把多步执行变成可回放的链路。Handoff：让不同 Agent 之间的交接成为正式动作。
只要这几个对象分开，你就会明白官方在做的是 runtime，而不是 prompt 模板集合。
一条典型执行链¶
一条多步执行大致会这样跑：
- 运行时拿到用户输入，并加载当前 session。
- 当前 Agent 根据角色、工具和状态决定下一步。
- 如果需要工具，运行时发起工具调用，并把结果写回状态和 trace。
- 如果需要切换角色，就通过 handoff 把控制权交给另一个 Agent。
- 如果命中 guardrail 或高风险动作，就进入审批或人工介入。
- 满足停止条件后返回结果，并把状态留给下一轮续接。
这条链最值钱的地方在于，它把“查工具”“切角色”“停下来让人确认”都当成了运行时里的正式事件，而不是散落在业务代码里的临时分支。
值得学的设计¶
这个仓库最值得学的有三点。
第一，handoff 和 agent-as-tool 被明确分开。前者是角色交接，后者是能力复用，二者在上下文隔离、控制权和结果形态上都不是一回事。第二，Session 被放在主路径里，说明官方默认多步系统必须有正式状态对象。第三，Tracing 不是附属功能，而是运行时必需品，因为没有 trace，多步执行一旦偏掉就很难复盘。
这些设计放到企业系统里非常实用。比如一个企业助手可能先由“资料检索 Agent”找制度，再把结果交给“业务执行 Agent”决定是否继续操作。这里最难的不是角色名字，而是交接时谁保留控制权、谁继承哪些状态、哪一步需要人确认。
适合借回自己项目的点¶
- 把 agent、tool、session、trace 这些边界显式化。
- 把人工确认做成正式节点，而不是临时
if分支。 - 把会话状态放进运行时对象，而不是前端顺手传来的聊天记录。
- 把角色切换、能力复用和工具调用分开建模。
不要照抄的地方¶
- 不要把 guardrails 当成权限系统本身。真正的权限还是要靠服务端兜。
- 不要因为框架支持 handoff，就默认系统应该上多 Agent。
- 不要忽略只读工具和高风险写工具在治理上的差别。运行时支持能力，不等于风险已经消失。