先说个背景很多人看到OpenAI Agents SDK第一反应是又来一个框架。我在过去一年多里被Assistants API、GPTs、Function Calling轮番折腾过最早看到SDK名字时也很不耐烦。但真正把官方文档和源码过了一遍之后我发现这次跟以前不太一样——它把智能体这个被玩烂的词重新拆成了几个非常干净的原语Agent、Handoff、Guardrail、Session、Dependencies。这篇文章是我自己从零上手、踩坑、再回头重构的全过程记录适合已经写过Function Calling或Assistants API、但对多智能体编排还停留在概念阶段的开发者。我会先讲清楚为什么它值得学再带你一起搭一个能跑的客服多智能体系统。1. 为什么OpenAI又掏出一套新框架从Assistants API到Agents SDK的迁移逻辑1.1 Assistants API时期的最大痛点如果你是从2023年底开始接触OpenAI接口应该还记得Assistants API刚发布时大家有多兴奋——终于不用手动维护对话历史、不用自己拼工具调用逻辑了。但实际用上半年就会发现几个很难绕开的问题。最让人头疼的是单体僵化。Assistants API的核心抽象是Thread也就是一条线程所有消息都在这条线程里排队。你想要一个前台客服能判断问题、然后把复杂售后转给另一个售后专家在Thread模型里只能自己写路由逻辑先让A模型判断意图再拿着整段上下文去调B模型还得处理两个模型之间可能出现的状态错乱。你相当于在框架外面自己造了一套调度系统而框架本身只负责保存消息和触发运行。第二个痛点是工具调用和对话主循环揉在一起。Assistants API里工具调用结果、用户消息、助手回复全都混在同一个消息列表里你很难清晰地判断这一轮模型是不是被工具结果带偏了。尤其当工具多了之后模型会在一次运行里连续调用七八个工具出错时你连日志都看不太明白。第三个痛点是防护能力几乎没有。如果你想在用户输入进入模型之前先做一轮敏感词过滤在Assistants API里只能先自己调一个校验接口再决定要不要创建Run。这个流程不是不能做但它不是框架的一等公民导致很多团队做着做着就放弃了最后只在主指令里写你要拒绝违规请求——效果可想而知。1.2 Agents SDK的设计思路转变OpenAI这次把整套体系推倒重来核心转变是把助手这个概念拆成了更细的原语。官方文档里有一句话我印象很深Agents SDK并不是一个多Agent聊天框架而是一组让AI应用变得可控、可测试、可观测的工具。它的几个关键设计决策是Agent不再绑定Thread而是绑定一组指令、模型、工具、防护栏和交接目标。交接Handoff变成了一等公民控制权可以在多个Agent之间显式转移。Guardrail独立于主循环运行可以在每一轮输入和输出上做强制检查。Session负责持久化把上下文存储从Agent对象里解耦出来。这种设计其实很像人类组织里的角色卡加工单系统每个Agent是一张写清楚职责的工牌交接就是把工单连人带上下文一起转给下一个环节Guardrail是门口的安检闸机。你听到这个名字时别再把它当成一个聊天机器人框架它是一个流程编排框架。1.3 版本现状与生态信号Agents SDK的Python和TypeScript版本在2025年上半年已经发布了正式版v0.1.0API比之前的预览版稳定很多。更值得关注的是OpenAI联合Google、Anthropic、Cognition等团队提出的Agents Authority这个互操作提议它试图统一Agent事件流、会话存储、工具调用这些通用概念。也就是说你今天用Agents SDK写出来的应用逻辑未来理论上也能跑在Anthropic或Google的框架上。这也是我写这篇指南的第一个理由它不只是OpenAI私有的SDK它在往行业通用抽象层的方向走。现在花时间吃透这套原语比反复踩各个厂商私有接口的坑更划算。2. 上手前必须搞懂的5个核心概念Agent、Handoff、Guardrail、Session、Dependencies在写第一行代码之前我建议你先花二十分钟把下面这五个词搞明白。它们的命名和含义并不复杂但我见过太多人拿着Agent就开始写结果Handoff、Guardrail完全是摆设。概念一句话解释类比容易犯的错Agent一组指令模型工具防护栏的集合代表一个可运行的角色工牌把Agent当会话用塞大量历史消息进去Handoff将当前对话的控制权交给另一个Agent并带上必要上下文转岗工单在指令里描述交接规则却不配置handoffs参数Guardrail在主循环外并行运行的校验逻辑输入输出各一层安检闸机用主指令里的禁止代替Guardrail场景Session多轮对话的持久化存储Agent本身无状态聊天记录文件每次运行都开新Session导致失忆Dependencies注入给Agent的全局上下文与配置比如用户ID、数据源连接工位设施把所有东西塞进指令字符串导致token暴涨2.1 Agent不是聊天机器人是任务单元在Agents SDK里一个Agent可以指定name、instructions、model、tools、handoffs、guardrails等属性。它不保存任何对话状态你给它什么输入它就处理什么。理解这点非常重要Agent更像一个函数而不是一个会话。你可以用同一个Agent跑很多个会话也可以在同一个会话里按需加载不同的Agent。既然Agent是无状态的那如何实现多轮对话呢这就需要Session这样的外部存储配合后面第6章我会专门讲。现在你只需要把Agent想象成一张描述角色职责的配置卡它负责决定用哪套规则处理当前输入。2.2 Handoff把上下文原封不动地转出去Handoff是Agents SDK最核心的创新之一。它不只是调另一个模型那么简单而是发起了一个正式的交接流程当前Agent生成一个特殊的Handoff输出SDK检测到后会把整个对话历史、上下文变量、依赖注入一起转交给目标Agent由目标Agent继续生成回复。这个机制让前台接待、售前、售后这种多角色系统变得极其自然。你不需要自己写if-else路由只需要在Agent的instructions里描述清楚什么时候交接给谁模型会基于对话语义自动触发交接。2.3 Guardrail独立于Agent判断的安全网Guardrail可以理解为在国家AI安全框架根据DEPA/容器域在每一轮用户输入进入Agent之前SDK会先并行运行你注册的Guardrail函数同样的在Agent输出返回给用户之前也会运行输出Guardrail。Guardrail和Agent的指令最大的区别在于指令是软约束模型有可能忽略Guardrail是硬校验触发tripwire可以直接中断整轮运行。2.4 Session给无状态Agent装上记忆体Session的概念对标的是Assistants API时代的Thread。Session负责保存输入/输出项的列表也可以附加自己的Store来存额外数据。SDK默认提供了一个sessions接口内置InMemorySession实现切换后端实现接口即可换成Redis或数据库存储。我在实际项目里通常把一个Session对应一次业务咨询工单而不是对应一个用户。这样既能保证上下文完整又不会把不同主题的对话搅在一起。2.5 Dependencies显式地给Agent塞外挂Dependencies是一个泛型参数你可以在构建Agent时指定它的类型然后在run的context参数里传入实例。比如你有一个CustomerContext类里面存了user_id、is_vip、搜索历史那么Agent的工具函数可以声明接收RunContextWrapper从里面取context.user_id。这样工具就能访问每个会话独立的上下文而且不用把这些数据拼进Prompt里。这个设计理解起来有点绕但用顺手之后有个很大的好处指令字符串可以保持干净只写角色规则不写业务数据。业务数据全部通过依赖注入给到工具函数既省token又方便调试。3. 从零搭一个能干活的Agent工具定义、模型选择与完整运行循环3.1 安装与工程目录先装好必须的库pip install openai-agents装完之后建议建一个干净的目录结构别像我第一次一样全堆在一个文件里agent_project/ ├── main.py ├── tools.py ├── agents_setup.py └── .env关键环境变量是OPENAI_API_KEY最好放在.env文件里用python-dotenv加载。如果你希望SDK自动生成trace并上传到OpenAI的Dashboard做可视化调试还需要设置OPENAI_API_KEY对应的组织。懒得配置trace也不影响运行只是排查多Agent问题时少了一个得力工具。3.2 定义一个最简单但完整的Agent我要先做一个有实际意义的示例一个仓库管理员Agent它能查温度传感器状态、能发起补货任务。使用官方推荐的以函数为核心的写法from agents import Agent, Runner, function_tool import os from dotenv import load_dotenv load_dotenv() function_tool def get_temperature(zone_id: str) - str: 查询指定区域的当前温度返回带单位的文本描述。 # 这里直接写死模拟数据实际项目里可接Redis或MQ readings { cold_storage: -2.4C, dry_goods: 18.6C, loading_dock: 23.1C, } return fzone {zone_id} temperature: {readings.get(zone_id, unknown)} function_tool def check_stock_level(sku: str) - int: 查询指定SKU的库存余量返回剩余数量。 stocks {sku_1001: 320, sku_1002: 5, sku_1003: 58} return stocks.get(sku, 0) agent Agent( nameWarehouse Agent, instructions( 你是仓库管理系统的一名值班助理。 当用户查询温度时用 get_temperature 工具。 当用户关心库存时用 check_stock_level 工具。 如果库存低于10你需要主动提醒补货。 ), modelgpt-4o-mini, tools[get_temperature, check_stock_level], ) if __name__ __main__: result Runner.run_sync( agent, input仓库冷库温度正常吗另外sku_1002还剩多少, ) print(result.final_output)如果你运行上面这段代码会看到类似输出仓库冷库温度是-2.4C属于正常范围。另外sku_1002目前只剩5件库存偏低建议尽快安排补货。注意它做了两件事一次提问触发两个工具的连续调用并且基于库存阈值给出了主动建议。这就是Function Calling在Agent框架里的自然体现——不需要你手动判断该调哪个工具模型会根据instruction和工具描述自动选择。3.3 为什么工具必须用函数而不是直接在指令里描述我在勘误早期代码的时候经常看到有人在instructions里写一大堆如果你需要查天气就调用天气API参数是城市名然后自己去解析模型输出的JSON字符串再调API。Agents SDK的做法是用function_tool装饰一个真实的Python函数SDK会自动生成函数对应的JSON Schema交给模型做Tool Calling。两者差异非常明显类型安全工具参数由Python类型注解定义不再需要手写JSON Schema。可测试每个工具都是普通函数可以直接单测。链路清晰SDK自动维护工具调用与工具结果之间的对应关系日志里能看到模型决定调用谁、工具返回了什么。3.4 运行循环里到底发生了什么Runner.run_sync在内部执行的是一个标准Agent循环读取输入交给模型模型可能返回文本或工具调用如果是工具调用SDK执行对应工具函数再把结果传回模型如此反复直到模型直接输出文本结束。这个循环中的每条消息都会被记录成事件你可以用SDK自带的trace功能在Dashboard里看到完整链路。如果不想在控制台里干等也可以换成流式输出from agents import Runner async def main(): result Runner.run_streamed(agent, input仓库全部区域温度给我报一遍) async for event in result.stream_text_events(): print(event.delta, end) final result.final_output print(\n---\n, final)流式模式下stream_text_events()会按增量返回文本片段适合做聊天界面的打字机效果。这里有个小坑如果你同时启用了多个工具流式事件里可能出现工具结果穿插在文本流中的情况前端需要按event类型过滤别直接把所有增量都渲染出去。4. 多智能体协作实战用Handoff搭一套客户服务三科系统4.1 场景设计与Agent职责划分单Agent能做的事毕竟有限。真实业务里最常见的需求是一个入口多个处理环节。我用一个经典的客户服务场景来演示Handoff。假设你的平台有商品咨询、售后退款、技术故障三个部门。你不想让用户自己选择部门而是希望前台的分诊Agent判断意图后直接把工单转给对应部门。三个Agent的职责划分如下Triage Agent只负责判断意图不回答问题然后把对话交给合适的Agent。Sales Agent负责商品咨询、优惠活动、下单引导。Post-sales Agent负责退换货、理赔、物流查询。Tech Agent负责API报错、网络问题、设备配置。from agents import Agent, Runner, function_tool sales_agent Agent( nameSales Agent, instructions( 你是商城售前专员。可以查询商品信息、优惠活动并引导用户完成下单。 如果用户提到退款或货物破损必须交接给 Post-sales Agent。 ), modelgpt-4o-mini, ) post_sales_agent Agent( namePost-sales Agent, instructions( 你是商城售后专员。负责退换货申请、物流跟踪、破损补发。 如果用户提到技术类故障如API报错或设备无法运行必须交接给 Tech Agent。 ), modelgpt-4o-mini, ) tech_agent Agent( nameTech Agent, instructions( 你是技术故障专员。负责设备配置、API报错、网络连接问题。 如果用户只是想退货请交还给 Post-sales Agent。 ), modelgpt-4o-mini, ) triage_agent Agent( nameTriage Agent, instructions( 你是平台总机接待。不要直接回答用户的业务问题。 先判断用户意图商品与订单问题交给 Sales Agent 退货与物流问题交给 Post-sales Agent 设备与接口故障交给 Tech Agent。 ), modelgpt-4o-mini, handoffs[sales_agent, post_sales_agent, tech_agent], )4.2 交接不是函数调用而是一整套上下文转移从代码上看Handoff只是把Agent对象放进列表。但SDK在运行交互时会做这些事当前Agent生成的输出中检测到特殊交接意图。把整段对话历史包括历史消息、工具调用结果封装成新输入。将控制权交给目标Agent目标Agent用自己携带的instructions从头生成回复。这样做最大的好处是目标Agent不需要知道之前发生过什么SDK把上下文全给它了。你可以在交接时用Handoff类覆盖对方的指令比如你是被售后组转交过来的用户情绪可能比较激动请先安抚再处理。我实际测试时发现如果Agent设置较少模型偶尔会在要不要交接上犹豫。解决办法是不要吝啬给每个Agent写清楚边界。尤其是triage这种只管转的Agent指令里一定要写死不要直接回复只负责判断和交接。4.3 跑通整个多Agent流程用一个函数模拟一段用户对话链if __name__ __main__: result Runner.run_sync( triage_agent, input我上周买的耳机有一只不响了想申请换货可以吗, ) print(result.final_output) # 同一段对话继续追问 result Runner.run_sync( triage_agent, input顺便问下你们API最近有报错吗我想用Python重新拉取订单数据一直403。, ) print(result.final_output)预期输出你好这里是售后专员。耳机不响的问题我可以帮你处理请提供一下你的订单号我会为你申请换货流程。 关于API返回403的问题请交给我们技术专员。你可以把调用接口的日志片段发给我我会帮你排查鉴权配置。你会在日志里看到SDK记录的transfer from Triage Agent to Post-sales Agent这类事件整个流程像工单系统一样清晰。这也是这个框架对比自己手写if-else的最大优势——所有的路由决策都留给了模型而不是写死在代码里。4.4 我踩过的交接坑上下文被洗掉了有一段时间我的Agent在交接后突然失忆用户已经在上一个Agent里提供了订单号转到售后Agent后它又回头问一遍。排查后发现是因为我在Handoff类里覆盖instructions时把原对话给截断了——当时我用了一个自定义的custom_handoff函数返回的新input只包含最后一轮消息。正确做法是尽量保持交接输入为原始历史消息的延续不要自作主张截断。如果你确实需要精简历史比如太长时也要确保关键结构化信息订单号、用户ID、问题描述已经放进了Dependencies或Session Store而不是只存在于对话文本里。5. 给Agent装上刹车输入/输出Guardrail的写法与触发逻辑5.1 为什么Guardrail不能靠主指令完成很多人会说我在instructions里写清楚禁止回答违规内容不就行了吗短期看确实能挡住大部分情况但模型本质是一个概率系统幻觉和指令违背是概率性的。主指令属于软约束面对高强度对抗提示词攻击时模型很可能被诱导偏离原指令。Guardrail则是一个独立于主循环的硬性校验节点。它在用户的输入进入Agent主循环之前先跑一遍你注册的校验函数如果校验返回tripwire_triggeredTrueSDK会直接中断整个运行不会让输入到达Agent模型。输出Guardrail同理在模型生成回复后、返回给用户之前做拦截。你可以把Guardrail理解成过滤器和闸门的组合。5.2 输入Guardrail的完整实现下面是一个结合pydantic做结构化输出的输入Guardrail示例。它让一个小模型去判断用户的输入是否触发了高风险问题如果触发就中断from typing import Any from pydantic import BaseModel from agents import ( Agent, Runner, InputGuardrail, GuardrailFunctionOutput, RunContextWrapper, ) class RiskCheckOutput(BaseModel): is_risky: bool reason: str async def risk_check( context: RunContextWrapper[Any], agent: Agent, input_data: str, ) - GuardrailFunctionOutput: # 这里直接用一个独立的轻量模型做判断 checker_agent Agent( nameRisk Checker, instructions判断输入是否属于高危请求返回JSON。, output_typeRiskCheckOutput, modelgpt-4o-mini, ) result await Runner.run(checker_agent, input_data) output result.final_output return GuardrailFunctionOutput( output_infooutput, tripwire_triggeredoutput.is_risky, ) guardrail_agent Agent( nameCustomer Service Agent, instructions你是标准客服助手。, modelgpt-4o-mini, input_guardrails[ InputGuardrail(guardrail_functionrisk_check), ], )这里要注意几件事Guardrail函数接收的input_data是原始输入不是加工后的消息对象。在Guardrail里去调用另一个模型是有代价的每个输入都会多一次额外模型请求。生产环境建议先跑轻量规则正则、关键词、长度过滤再决定是否启动模型级Guardrail。Guardrail函数里不要递归调用同一个Agent否则会形成死循环。我的经验是用一个独立命名、独立职责的checker_agent和业务Agent分开。5.3 输出Guardrail与Tripwire的三种策略输出Guardrail的写法几乎一样只是把函数注册到output_guardrails里。触发Tripwire后你有三类处理策略直接中断返回一个预设的兜底回复比如抱歉我暂时无法回答这个问题。降级处理把模型输出标记为未通过要求主Agent用更保守的设定重新生成一次。记录放行触发时只记录日志不中断回复。适合内容审核期或者灰度发布时观察。我目前在项目里最常用的是前两种输入侧做安全硬拦截输出侧做若不合格则重写的软降级。因为输出完全中断会伤害正常用户的交互体验而软降级能保证大部分回复质量。5.4 关于额外成本的实话一个模型级Guardrail等于每轮多一次模型调用成本肯定会上升。我建议分级第一层字符串规则过滤掉明显的高危词、超长输入、畸形格式。第二层小模型如gpt-4o-mini分类判断只对第一层没拦截但疑似高危的输入启用。第三层业务规则校验比如订单号格式、日期范围用代码而不是模型。千万别一上来就把所有输入都丢给一个完整的大模型做Guardrail。你的账单会很诚实地反映这个设计的好坏。6. 会话与记忆怎么管Session持久化与多轮对话上下文6.1 为什么需要SessionAgent默认是无状态的官方SDK的Runner.run_sync每次运行都是独立的。如果不做任何持久化用户上一句说我的订单号是12345下一句你再问请查一下订单进度Agent已经完全不记得之前发生过什么。这就是Session存在的根本原因——它专门负责保存对话过程中的输入、输出项保证Agent在多次run之间能读到完整的上下文。你可以把Session看成一条聊天记分牌。每次run时通过session_id把历史带进去新的输出会追加到Session末尾。这样多轮对话就有了连续性而Agent本身仍然是纯逻辑角色。6.2 用SessionsRunner管理会话为了简化这个过程SDK引入了SessionsRunner。它帮你在内部维护输入历史、运行状态和会话存储。一个最小示例from agents import Agent, SessionsRunner from agents.sessions import InMemorySession agent Agent( nameAssistant, instructions你是贴心助手。, modelgpt-4o-mini, ) sessions_runner SessionsRunner( agentagent, sessions_factoryInMemorySession, ) async def main(): session_id order_20250601_customer_42 result1 await sessions_runner.run( session_idsession_id, input你好我是老用户想查一下我去年买的耳机的保修期。, ) print(result1.final_output) result2 await sessions_runner.run( session_idsession_id, input那你帮我看看这个订单还在保修期内吗订单号是A123456。, ) print(result2.final_output)第一次run之后Session里保存了关于老用户、耳机、保修期的上下文第二次run时SessionsRunner会把之前的输入输出全部追加到当前对话里模型自然知道这个订单号A123456指的就是上一轮提到的耳机订单。6.3 换掉内存存储生产环境的Session后端官方提供的内存Session很好用但进程一重启就全丢。生产环境建议实现Session接口把Session数据落库。我目前的做法是以session_id为主键Session内容按JSON存储相关序列化数据。每次run后把增量写入存储避免每次全量重写。设置失效时间比如30天不活跃就清理。Redis是一个比较自然的起点因为Session的读写模式很简单而且可以顺便做并发控制。你也可以把Session数据放进Postgres或MongoDB只要实现好create_session_id、get、save这几个方法就行。6.4 管理Session长度别让上下文无限膨胀对话越存越长token也就越花越多。我踩过一个不算小的坑有个用户连续聊了两个小时Session里累积了几千条消息Agent每次回答前都要处理完整上下文延迟飙升到十几秒费用也翻了五倍。现在我的策略是在Session中维护一个最近N轮滑动窗口超过窗口的历史交给摘要Agent压缩。重要结构化信息订单号、用户身份、地址等抽出来放Session的Store里不走文本摘要。如果业务允许直接容忍短期失忆但在Prompt里告诉用户为了隐私每次会话只保留最近几轮。Session设计是Agents SDK里最容易被低估的一环。很多人以为只是加个参数的事实际做深了之后会发现它决定着你系统能不能支撑真实用户量。7. 从Assistants API迁移的关键差异与踩坑清单7.1 Thread与Session、Assistant与Agent的对应关系如果你之前用的是Assistants API迁移时不要机械地对概念。两者的设计哲学不一样硬套会写出非常别扭的代码。Assistants APIAgents SDK差异点AssistantAgentAgent天然支持多角色、多工具、多防护栏ThreadSessionSession是可插拔存储Thread是固定消息列表RunRunner.runRunner更强调事件流控制Tool调用内嵌function_tool装饰器类型安全Schema自动生成无原生HandoffHandoff多Agent协作成为一等公民无GuardrailInput/Output Guardrail硬校验可中断流程最核心的迁移动作是把原来塞在Assistant instructions里的一大段路由逻辑拆掉换成多个Agent的handoffs关系。你会发现代码总量反而变少了。7.2 迁移踩坑记录我在迁移时踩了几个比较典型的坑记录如下工具函数的参数类型一定要写清楚。Agents SDK依赖Python类型注解生成工具Schema如果你把参数写成def f(x)这种无类型形式模型调用工具时很容易生成错误参数。务必加上类型注解和docstring。Guardrail函数在高并发下容易成为性能瓶颈。每个Guardrail如果都要调模型QPS上来之后延迟和费用都hold不住。先用规则过滤再模型兜底。不要在Session里塞超大附件。SDK本身没有限制但模型上下文窗口是有限的几百KB的日志直接放Session里输出基本就废了。默认的Tracing是打开的。如果你希望调试少一点干扰可以显式配置tracing级别不然控制台会被事件刷屏。7.3 到底什么样的项目值得迁不是所有项目都要迁移。我在做迁移判断时有一条简单的标准如果你的系统只有一个角色、没有复杂的工具调用链、也没有多轮状态管理的需求那用最简单的Function Calling接口就够了迁移到Agents SDK只会增加概念负担。但如果你现在面临下面这几个场景我建议认真考虑迁移多个角色共享一套对话流程需要自动路由。同一个任务里需要连续调用多个工具且工具之间存在依赖关系。你希望在模型输入和输出层面加上程序化的安全检查。你需要把对话记忆做成可扩展的持久化能力而不是写在代码里的list。结语先把一个Agent跑通再谈编排这篇文章我从为什么换框架讲到怎么迁移核心目的只有一个让你不再把Agents SDK当成一个更高级的聊天API而是当成一套编排工具集来用。我自己在实际使用中的体会是它最惊艳的部分不在于单个Agent的能力而在于Handoff和Guardrail这两个原语把多角色协作和安全边界变成了可以工程化处理的问题。如果你现在想动手我的建议是从第3章那个仓库管理员的例子开始先跑通一个带两个工具的Agent然后试着加一个Handoff、一个输入Guardrail最后再引入Session做多轮记忆。等这四个部件在你脑子里转起来之后再去读官方文档和源码都不迟。下一篇我会重点拆解Agent事件流和Tracing系统的实现细节顺便聊聊怎么用OpenTelemetry把我们自己的日志埋点接进去。
