最近在给团队做 AI Agent 技术选型时发现一个很有意思的现象网上的智能体教程鱼龙混杂有人还在教两年前的 Plugins 写法有人已经在折腾 Codex 自动化编码。把所有资料放在一起对比很容易被搞晕。其实 OpenAI 在智能体能力上的演进根本不是什么简单的小版本升级而是经历了三次完全不同的范式切换。每一次切换都意味着一批旧接口、旧框架被宣布废弃、被迁移、被“灭绝”。这篇文章想把这些变化整理成一条清晰的时间线围绕“智能体开发”这件事拆解 OpenAI 三个阶段的方案设计与关键代码示例同时附上从旧方案迁移到新方案的实战过程。不管你是刚开始入门 Agent 开发还是已经在生产环境里使用 Assistants API都可以从中找到对应的避坑点。1. 一场没有公告的“物种灭绝”从智能体方案迭代说起1.1 智能体到底是什么在展开技术方案之前先对齐一下“智能体”的概念。我们平时说的 AI Agent智能体通常指的是一个能够自主理解任务、调用工具、根据反馈完成目标的 AI 系统。它和普通聊天机器人的区别在于聊天机器人只负责“说”智能体还要负责“做”。举个例子一个普通的 LLM 接口用户问“北京今天天气怎么样”模型会回答“你需要查询天气网站哦。”它不会真的去查。而一个智能体会把用户的问题拆成“获取北京天气”这个工具调用然后拿着工具返回的数据再生成最终答案。也就是说智能体 大模型 规划能力 工具调用 执行循环。在早期的开源实现里大家会自己写一个while循环不断把模型输出、工具结果拼进消息列表再请求一次模型接口。这种做法完全可行但每个团队都要重复造轮子而且对错误处理、上下文长度、多步调用都很头疼。OpenAI 后来的方案就是要把这套“轮子”标准化让开发者通过 API 或 SDK 直接使用一套成熟的智能体运行框架。1.2 为什么 OpenAI 的每一次改动都影响巨大因为 OpenAI 的模型和 API 是全球大量智能体产品的地基。无论是直接调用gpt-4o完成 Function Call还是使用 Assistants API 做知识库问答又或者用最新的 Agents SDK 编排多智能体协作底层都依赖 OpenAI 的这套接口体系。只要 OpenAI 调整一次推荐路线市面上会有一大批教程、开源项目、商业应用跟着变。这也是这次“灭绝事件”如此关键的原因旧范式并不是自己慢慢死掉的而是官方主动宣布停用、迁移或者用新接口覆盖老接口。如果你还在照着一年前的教程写代码很可能项目刚上线就遇到了废弃警告。1.3 本文适合哪些读者正在学习 AI Agent / 智能体开发想了解不同 API 方案区别的人项目中还在使用 Assistants API担心被官方淘汰的人想快速跑通 OpenAI 最新 Agents SDK并学会做一个带工具调用的智能体的人做技术选型时需要对“Function Calling、GPTs、Assistants API、Responses API、Agents SDK”这些词做横向对比的人。读完这篇文章你会知道 OpenAI 智能体方案的三次关键迭代分别解决什么问题并带走一份可以直接运行的 Python 实战代码。2. 第一朝Function Calling 与 Plugins智能体雏形2.1 从“对话”到“动手”Function Calling 的意义时间回到 2023 年前后。当时的 GPT 模型虽然能生成高质量文本但在回答事实性问题时经常出现幻觉。大家需要在模型外面接搜索引擎、数据库、业务系统于是最朴素的做法是把数据和工具全都塞进 Prompt 里让模型“看着”这些信息来回答。这种做法有两个明显问题上下文长度有限塞不了太多数据模型不知道怎么按固定格式触发外部系统。Function Calling函数调用的出现改变了这一点。模型可以通过结构化的工具描述知道“有哪些外部能力可用”然后在回答时输出一个 JSON 格式的调用请求由开发者接收这个请求去执行真实函数再把结果返回给模型。这样就形成了“模型负责决策、代码负责执行”的闭环。与其把 Function Calling 看成一个 API 特性不如把它看成智能体的“肢体”模型终于不只是会动嘴还能“伸手”操作外部工具。2.2 Function Calling 的最简示例下面是一个典型的 Function Calling 请求。这里我们定义了一个get_city_weather工具让模型学会在用户询问天气时返回工具调用参数。# 文件路径function_calling_demo.py from openai import OpenAI client OpenAI() tools [ { type: function, function: { name: get_city_weather, description: 获取指定城市的天气信息, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海 } }, required: [city] } } } ] completion client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 北京今天天气怎么样} ], toolstools ) message completion.choices[0].message # 如果模型认为需要调用工具message.tool_calls 会包含参数 if message.tool_calls: print(模型决定调用工具, message.tool_calls[0].function.name) print(参数, message.tool_calls[0].function.arguments) else: print(模型直接回复, message.content)这段代码先把工具描述传给模型模型会自行判断是否调用。当你收到tool_calls后再执行真正的天气查询接口并把结果追加进 messages 里继续发起二次请求。整个过程需要开发者自己写循环框架感并不强但思路是对的。2.3 Plugins 的尝试与失败和 Function Calling 几乎处于同一时期的还有 OpenAI 推出的 Plugins 插件机制。插件让 ChatGPT 可以通过联网、解释代码、甚至访问第三方应用来完成更复杂的任务。这个想法在当时很前卫但也暴露出不少问题插件生态需要大量开发者做额外适配通用性不足插件权限与安全边界没有完全理顺存在提示注入等风险用户对“什么时候该启用哪个插件”的体验并不好OpenAI 无法快速审核和保障第三方插件的质量。最终插件模式逐步退场官方把注意力放到了更可控的 GPTs 和 Actions 方案上。但 Plugins 留下的一个重要遗产是智能体不能只靠模型单打独斗必须有一套标准化的工具接入方式。2.4 这一朝留下的技术遗产这一阶段最核心的财富是 Function Calling。它让“模型输出结构化调用参数”成为一门通用语言。直到今天最新的 Responses API 和 Agents SDK 底层依然在延续这个思想只是把工具调用的处理逻辑封装得更完整了。新手如果先弄懂 Function Calling再去看 Agents SDK理解成本会低很多。3. 第二朝GPTs 与 Assistants API智能体平台化3.1 降低门槛的愿景2023 年 11 月的 OpenAI DevDay 上官方发布了 GPTs 和 Assistants API。GPTs 允许普通用户通过对话方式创建自定义版 ChatGPT不需要写代码。Assistants API 则面向开发者把常用智能体能力打包成服务端接口。“平台化”是第二朝的关键词。OpenAI 希望把智能体开发变成一种配置行为上传文档、勾选工具、配置指令就能得到一个可供调用的智能体。对非技术用户来说这个愿景很美好对开发者来说Assistants API 也确实省去了自己维护工具循环的痛苦。3.2 Assistants API 核心能力Assistants API 的典型能力包括Assistant在服务端维护一个“助手”对象包含指令、模型、工具等配置Thread服务端维护的会话线程用来保存多轮上下文Message用户和助手之间的消息记录Run一次基于 Thread 的执行过程内置工具如 Code Interpreter代码解释器、File Search文件检索、Function Calling。这套设计把“智能体运行”的大部分状态都放到了 OpenAI 服务端开发者不需要自己管理上下文累计和工具调用循环调用起来会轻松不少。3.3 Assistants API 的代码示例下面是 Assistants API 的常见用法创建一个文件检索助手并向它发消息# 文件路径assistants_api_demo.py # 注意Assistants API 已进入退役流程示例用于理解旧方案。 from openai import OpenAI client OpenAI() # 创建助手 assistant client.beta.assistants.create( name文档问答助手, instructions你是一个知识库助手帮助用户总结和检索文档内容。, modelgpt-4o, tools[{type: file_search}] ) # 创建线程 thread client.beta.threads.create() # 给线程添加用户消息 client.beta.threads.messages.create( thread_idthread.id, roleuser, content帮我整理一下这份文档的要点。 ) # 运行助手并等待执行完成 run client.beta.threads.runs.create_and_poll( thread_idthread.id, assistant_idassistant.id ) # 打印助手回复 messages client.beta.threads.messages.list(thread_idthread.id) if messages.data: print(messages.data[0].content[0].text.value)使用client.beta.threads路径意味着这是一套仍处于测试期、随时可能调整的接口。服务端会帮你完成状态管理但代价是调试链路变长网络请求更多且当业务需要多智能体协作时Thread 的模型反而限制了灵活性。3.4 为什么被淘汰OpenAI 在后续迭代中逐渐意识到服务端维护 Thread 的设计更适合“单助手 对话”却不适合工程化、可编排、多智能体的场景。如果每个 Agent 都有自己的 Thread如何让两个 Agent 之间传递状态如何控制工具调用的可见性如何处理长任务的失败恢复这些问题在 Assistants API 里回答得并不好。于是OpenAI 在 2025 年明确宣布 Assistants API 将会退役并推荐开发者迁移到 Agents SDK 和 Responses API。这是一个非常典型的“物种灭绝”节点旧方案依然能用但官方已经停止投入新特性并开始倒计时下线。4. 第三朝Responses API、Agents SDK 与 Codex智能体工程化4.1 新路线整体思路第三朝的思路发生了变化从“服务端帮你管理一切”回归到“开发者拥有透明化和可编排的执行循环”。Responses API 可以看成 Chat Completions API 的升级版它把工具调用、网络搜索、文件搜索等能力放在更统一的接口里。Agents SDK核心包名为openai-agents则是在这一基础上构建的智能体编排框架它支持定义 Agent、配置指令和工具使用Runner运行单个或多个智能体通过 Handoff移交机制实现多智能体协作提供追踪Tracing能力方便观测智能体执行过程。Codex 则是另一个方向的产物把智能体能力应用到编码场景通过自然语言驱动编码、命令行操作、文件修改等。你可以把 Codex 理解为“会写代码的智能体”它和云主机、Git、命令行工具结合能完成一类完整开发任务。从整体趋势看OpenAI 正在把智能体从“API 特性”升级为“开发者可以完全掌控的工程框架”。这不是小修小补而是对上一代方案的全面替代。4.2 Agents SDK 安装与环境配置以 Python 为例安装命令如下pip install openai-agents安装完成后需要配置 OpenAI API Key。建议使用环境变量而不是直接把 Key 写在代码里export OPENAI_API_KEYsk-your-key如果你使用 Windows PowerShell$env:OPENAI_API_KEYsk-your-key如果你在项目中使用.env文件也可以借助python-dotenv加载from dotenv import load_dotenv load_dotenv()注意openai-agents安装后的导入模块名是agents不要和项目里其他同名模块混淆。4.3 实战带天气工具的单智能体下面是一个完整的 Agents SDK 智能体示例。智能体持有一个天气查询工具用户询问天气时它会先调工具再把工具结果整理成回答。# 文件路径weather_agent.py from agents import Agent, Runner, function_tool function_tool def get_weather(city: str) - str: 查询指定城市的天气情况。 # 真实项目中这里应调用天气服务 API return f{city}晴25℃微风。 agent Agent( nameWeatherAssistant, instructions你是一个天气助手。当用户询问天气时必须调用 get_weather 工具获取真实天气并根据结果回答。, tools[get_weather], ) def main(): result Runner.run_sync( agent, 北京今天天气怎么样 ) print(智能体回答, result.final_output) if __name__ __main__: main()运行方式python weather_agent.py预期输出类似智能体回答 北京今天天气晴朗气温 25℃微风。从代码结构可以看出Agents SDK 把“模型请求、工具调用、结果合并”这整个过程封装进了Runner.run_sync。开发者只需要关注两件事定义工具、定义 Agent 行为。4.4 多智能体协作与 Codex如果我们把多个 Agent 组合起来就可以完成更复杂的任务。比如一个“渠道分发智能体”根据用户意图把问题移交给“天气智能体”或“计算器智能体”。Agents SDK 提供了 Handoff 机制让智能体之间可以主动移交任务。这种多智能体设计非常适合以下场景客服系统按意图路由到不同领域的专家数据看板系统由一个主 Agent 协调多个查询工具开发工具链中由编码 Agent 调度测试 Agent 和部署 Agent。Codex 同样是当前热门的智能体形态。对于做 AI 编码的同学可以关注官方提供的 Codex CLI它以命令行方式执行编码任务。通过自然语言描述需求Codex 能直接修改仓库文件、运行命令并提交结果。它把“智能体”和“开发者工作流”结合得非常紧密。5. 完整实战从旧方案迁移到 Agents SDK如果你现在还在使用 Assistants API建议尽早做迁移规划。这一部分我们演示一个“文档问答助手”如何从旧方案改造成 Agents SDK 新方案。5.1 迁移前的需求梳理假设旧系统的需求是用户上传或指定一个文档智能体基于文档内容回答问题系统需要保留多轮上下文后续可能扩展为多个助手协作。在旧方案中Thread 放在 OpenAI 服务端文档检索由file_search工具完成。迁移到新方案后我们有两种选择继续使用 OpenAI 官方的文件检索能力把文档切成向量配合外部向量数据库做检索再把结果作为工具返回给模型。对于需要精细控制权限和知识库的企业项目推荐第二种方案。但为了演示方便下面的迁移例子用一个简化版自定义search_document工具内部返回固定文本核心目的是展示工程结构。5.2 环境准备安装依赖pip install openai-agents openai python-dotenv目录结构建议agent_migration/ ├── .env ├── main.py └── tools.py.env文件OPENAI_API_KEYsk-your-key注意sk-your-key只是占位符需要替换成你自己的 Key。5.3 编写核心代码首先定义工具文件tools.py# 文件路径tools.py from agents import function_tool function_tool def search_document(query: str) - str: 根据问题在知识库中检索相关段落。 # 真实项目中这里应调用向量检索接口并返回最相关的文本片段 snippets { 退货政策: 用户购买后 7 天内可无理由退货运费由买家承担。, 保修期限: 电子产品整机保修一年主要零部件保修两年。, } for key, value in snippets.items(): if key in query: return value return 未找到相关文档请补充更多关键词。然后编写主文件main.py# 文件路径main.py import os from dotenv import load_dotenv from agents import Agent, Runner from tools import search_document load_dotenv() agent Agent( nameKnowledgeBaseAssistant, instructions你是一个知识库助手。用户提问时先调用 search_document 工具检索相关文档再根据检索结果回答。, tools[search_document], ) def ask(question: str) - str: result Runner.run_sync(agent, question) return result.final_output if __name__ __main__: while True: question input(请输入你的问题输入 exit 退出) if question.strip().lower() exit: break answer ask(question) print(助手回答, answer) print(- * 50)这个示例实现了控制台交互。每次提问都会创建一个新的运行上下文如果需要长期保持多轮记忆可以把历史消息累计后作为参数传入或者在系统中自己维护会话状态。5.4 运行与验证运行命令python main.py输入测试问题请输入你的问题输入 exit 退出退货政策是什么预期输出助手回答 根据知识库内容用户购买后 7 天内可无理由退货运费由买家承担。这个流程和旧 Assistants API 的对比如下对比维度旧方案Assistants API新方案Agents SDK包名或路径client.beta.assistantsfrom agents import Agent会话状态服务端 Thread应用侧自行管理工具定义通过 API 提交工具配置使用function_tool装饰器运行方式创建 Assistant、Thread、Run调用Runner.run_sync调试可见性状态在远端链路较长本地执行易于打印日志和追踪5.5 预期结果与后续扩展到这里你应该已经能够通过 Agents SDK 跑通一个自定义工具型智能体。后续扩展方向包括接入真实向量数据库让search_document返回相似度最高的文档片段使用流式输出让智能体边思考边返回结果增加多个 Agent用 Handoff 实现“意图识别 领域回答”的分工结构接入观测平台分析每次工具调用的耗时和成功率。6. 常见问题与排查思路在实际开发和迁移过程中下面几个问题出现频率很高。问题现象常见原因解决思路运行报错ModuleNotFoundError: No module named agents没有安装openai-agents或包名冲突执行pip install openai-agents检查当前 Python 环境提示OPENAI_API_KEY未设置环境变量未生效检查.env是否加载确认是否执行了export返回 401 UnauthorizedAPI Key 无效或账号权限不足到 OpenAI 后台重新生成 Key确认余额和权限模型没有调用工具而是直接编造答案指令不够严格或模型选择不调用工具在instructions中强调“必须调用工具”或调整model参数工具返回结果没有进入模型上下文只看第一次请求的返回没有完成二次调用使用 Agents SDK 的Runner封装避免手写循环时遗漏消息拼接Assistants API 调用报废弃警告官方已进入迁移窗口期尽快评估迁移到 Agents SDK同时关注官方下线时间节点调用成本明显升高多轮工具调用次数多、上下文膨胀优化工具数量压缩检索结果增加缓存与限流如果你是手动实现 Function Calling还有一个常见的坑模型虽然返回了tool_calls但代码没有把tool_calls消息和工具执行结果同时追加到 messages 里导致第二次请求报错。建议直接使用封装好的 Agents SDK让框架处理这些细节。7. 最佳实践与工程建议7.1 API 选型建议新项目请优先考虑 Responses API Agents SDK。即使你只是做一个简单的 Function Calling直接使用 Agents SDK 也能省去维护循环的麻烦。对于历史项目如果还在用 Assistants API应把“迁移”列入版本计划不要在废弃接口上继续堆业务。另外很多第三方智能体平台如 Dify、Coze也在逐步兼容 OpenAI Agents 协议选型时可以关注平台是否支持“以 OpenAI 兼容接口方式接入模型”。这样业务代码可以做到模型层可替换避免被单一供应商锁定。7.2 密钥与配置管理不要把OPENAI_API_KEY写死在代码或前端页面中。建议使用环境变量、云厂商的密钥管理服务或 CI/CD 的 Secret 配置功能。在后端服务中还需考虑给不同业务模块分配独立 API Key便于成本核算与权限隔离设置月度消费上限防止异常调用导致成本失控定期轮换密钥降低泄漏风险。7.3 工具设计原则工具是智能体的核心能力边界。设计工具时建议做到一个工具只做一件事命名清晰比如get_user_order_status工具描述尽量详细让模型知道什么时候该用、什么时候不该用工具参数使用强类型并提供必要的枚举说明工具内部做好超时、异常兜底避免把底层错误直接抛给模型。一个容易被忽视的点工具返回的内容会进入模型上下文所以返回字符串应该尽量精简只放对回答有帮助的关键信息。不要返回一整个数据库表 JSON那会浪费 Token 并影响推理效果。7.4 异常处理与日志生产环境的智能体链路比普通 HTTP 接口更长容易出现部分工具调用失败、模型超时、返回内容不符合预期等情况。工程上建议为工具调用增加超时时间对工具执行结果做结构校验记录每次调用的模型名、请求时间、Token 消耗、工具调用列表在关键节点输出结构化日志便于追踪多智能体协作过程。调试时可以先使用 Agents SDK 的 tracing 功能把 Agent 运行过程可视化正式上线后再结合日志平台做链路追踪。7.5 成本控制与性能优化智能体应用的成本往往比普通聊天应用更高因为一次任务可能需要多次模型请求。优化思路包括用小型模型处理简单意图大型模型只处理复杂推理对常见问题做缓存尽量命中已有答案控制检索返回的文档数量减少上下文长度合理设置 Agent 的最大步骤数防止模型陷入无意义循环在非实时场景使用异步任务队列错峰调用模型。7.6 安全边界接入智能体后安全边界主要集中两个方面工具权限智能体能调用什么工具后端必须做二次鉴权不能只靠模型判断。比如“删除订单”这类敏感操作应要求用户确认或提供额外凭证。提示注入用户输入中可能隐藏恶意指令试图让模型调用高权限工具。可以通过“输入隔离 输出校验 权限最小化”来缓解。无论使用哪种平台、哪种协议只要你的智能体能访问真实业务系统这些安全原则都不能省略。8. 总结与下一步学习路线从 Function Calling 到 Assistants API再到现在的 Agents SDKOpenAI 的智能体路线其实一直在做同一件事让模型更好地融入实际业务系统。第一朝解决了“模型能调用函数”的问题第二朝解决了“智能体能被配置”的问题第三朝则把重心转向“智能体能被工程化编排”。对于开发者来说最需要记住的结论是旧方案虽然还能跑但趋势已经非常明确。新项目直接学习 Agents SDK 和 Responses API旧项目尽快迁出 Assistants API而你自己手写 Function Calling 循环的时间省下来去设计更好的工具和业务流会更划算。接下来可以按这个顺序继续深入先跑通一个最简单的 Agents SDK 单智能体自己设计 2 到 3 个真实业务工具让智能体完成一个多步骤任务尝试用 Handoff 搭建一个多智能体流程比如意图识别 领域回答研究流式输出、Tracing、缓存和成本控制逐步完善生产级方案。智能体开发这个方向变化很快官方接口和第三方平台的功能也在不断更新。动手实践时记得以你所使用 SDK 的最新官方文档为准。如果你正在从某个旧方案迁移或者遇到过比较难排查的智能体运行问题欢迎在评论区交流。