一、总体架构与设计目标

OpenAI Agents SDK 是一个轻量级且功能强大的多智能体工作流框架，具有 provider-agnostic（模型无关）的特性。它同时支持 OpenAI 的 Responses API、Chat Completions API 以及 100+ 其他 LLM 提供商。核心抽象围绕三个概念展开：

• Agent：配置了 instructions（指令）、tools（工具）、guardrails（护栏）和 handoffs（移交目标）的 LLM。
• Runner：负责驱动 Agent 循环、调用模型、执行工具与移交，并产出 RunResult。
• Handoff：允许 Agent 将对话控制权委托给另一个 Agent 的机制。

资料来源：README.md

graph TD
    User[用户输入] --> Runner
    Runner[Runner.run / Runner.run_sync / Runner.run_streamed] --> Loop{Agent 循环}
    Loop -->|调用 LLM| Model[Model 接口]
    Loop -->|执行工具| Tools[Function Tools / MCP / Hosted]
    Loop -->|检测到 handoff| Handoff[Handoff 目标 Agent]
    Loop -->|触发护栏| Guardrails[Input / Output Guardrails]
    Loop -->|完成| Result[RunResult]
    Handoff --> Loop
    Result --> User

二、Agent：核心数据模型

2.1 Agent 的角色

Agent 是 SDK 中最基本的可执行单元。它封装了 LLM 调用所需的全部配置，包括系统提示词、可用工具、可移交目标、输出结构以及护栏。Runner 接受一个起始 Agent，并基于该 Agent 启动循环。

2.2 关键字段

Agent 数据类（src/agents/agent.py）中与核心循环相关的主要字段包括：

资料来源：src/agents/agent.py

2.3 生命周期钩子

RunHooks（定义在 src/agents/lifecycle.py）为外部代码提供观察 Agent 执行过程的钩子。社区中常被引用的请求（如 #252「增强 on_tool_start Hook 以包含工具调用参数」）即与此相关：默认情况下回调已存在，但用户希望更细粒度地控制入参。

from agents import Agent, RunHooks

class MyHooks(RunHooks):
    async def on_agent_start(self, context, agent): ...
    async def on_tool_start(self, context, agent, tool): ...
    async def on_handoff(self, context, from_agent, to_agent): ...
    async def on_tool_end(self, context, agent, tool, result): ...

资料来源：src/agents/lifecycle.py

三、Runner：执行循环的入口

3.1 Runner 的入口点

Runner（src/agents/run.py）对外暴露三个主要方法：

3.2 RunConfig：跨运行配置

RunConfig（src/agents/run_config.py）控制一组 Agent 调用的共享行为，例如：

资料来源：src/agents/run_config.py

3.3 RunContext：每轮运行的状态

RunContext（src/agents/run_context.py）是随 Runner.run(...) 注入到工具、guardrail、动态指令中的泛型上下文对象。它常用于携带以下数据：

• 用户的 user_id、session_id、权限信息。
• 数据库连接、外部服务句柄。
• 跨多个工具调用需要共享的可变状态。

from dataclasses import dataclass
from agents import RunContextWrapper, function_tool

@dataclass
class MyCtx:
    user_id: str
    db: object

@function_tool
async def lookup(ctx: RunContextWrapper[MyCtx], query: str) -> str:
    return ctx.context.db.fetch(query)

资料来源：src/agents/run_context.py

3.4 Runner 循环内部流程

graph TD
    Start([Runner.run 入口]) --> Init[创建 RunContext / 初始化 trace]
    Init --> Turn[开始新轮 Turn]
    Turn --> GuardIn{输入护栏}
    GuardIn -->|失败| Fail[抛出 InputGuardrailTripwire]
    GuardIn -->|通过| Model[调用 Model]
    Model --> Decide{响应中包含}
    Decide -->|tool_calls| ExecTool[并行执行工具]
    Decide -->|handoff_call| ExecHandoff[切换目标 Agent]
    Decide -->|final_output| GuardOut{输出护栏}
    ExecTool --> Turn
    ExecHandoff --> Turn
    GuardOut -->|通过| Done[构造 RunResult 并返回]
    GuardOut -->|失败| OutFail[抛出 OutputGuardrailTripwire]

资料来源：src/agents/run.py

四、Handoffs：Agent 间的控制权转移

4.1 Handoff 的语义

Handoff 是 SDK 中「一个 Agent 将对话控制权移交给另一个 Agent」的机制。一旦 LLM 在响应中产出 handoff_call，Runner 即会：

1. 暂停当前 Agent。
2. 把控制权切换到 Handoff 所指向的目标 Agent。
3. 在新 Agent 上继续执行循环，直到产出 final_output 或下一轮 handoff_call。

重要提示：根据社区反馈（issue #847），当前 handoffs 是「单程票」。一旦 Agent A 移交到 Agent B，控制权默认不会自动回到 A。要实现「返回」必须显式建模（例如让 B 再 handoff 回 A，或使用 agents_as_tools 模式将 B 作为子任务）。

4.2 定义 Handoff

Handoff 对象可通过以下两种方式创建：

from agents import Agent, handoff

billing_agent = Agent(name="Billing", instructions="处理账单问题")
refund_agent = Agent(name="Refunds", instructions="处理退款")

triage_agent = Agent(
    name="Triage",
    instructions="根据用户问题分诊",
    handoffs=[
        billing_agent,
        handoff(
            agent=refund_agent,
            tool_name_override="transfer_to_refunds",
            tool_description_override="当用户明确要求退款时使用。",
            on_handoff=lambda ctx, input: log_event(ctx, input),
        ),
    ],
)

handoff(...) 工厂函数（src/agents/handoffs/handoff.py）支持的参数包括：

资料来源：src/agents/handoffs/handoff.py

4.3 Handoffs vs. Agents as Tools

社区文档中（examples/agent_patterns/README.md）明确区分两种组合方式：

graph LR
    subgraph Handoff模式
        A1[主 Agent] -->|handoff_call| B1[专业 Agent]
        B1 -->|继续控制| A1
    end
    subgraph AgentsAsTools模式
        A2[主 Agent] -->|tool call| B2[子 Agent as Tool]
        B2 -->|返回 result| A2
    end

资料来源：examples/agent_patterns/agents_as_tools.py、README.md

4.4 路由示例

examples/agent_patterns/routing.py 演示了根据用户语言（中文/英文/西班牙文）将请求分诊到不同语言 Agent 的 handoff 模式：

spanish_agent = Agent(name="Spanish", instructions="仅用西班牙语回答。")
english_agent = Agent(name="English", instructions="仅用英文回答。")

triage = Agent(
    name="Triage",
    instructions="根据用户语言 handoff 到对应 Agent。",
    handoffs=[spanish_agent, english_agent],
)

result = await Runner.run(triage, "Hola, ¿cómo estás?")

资料来源：examples/agent_patterns/routing.py

五、RunResult：执行结果

Runner.run(...) 返回 RunResult（src/agents/result.py）。它封装了：

• final_output：最终输出，可能是 str 或 output_type 对应的 Pydantic 模型实例。
• input：本次运行的输入历史（包含所有轮次）。
• messages：模型交互产生的原始消息列表。
• new_items：本次运行中新增的协议项（tool call、tool result、handoff call 等）。
• last_agent：最终控制权所在 Agent。

Runner.run_streamed(...) 返回 RunResultStreaming，可以订阅 stream_events() 以获取 RunItemStreamEvent、AgentUpdatedStreamEvent、RawResponsesStreamEvent 等事件流。

资料来源：src/agents/result.py

六、追踪与可观测性

Runner 启动时，会在内部创建 Trace 与 AgentSpanData/GenerationSpanData 等 span。所有 handoff、tool call、guardrail 都会作为子 span 出现。

• 通过 set_trace_processors(...) 注册自定义导出器（src/agents/tracing/__init__.py）。
• 通过 TracingConfig(api_key=...) 指定与运行 API key 不同的追踪 API key（社区 issue #1437 即与此相关：当导出与运行使用不同 key 时，可能因 OpenAI 平台权限不足而无法加载 trace）。
• 对敏感数据可通过 RunConfig(trace_include_sensitive_data=False) 关闭。
• model_config_for_trace 与 sanitize_url_for_trace（src/agents/models/_trace.py）会从 URL 中剥离认证信息和查询参数后再写入 trace。

资料来源：src/agents/tracing/__init__.py、src/agents/tracing/config.py、src/agents/models/_trace.py

七、模型接口

Runner 通过 Model 抽象与具体 LLM 解耦。src/agents/models/openai_responses.py 实现 Responses API（OpenAI 新接口），src/agents/models/openai_chatcompletions.py 实现 Chat Completions API，而 src/agents/extensions/models/any_llm_model.py 则允许通过 any-llm 接入 100+ 第三方 LLM。

graph TD
    Runner --> Model{Model 抽象}
    Model --> R[OpenAIResponsesModel]
    Model --> C[OpenAIChatCompletionsModel]
    Model --> A[AnyLLMModel / LiteLLMModel / ...]
    R --> API1[Responses API]
    C --> API2[Chat Completions API]
    A --> API3[第三方 LLM]

模型抽象允许在同一应用内为不同 Agent 选择不同后端，并通过 RunConfig.model_provider 统一解析模型名。

资料来源：src/agents/models/openai_responses.py、src/agents/models/openai_chatcompletions.py、src/agents/extensions/models/any_llm_model.py

八、常见模式

8.1 Deterministic（确定性流水线）

将一个任务拆分为多个步骤，每步交给不同 Agent，前一步的输出作为下一步的输入。适合报告生成、流水线式数据处理。

planner = Agent(name="Planner", instructions="生成大纲。", output_type=Outline)
writer = Agent(name="Writer", instructions="根据大纲写作。", output_type=Story)
finisher = Agent(name="Finisher", instructions="续写结尾。", output_type=Story)

async def run(req: str) -> Story:
    outline = (await Runner.run(planner, req)).final_output
    story = (await Runner.run(writer, outline)).final_output
    return (await Runner.run(finisher, story)).final_output

资料来源：examples/agent_patterns/deterministic.py

8.2 Parallelization（并行化）

将可并行的子任务一次性发出，所有子 Agent 同时运行，最后聚合结果。SDK 默认支持并行工具调用，子 Agent 通过 agents_as_tools 暴露后可一并触发。

graph TD
    M[主 Agent] --> T1[子任务 1]
    M --> T2[子任务 2]
    M --> T3[子任务 3]
    T1 --> A[聚合]
    T2 --> A
    T3 --> A

资料来源：examples/agent_patterns/parallelization.py

8.3 Human-in-the-Loop（人机协作）

Runner 支持在工具调用或输出生成时插入人类审批。社区 issue #636（38 条评论）是该领域最高互动量的功能请求，呼吁更系统的「人在回路」架构。SDK 提供了基础：

• InputGuardrail / OutputGuardrail 可在抛错时阻断 Agent 继续运行。
• 工具本身可返回特殊 sentinel（如 ToolUseBehavior）让 Runner 暂停，等待外部输入后再恢复。

资料来源：examples/agent_patterns/human_in_the_loop.py

九、交互式 REPL

src/agents/repl.py 提供了一个命令行 REPL，可直接与 Agent 对话，便于快速调试：

python -m agents.repl
# 或
python -m agents.repl --model gpt-4.1 --agent my_module:my_agent

REPL 在内部使用 Runner.run_streamed(...)，并把流式事件以可读格式打印到终端。它是验证 instructions、handoffs、tools 行为是否如预期配置的最低门槛。

资料来源：src/agents/repl.py

十、已知限制与社区关注

这些限制对设计多智能体应用具有直接影响：在使用 handoffs 编排多 Agent 时，建议结合 agents_as_tools 以避免「回不去」的死胡同；为生产系统设计 RunConfig 时应明确 tracing_disabled 与 trace_include_sensitive_data，并使用与运行 API key 匹配的 TracingConfig（或显式不同 key 但属于同一组织）。

十一、配置速查表

十二、参见

• 工具系统（Function Tools / Hosted Tools / MCP）：参见 Tools 与 MCP 集成
• 追踪与导出器：参见 追踪与可观测性
• 实时语音 Agent：参见 Realtime Agents
• 沙箱 Agent（Sandbox Agents）：参见 Sandbox Agents
• 多 Agent 编排模式：参见 Agent 模式

下一步建议：阅读完本页后，建议继续阅读《Tools 与 MCP 集成》以理解 Agent.tools 与 Agent.handoffs 之间的区别与组合策略。

工具、函数架构、MCP 与模型提供者

本页系统性地介绍 OpenAI Agents Python SDK 中四大相互关联的子系统：工具（Tools）、函数架构生成（Function Schema）、模型上下文协议（Model Context Protocol, MCP） 与 模型提供者（Model Providers）。这些子系统共同决定了 Agent 能够调用什么、以何种方式调用，以及底层由哪个 LLM 提供者执行推理与生成。

1. 子系统在整体架构中的位置

下图为 SDK 运行时从用户输入到模型响应的核心数据流，凸显工具、函数架构、MCP 与模型提供者之间的协作关系。

graph TD
    A[用户输入 / 消息] --> B[Agent 循环]
    B --> C{选择模型提供者}
    C -->|OpenAI Responses| D1[OpenAIResponsesModel]
    C -->|OpenAI Chat Completions| D2[OpenAIChatCompletionsModel]
    C -->|LiteLLM / 第三方| D3[LitellmModel]
    D1 --> E[LLM 返回 Tool Call]
    D2 --> E
    D3 --> E
    E --> F{工具派发}
    F -->|FunctionTool| G1[@function_tool 装饰器]
    F -->|HostedTool| G2[WebSearch / FileSearch / CodeInterpreter]
    F -->|MCPServer| G3[MCP Manager / Server]
    G1 --> H[function_schema 生成 JSON Schema]
    G3 --> I[MCP util 工具过滤与列表]
    H --> J[工具结果返回模型]
    I --> J
    J --> B

资料来源：src/agents/tool.py、src/agents/models/interface.py、src/agents/mcp/manager.py。

概述

OpenAI Agents SDK 在智能体执行生命周期内提供四个相互关联的横切能力：Sessions（会话）、Memory Backends（记忆后端）、Guardrails（防护栏） 与 Tracing（追踪）。它们共同决定了智能体如何维持跨轮次上下文、如何强制执行安全策略，以及如何在生产环境中观测与排查智能体的运行行为。

• Sessions 定义了"对话历史"的抽象，是智能体与持久化层之间的接口。
• Memory Backends 是 Session 协议的具体实现，覆盖本地文件、关系数据库、远程 KV 以及 OpenAI 托管的对话/响应服务。
• Guardrails 在智能体输入与输出处插入可配置的检查点，可以阻断不安全内容、修改结果，或对工具调用进行二次校验。
• Tracing 提供统一的 OpenTelemetry 风格 Span/Trace 模型，让 LLM 调用、工具执行、防护栏与转交过程都可被采集、导出与回放。

graph TD
    U[用户输入] --> A[Agent 运行循环]
    A --> S[Session/Memory]
    S -->|历史消息| A
    A --> G1[输入 Guardrails]
    G1 --> M[模型调用]
    M --> G2[输出 Guardrails]
    G2 --> TG[Tool Guardrails]
    TG --> A
    A --> T[Tracing: Spans & Trace]
    T --> P[TraceProcessor 后端]

资料来源：src/agents/tracing/__init__.py:9-72、src/agents/guardrail.py、README.md

Sandbox Agents、Realtime Agents 与 Voice Pipeline

1. 概述

OpenAI Agents SDK 在传统 Agent 之上提供了两类专用执行形态：Sandbox Agents（沙盒智能体）与 Realtime Agents（实时语音智能体），二者分别面向"长时任务、需要隔离工作区"以及"低延迟、多模态语音交互"两大典型场景。Voice Pipeline 则是 Realtime Agents 在实际部署中的端到端编排形态。三者共享同一套核心抽象（Tools、Handoffs、Guardrails、Sessions、Tracing），但在执行容器、连接方式与生命周期管理上有显著差异。

资料来源：README.md:1-20

官方在 src/agents/realtime/README.md:3-5 中明确说明：Realtime agents 当前为 beta，未来几周内可能存在破坏性变更。Sandbox Agents 则随 v0.17.x 系列迭代快速演进，社区对扩展后端（如 OpenShell）有持续呼声。

Pitfall Log / 踩坑日志

项目：openai/openai-agents-python

摘要：发现 18 个潜在踩坑项，其中 11 个为 high/blocking；最高优先级：安装坑 - 来源证据：Hook point for eager tool dispatch (overlap tool execution with model streaming)。

1. 安装坑 · 来源证据：Hook point for eager tool dispatch (overlap tool execution with model streaming)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Hook point for eager tool dispatch (overlap tool execution with model streaming)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3404 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Provide stable public access to the underlying function on `FunctionTool`

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Provide stable public access to the underlying function on FunctionTool
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3381 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：BUG: TypeError crash when function parameter is named 'model_config'

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: TypeError crash when function parameter is named 'model_config'
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3547 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Realtime API with Multiple Tool Calls Results in No Voice Output

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Realtime API with Multiple Tool Calls Results in No Voice Output
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/1168 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：Realtime known tool failures (exception/timeout) do not send model-visible output

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Realtime known tool failures (exception/timeout) do not send model-visible output
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3356 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：RealtimeAgent traces contain no spans (empty traces on dashboard)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RealtimeAgent traces contain no spans (empty traces on dashboard)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/1845 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 能力坑 · 来源证据：Support automatic "back" handoffs to orchestrating Agents

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Support automatic "back" handoffs to orchestrating Agents
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · 来源证据：Error "Item ‘rs_ABCD’ of type ‘reasoning’ was provided without its required..." when using CodeInterpreter

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Error "Item ‘rs_ABCD’ of type ‘reasoning’ was provided without its required..." when using CodeInterpreter
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/985 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：Fail to load traces when using a different API key for tracing

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Fail to load traces when using a different API key for tracing
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/1437 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：Read `_meta` from MCP Tool Call Responses

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Read _meta from MCP Tool Call Responses
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3477 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：feat: add OpenShell sandbox provider extension

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: add OpenShell sandbox provider extension
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/openai/openai-agents-python/issues/3468 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 openai-agents-python 与安装入口 openai-agents 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：pip install openai-agents
• 证据：identity.distribution | github_repo:946380199 | https://github.com/openai/openai-agents-python | repo=openai-agents-python; install=openai-agents

13. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:946380199 | https://github.com/openai/openai-agents-python | README/documentation is current enough for a first validation pass.

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium

16. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:946380199 | https://github.com/openai/openai-agents-python | no_demo; severity=medium

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:946380199 | https://github.com/openai/openai-agents-python | release_recency=unknown