架构全景：一等公民原语
Agents SDK 的设计哲学是「小而明确的表面」。它不试图覆盖所有Agent 模式，而是把最常复用的能力做成一等公民，其余交给用户组合。理解这套原语，是理解其架构的前提。
| 原语 | 角色 | 关键能力 |
|---|---|---|
| Agent | 带指令与工具的 LLM | name、instructions、tools、可选 output_type、handoffs、input/output guardrails |
| Tool | Agent 可调用能力 | 托管工具（WebSearch/FileSearch/Computer/CodeInterpreter）、function_tool、MCP Server、agents-as-tools |
| Handoff | 多智能体委派 | 声明式 transfer_to_ 工具，由模型自主决定切换目标 |
| Guardrail | 输入/输出校验 | input/output/tool 三级；tripwire 触发即中断执行 |
| Runner | 执行循环 | run / run_sync / run_streamed，产出 RunResult |
| Session | 跨轮记忆 | SQLite / Redis / SQLAlchemy(Postgres) 可插拔后端 |
Swarm 原型在 2024 年 10 月验证了「Agent + Handoff」的概念，但缺少 tracing、guardrails 与生产保障。Agents SDK 保留了同样的概念模型，补齐了生产原语：内置追踪、输入/输出护栏、结构化输出、Session，以及清晰的 Runner 抽象。迁移成本因此被压到最低——简单场景主要是 API 改名加 Session/Tracing 初始化，复杂状态才需重写。
Agent 与 Tool：从函数工具到 MCP
Tool 是 Agent 与外部世界交互的边界。SDK 把工具分成几类，工程上对应不同的信任与连接方式：
- 托管工具：WebSearch、FileSearch、Computer、CodeInterpreter 等，由 OpenAI 托管，无需本地代码即可接入。
- 函数工具：用装饰器把任意 Python/TS 函数变成工具；参数 schema 由类型提示（Python）或 Zod（TS）推导，降低手写 JSON Schema 的错误。
- MCP Server 工具：通过 stdio 或 Streamable HTTP 接入任意 Model Context Protocol 服务器；本地传输时由你的运行时持有连接、审批与网络边界。
- Agents-as-Tools：把一个 Agent 包成另一个 Agent 可调用的工具，实现层级委派。
SDK 默认走 OpenAI Responses / Chat Completions，但通过 LiteLLM 可接入 100 多个非 OpenAI 模型而不改应用架构。这意味着它并非「只能调 OpenAI」——这也是它能在企业多模型环境下落地的关键。托管 MCP 适合公开远程服务器，本地/私有 MCP 则把连接与审批留在你的运行时，这是安全边界划分的要点。
Handoff：多智能体委派的运行时
Handoff 是 SDK 多智能体机制的核心。开发者在 Agent 的 handoffs 列表里声明目标 Agent，模型在运行中自行决定何时委派；当模型调用对应的 transfer_to_ 工具时，Runner 切换当前活动 Agent。
其底层实现值得注意：切换时 SDK 会重写对话上下文，让被接管 Agent 只看到与任务相关的历史，而非此前所有 Agent 的每一轮。这一设计避免了上下文爆炸，也是与「把所有 Agent 塞进同一条长上下文」方案的本质区别。
- Handoff 始终发生在同一次 Runner.run 调用内，对调用方透明。
- Input guardrail 只作用于链路中起始的那个 Agent；Output guardrail 只作用于产出最终输出的 Agent。
- 内置 handoff prompt 模板让切换自然语言化，降低模型误判委派时机的概率。
对比而言，CrewAI 偏「角色化多智能体」、LangGraph 偏「图编排」，而 Agents SDK 的 Handoff 更接近「路由器/主管」模式——一个 Triage Agent 把请求路由给 Billing、Support、Sales 等专家 Agent。
Guardrail：与执行并行的校验网
Guardrail 是 SDK 的主要安全机制，本质是一个返回布尔结果的校验函数。它分三个作用域：
| 类型 | 运行时机 | 守护对象 |
|---|---|---|
| input_guardrail | 模型处理用户输入前 | 阻断不良提示抵达模型 |
| output_guardrail | 最终输出到达用户前 | 拦截有害或离题响应 |
| tool guardrail | 函数工具调用前后 | 校验工具入参/出参 |
当 GuardrailFunctionOutput 的 tripwire_triggered 为 true 时，执行立即中止并抛出异常。Input guardrail 默认与模型调用并行执行（也可用 run_in_parallel=False 改为阻塞），Output guardrail 在 Agent 产出后运行（无并行模式）。这种「廉价、快速、可短路」的校验，是构建可信 Agent 的底层骨架。
Session：跨轮持久记忆
多轮对话若每次手动拼接历史，既脆弱又易出错。Session 把对话历史、工具调用结果，以及通过 RunContextWrapper 注入的应用上下文一并持久化，并提供序列化/反序列化。
- SQLiteSession：开发与单进程部署的开箱即用后端。
- Redis：多进程、多实例的共享记忆。
- SQLAlchemy（Postgres）：有高可用要求的生产部署。
开发者也可继承 Session 实现自定义存储。Session 与 Memory 侧产品的区别在于：它解决的是「同一会话跨多次 run 的上下文连续性」，而非跨会话的长期知识沉淀——后者通常交给 RAG 或外部记忆库。
Tracing：内置可观测性
每一次 Agent 运行都会自动产生 Trace，无需额外配置（仅需 API Key）。Trace 是端到端执行的记录，Span 嵌套成树，覆盖：
- LLM 生成（prompt、completion、token 计数）
- 工具调用（函数名、入参、出参、耗时）
- Handoff（来源、目标、原因）
- Guardrail 检查（哪个护栏、结果、耗时）
- 自定义事件（通过 trace 上下文管理器包裹多次 run）
默认发送到 OpenAI Traces Dashboard，也可通过自定义 TraceProcessor 导出到 Datadog、Grafana 等自有可观测栈。需要强调的是：处于零数据保留（ZDR）政策下的组织，向 OpenAI 后端的追踪不可用，必须改用自定义处理器路由到自有目的地。这是金融、医疗等强合规行业的硬性前提。
多数 Agent 框架把 tracing 当作插件或留给第三方，而 Agents SDK 让它免费且默认开启。对生产系统而言，能在一次 run 内看清「模型何时委派、工具为何失败、护栏在哪一步短路」，是排障与后续做评测（eval）的起点。官方建议：先靠 trace 理解单次运行，再把高信号样本喂给评测流程做系统化打分。
与同类框架技术对比
| 维度 | OpenAI Agents SDK | LangGraph | CrewAI | PydanticAI |
|---|---|---|---|---|
| 编程模型 | ReAct 循环 + 委派 | 图（节点 + 边） | 角色化多智能体 | 类型安全优先 |
| 多智能体 | Handoff 一等公民 | 图编排 | 内建 role | 需自行编排 |
| 可观测性 | 内置 Tracing | 需接 LangSmith | 第三方便捷 | 可选 |
| 模型绑定 | 开放（LiteLLM 100+） | 开放 | 开放 | 开放 |
| 典型适用 | OpenAI 原生生产 | 复杂有状态流 | 快速角色协作 | 强类型业务 |
四者并非互斥。实践中常见组合是：用 Agents SDK 写 OpenAI 原生生产链路，用 LangGraph 编排含复杂状态机的长流程，用 PydanticAI 约束对正确性敏感的结构化输出。选型取决于「你的状态有多复杂、模型绑定有多松、对类型有多偏执」。
局限与适用边界
- 不是银弹：SDK 解决的是「循环 + 委派 + 校验 + 观测」的编排层，记忆的跨会话沉淀、评测体系、人工审批流仍需周边工程补齐。
- OpenAI 生态黏性：尽管模型可换，但 Responses API 的新特性（推理模型、Computer Use、File Search）最顺滑的路径仍是 OpenAI 原生。
- ZDR 约束：强合规行业需自建 TraceProcessor，默认后端不可用。
- 长程稳定性：Handoff 链越长，复合错误率越高（行业实测多步任务复合错误率可达三成量级），需配合评测与护栏。
- 评估缺口：可观测性只是起点，从 trace 到可复现评分仍需自建 eval 流水线。