OpenAI Agents SDK 全攻略：OpenAI 官方多步 Agent 编排框架

为什么需要 OpenAI Agents SDK：从单次调用到多步编排

传统方式构建多步 Agent 需要自己实现 agent loop：写 while 循环反复调 LLM、解析 tool_calls 参数、把工具结果拼回上下文、判断何时终止；同时还要自己维护多轮上下文（截断、持久化）、做输入合法性校验、打印日志排查问题。这些代码工程量大，且边界 bug 集中——工具参数解析失败、上下文超出窗口、重试策略缺失，任何一个环节出错都会让线上 Agent 表现不稳定。Swarm 验证了 handoff 模式但明确定位为教学实验，不具备生产条件。

OpenAI Agents SDK 把上述能力内置为原语。agent loop 由框架执行：模型自动决定调用哪些工具，循环直到不再请求工具或达到 max_turns；Handoff 把「将控制权交给另一个 Agent」封装成一次工具调用；Guardrail 在输入进入主流程前与输出生成后执行校验函数，可中断并移交；Session 负责多轮记忆与持久化；Tracing 默认上报 OpenAI 平台，可查看 span 树、耗时与 token 用量。由于是官方维护，新模型能力（如 Responses API 工具、托管工具）能第一时间获得支持。

与同类工具相比，它不要求你像 LangGraph 那样手写状态图，也不像 AutoGen 那样强调多 Agent 自由对话，而是提供「最贴近 OpenAI 官方最佳实践」的极简原语：默认配置即可生产运行，学习成本低，适合以 OpenAI 模型为核心的团队快速落地。

安装与环境配置：3 步就绪

步骤一：安装。要求 Python 3.9+，安装主包 openai-agents。注意 import 名是 agents 而不是 openai-agents。可选安装 LiteLLM 扩展（用于接第三方模型）。

步骤二：配置 API Key。设置环境变量 OPENAI_API_KEY，或在代码中调用 set_default_openai_api_key("sk-...")。如需指向 OpenAI 兼容网关，可通过自定义 client 并传入 base_url 实现，但托管工具与部分高级特性仅对官方端点可用。

步骤三：验证安装。导入 agents 包并确认版本可加载，无 API Key 时仅做 import 检查，不发起网络请求。

# 1. 安装（含可选 LiteLLM 扩展）pip install openai-agentspip install 'openai-agents[litellm]'   # 可选：接第三方模型 # 2. 配置 API Keyexport OPENAI_API_KEY="sk-..." # 3. 验证导入python -c "from agents import Agent, Runner; print('import ok')"

快速上手：10 分钟跑通一个工具调用 Agent

最小可用流程的思路：一个带工具的 Agent 即可演示完整 agent loop——写一个普通 Python 函数、用装饰器挂到 Agent、运行 Runner、读取结果。下面用天气查询演示「模型决定调用工具→拿到结果→生成回答」的完整路径。

1. 新建 agent_demo.py，从 agents 导入 Agent、Runner、function_tool。

2. 定义 get_weather(city) 函数并加 @function_tool：函数名即工具名，docstring 即工具描述，类型注解自动生成参数 schema。

3. 创建 Agent 实例：name 用于追踪，instructions 写清行为，tools 传入函数列表。

4. 在 async 函数内调用 await Runner.run(agent, "北京今天天气怎么样？")。

5. 打印 result.final_output；再打印 len(result.items) 观察执行步骤数，可以看到消息、工具调用、工具结果等多个 item。

代码示例：

运行需要有效的 OPENAI_API_KEY。执行时日志中会出现两次模型调用：第一次请求工具，第二次基于工具结果生成回答。若模型未调用工具，通常是因为指令不够强，在 instructions 中强调「必须先用工具查询」即可。进阶技巧：result.items 列出每一步的消息与工具执行记录；改用 Runner.run_streamed 可拿到流式事件；默认 Tracing 开启时，可在 OpenAI 平台 Logs 页看到本次运行的完整调用链。

import asynciofrom agents import Agent, Runner, function_tool @function_tooldef get_weather(city: str) -> str:    """查询指定城市的当前天气，返回天气与温度。"""    return f"{city}：晴，25℃，东北风2级"  # 演示数据，生产请替换为真实天气 API async def main():    agent = Agent(        name="Weather Assistant",        instructions="你是天气助手。用户问天气时，必须先用 get_weather 工具查询再回答。",        tools=[get_weather],    )    result = await Runner.run(agent, "北京今天天气怎么样？")    print("最终回答：", result.final_output)    print("执行步骤数：", len(result.items)) if __name__ == "__main__":    asyncio.run(main())

核心能力详解：5 大支柱

支柱一·Agent 与函数工具：从「单次生成」到「自主循环」。 Agent 是核心对象：instructions 定义行为，tools 挂载函数工具，model 指定模型（默认 OpenAI Responses API 模型），name 用于追踪。@function_tool 装饰器把普通 Python 函数自动转成工具 schema，省去手写 JSON Schema 的步骤。运行时框架自动完成「调用 LLM→解析工具调用→执行→回填结果→再次调用」的循环，直到完成或达到轮次上限。跨厂商需求可用 agents.extensions.litellm.LiteLLMModel 接第三方模型，但托管工具仅在 OpenAI 模型下可用。

支柱二·Handoff：多 Agent 分工基于控制权移交。 handoff(agent) 生成一个特殊工具，父 Agent 决定移交时调用它；子 Agent 执行完后，控制权连同结果一起交还父 Agent，父 Agent 继续推理。这使得「主管—专员」分层成为天然编程模式：主管只做意图判断，专员各持少量工具。可用 input_filter 过滤移交内容（如只传结构化摘要），内置 remove_all_tools 等过滤器。目标 Agent 也可以继续 handoff 给更细的专员，形成多级路由。

支柱三·Guardrail：输入输出两侧的拦截点。 InputGuardrail 在主 Agent 首轮执行前运行校验函数，OutputGuardrail 在最终输出生成后校验。校验函数是普通 Python 函数，返回 GuardrailFunctionOutput(output_info, tripwire_triggered)；触发 tripwire 后可指定 tripped_handoff 把对话移交给另一个 Agent（如转人工）。校验逻辑可以是规则、LLM 判断或外部 API 检查。规范上禁止在护栏函数内再调用挂同一护栏的 Agent，否则会递归。

支柱四·Session：多轮记忆的持久化抽象。 Runner.run 每次都是独立事件流，要支持「接着上次聊」需传入 session。SDK 用 Session 存对话消息，抽象出 SessionStorage 接口负责读写；内置 SQLiteSessionStorage，默认会话存储写入本地 SQLite。生产环境可实现自定义 SessionStorage 接 Redis/Postgres 等共享存储，多实例横向扩展时保证同一用户读到同一上下文。会话裁剪策略（保留最近 N 条）需按业务自行配置。

支柱五·Tracing：全链路可观测。 默认 OpenAITracingProcessor 把 span 上报 OpenAI 平台，在 Logs 页可查看每个 Agent 运行、每次工具调用的调用树、耗时与 token 统计。生产环境可用 add_trace_processor 接入自定义 TracingProcessor，或通过 RunConfig(tracing_disabled=True) 关闭默认上报；workflow_name 与 group_id 用于把 trace 归类到业务线与会话组，便于按维度检索。

生产部署与监控：从上线到运维

部署方式一·异步 HTTP 服务。 将 Agent 封装在 FastAPI 等异步框架中，async 路由函数内 await Runner.run(agent, input)。注意并发控制：OpenAI 接口有 RPM/TPM 限流，用 asyncio.Semaphore 限制并发数，并为单次 run 设置整体超时。每个请求应使用独立的 session，不要全局复用同一个会话对象，避免用户上下文串扰。

部署方式二·队列化长任务。 报告生成、批量审核等分钟级任务走任务队列（如 ARQ、Celery）。worker 内可复用 Agent 对象（Agent 是无状态定义），关键是 SessionStorage：默认 SQLite 存本地文件，多 worker/多副本部署时必须换成 Redis/Postgres 等共享存储。用 RunConfig(workflow_name="xxx", group_id=user_id) 给 trace 打标签，便于按业务线检索调用链。

可观测性。 默认 Tracing 已启用并上报 OpenAI 平台，开发期强烈建议保留，可直接在 Logs 页排查「哪一步耗时高、哪次工具调用返回异常」。生产环境若数据不允许出网，用 set_tracing_disabled(True) 关闭默认上报，再实现自定义 TracingProcessor 接入 OpenTelemetry 或自建日志体系；将 trace_id 透传到业务日志，实现端到端关联。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>agent loop 不是无限的：Agent 默认 max_turns=10，达到上限即停止并返回当前结果。长链路多级 handoff 任务需显式调大该值，否则结果被截断，表现为「答到一半就停」。</li><li>Runner.run 是协程：同步脚本用 Runner.run_sync，async 函数内用 await Runner.run；直接调用会得到未等待的协程对象。Notebook 中需用 asyncio.run 包裹，二者混用会报 RuntimeError。</li><li>会话跨实例问题：默认 SQLite 是本地文件，容器多副本部署时每个副本各有独立会话，用户请求落到不同实例会「失忆」。上线前务必替换为共享 SessionStorage。</li><li>托管工具依赖 Responses API：WebSearch/FileSearch 在服务端执行，仅随默认 Responses API 可用；切换到 Chat Completions 模型（OpenAIChatCompletionsModel）或 LiteLLM 第三方模型后这些工具不可用，需改自定义检索工具。</li><li>护栏函数防递归与超时：护栏函数内再调用挂同一护栏的 Agent 会无限循环；校验函数若依赖外部 LLM 判断，必须设置超时与重试，否则会拖慢整个请求链路。</li></ul>

版本迭代

OpenAI Agents SDK 前身为 2024 年 10 月开源的实验框架 Swarm（明确标注仅用于教学演示）；2025 年 3 月 11 日，OpenAI 在发布「New tools for building agents」时正式推出生产级 Agents SDK v0.1.0，在 Swarm 的 Handoff 思路之上补齐 Guardrail、Session、Tracing 等工程能力，此后保持高频 0.1.x 补丁迭代（截至训练数据，可能已有更新版本；正式版本号以 GitHub Releases/Changelog 为准）。

AI 应用场景

常见误区

面试题