OpenAI官方多步Agent SDK实战开发指南

可视化演示

动态演示OpenAI官方多步Agen的核心机制，通过概览/流程/对比/趋势四种模式展示关键概念与交互流程。

智能体认知

普通聊天机器人像一位只会背菜谱的解说员：你把订单念给他，他能流利地复述“这道菜要先焯水再爆炒”，但绝不会碰一下锅铲。而多步 Agent 是真正上岗的主厨——他看完订单，会自己规划“先备菜、再热锅、依次下料、试味装盘”，然后真的一步一步把菜做出来。

在 OpenAI Agents SDK 的世界里，一个 Agent 对象就是这位“会动手的主厨”。它由四件套组成：模型是大脑，负责理解与决策；指令是后厨手册，规定做事风格与边界；工具是厨具清单，让它具备“干活”的能力；上下文是订单便签，记录当前一切已知信息。所谓“多步”，指的是模型在给出最终回答之前，可以反复经历“思考→调用工具→拿到结果→再思考”的内部循环。

SDK 的核心编程模型是把 Agent 声明为一个对象，再把执行交给 Runner。你不需要手写循环去拼 prompt，框架会在内部自动维护“工具调用→结果回填→继续推理”的循环，直到模型认为信息足够、输出最终答案。这也是它与普通 Chat 接口本质上的区别：Chat 接口默认一步到位，Agent 则允许“多走几步”。

所以别再让 AI 当“只会背菜谱的解说员”了。用 SDK 定义出模型、指令、工具、上下文这四件套，你的应用就从“能聊”进化成了“会干活”，这正是多步 Agent 的第一课。

环境快速搭建

新餐厅开业，第一件事不是招厨师，而是给后厨通水通电、买齐锅碗瓢盆。没有这些基础，再好的手艺也施展不开。对开发者来说，装好 SDK、配好密钥，就是给这间“AI 后厨”完成开荒。

安装过程只有一行命令：写代码前先在你的 Python 环境里执行 pip install openai-agents。接着配置环境变量 OPENAI_API_KEY，相当于给厨房办一张“供应商通行证”，模型服务才会响应你的请求。最后确认网络能访问 OpenAI 接口，就像确认食材供应链畅通。

搭好环境后，可以立刻写一个最小 Agent 验证链路：只给一个 name 和一段 instructions，用 Runner.run() 跑一句“你好”，能返回内容就说明厨房通水通电了。这个最小原型虽然还不会用工具，但它已经是一个合法的多步 Agent——你随时可以把工具和更复杂的指令加进去。

厨房通了水电气，主厨才能上岗。环境这一关看似琐碎，却决定了后面所有代码能不能跑起来——记住，先让“最小可用厨房”转起来，再逐步加设备。

Agent定义配置

主厨上岗前，老板会递上一份《本店手册》：口味偏淡、“不要香菜”必须划重点、上菜不得超过十五分钟。这份手册决定了主厨做事的方式。在 SDK 里，它对应的就是 instructions 参数。

定义一个 Agent 通常是这样：给它起个名字、写清楚指令、选一个模型、挂上工具列表。指令的质量几乎直接决定多步执行的成败——你想让它先查库存再报价，就把这个顺序写进手册；你想让它语气简洁，也在手册里注明。

模型选型方面，复杂推理任务适合 gpt-4o 系列，追求成本和速度可以用 gpt-4o-mini；此外还能调整 temperature 等参数，控制回答的随机性——好比规定主厨“按标准菜谱走，不许自由发挥”。SDK 把这些都收敛成 Agent 构造函数的参数，改动一行就能更换一个“人设”。

手册写得好，主厨才不跑偏。Agent 定义阶段花十分钟打磨 instructions，往往比后面调试十次工具调用更有效——这是所有多步 Agent 项目的“免费杠杆”。

工具函数开发

厨房里每样工具都贴着一张说明卡：名称“切片刀”、用途“处理食材”、用法“请递入菜名”。模型读卡之后，就能判断此刻要不要用这个工具、参数该怎么填。这张卡做得越清楚，工具被正确调用的概率越高。

SDK 提供了 @function_tool 装饰器：你只要写一个普通的 Python 函数，加上类型注解和 docstring，SDK 就会自动把它翻译成模型能读懂的“说明卡”（JSON Schema）。函数名就是工具名，docstring 就是用途说明，参数注解就是填卡模板。

调用过程同样顺滑：模型在推理中说“我要调用 query_stock_price，参数 AAPL”，Runner 就真的去执行这个函数，把返回值（普通字符串即可）追加到上下文，交回给模型继续推理。工具返回“未收录该股票”这类兜底文案时，模型往往还会换个参数重试——这正是多步循环的魅力。

好工具要“单一职责”：一把刀只负责切菜，一个工具只干一件事。把工具设计得简单、说明写得清楚，主厨（模型）才能像用自家厨具一样顺手，这是整个 Agent 能力的天花板。

多步执行流程

做佛跳墙不可能一锅端：要泡发、焯水、炖煮、收汁，每完成一步还得看看火候对不对，不行就调整。多步 Agent 的执行过程也是如此——它不是在“写答案”，而是在“做任务”。

这一切由 Runner 驱动。Runner.run(agent, input) 一发出，内部就开启循环：模型判断要不要调用工具，需要就输出调用指令，Runner 执行工具并把结果回填，再让模型继续想；直到模型认为信息足够，才输出最终回答，整个过程结束。这就是多步执行的核心机制。

结果追踪方面，运行结束后可以从 Result 对象里拿到 final_output（最终回复）、last_agent（最后负责的 Agent）等字段；如果接入流式事件，还能实时看到每一步的工具调用记录，像透过后厨玻璃看主厨做菜一样。

多步执行把“一道大菜”拆成“一道道工序”，每一步的结果都成为下一步的输入。理解了这条循环链，你就掌握了 Agent 从“想”到“做”的引擎——后面所有复杂编排都建立在这条循环之上。

上下文管理

后厨的备忘板上贴满便签：订单最初只有一句“宫保鸡丁”，中途又贴上新备注“不要花生”，旁边还挂着刚才查到的“鸡胸肉库存不足”。主厨每做一步都要瞄一眼板子。对 Agent 来说，这块板子就是上下文。

SDK 里每次 Runner.run 都是独立会话，相当于一张新订单，不会自动继承上一单的便签。如果你希望 Agent“记得”之前的对话，需要显式地把历史消息传进去，或者使用持久化能力把状态存到外部。默认“不记忆”不是缺陷，而是把控制权交还给开发者。

更精细的状态管理可以用 RunContextWrapper：工具函数可以通过它读取和写入上下文数据，比如用户身份、订单编号、中间计算结果。这套机制相当于给主厨配了个“随身笔记本”，写什么、什么时候擦掉，都由你决定。

上下文串起了多步 Agent 的整个生命周期：上一轮的工具结果、用户的隐含偏好、系统的固定守则，全都在这块“备忘板”上汇合。善用上下文，你的 Agent 才能像老主厨一样“心里有数”。

编排与协作

大餐厅不会只靠一个主厨：热炒间、凉菜间、甜品间各司其职。主厨看到订单是生日蛋糕，喊一声“甜品组接单”，就把这单转了出去。在 SDK 里，这个动作叫 handoff（交接）。

实现交接非常简单：在 Agent 的 handoffs 参数里列出可交接的其他 Agent，模型会根据当前请求的意图，自动决定是留下来亲自处理，还是把整段会话转给更合适的专家。一个典型的架构是“三明治”：派一个调度 Agent 接单，按问题类型分发给不同的专家 Agent，每个专家只负责自己那摊事。

子 Agent 是另一种协作形态：主 Agent 可以把一个子任务“委派”给子 Agent，拿到它的输出后继续自己的工作。当你需要 Agent 同时具备“总览全局”和“深耕细节”的能力时，这种主从结构比把所有逻辑塞进一个 Agent 思路清晰得多。

单个主厨再强也有上限，团队协作才能应付满堂客人。多 Agent 编排让你把复杂业务拆给多个“专精主厨”，各管一摊、随时交接——这也是多步 Agent 从玩具走向生产的必经之路。

AI 应用场景

Python 演示

import asyncio from agents import Agent, Runner, function_tool  @function_tooldef query_stock_price(symbol: str) -> str:    """查询指定股票代码的最新成交价, 返回字符串形式的价格"""    prices = {"AAPL": "190.20 美元", "MSFT": "420.30 美元", "TSLA": "248.50 美元"}    return prices.get(symbol.upper(), "未收录该股票")  @function_tooldef calc_roi(cost: float, current: float) -> str:    """根据买入成本与当前价格计算投资回报率, 返回百分比字符串"""    roi = (current - cost) / cost * 100.0    return f"回报率 {roi:.2f}%"  async def main() -> None:    analyst = Agent(        name="股票分析师",        instructions="先用 query_stock_price 查最新价, 再用 calc_roi 算收益, 最后给出投资结论",        model="gpt-4o-mini",        tools=[query_stock_price, calc_roi],    )    result = await Runner.run(analyst, "我 180 美元买入 AAPL, 现在赚了多少?")    print(result.final_output)  if __name__ == "__main__":    asyncio.run(main())

1. from agents import Agent, Runner, function_tool导入 SDK 三大件，对应主厨、传菜员和厨具注册表。
2. @function_tool把普通 Python 函数注册成模型可调用的工具。
3. def query_stock_price(symbol: str) -> str:类型注解帮助 SDK 生成参数模板，模型据此填参数。
4. prices.get(symbol.upper(), "未收录该股票")命中返回价格，没命中给兜底文案，模型会据此换参数重试。
5. instructions="先用 query_stock_price 查最新价..."在多步执行中引导工具调用顺序，像后厨手册一样。
6. Runner.run(analyst, ...)启动多步执行循环，直到模型不再需要工具为止。

常见误区

面试题