这两年 AI 圈里有个很有意思的现象一个智能体产品刚火出圈很快就会被另一个产品替代而推动淘汰的往往正是 OpenAI 自己。从公开的产品和 API 演进看OpenAI 已经在智能体方向上完成了至少三次底层路线的切换一开始是函数调用加 Assistants API中间是 Swarm、Codex CLI 为代表的多 Agent 工具箱现在则集中到 Responses API、Agents SDK 和 ChatGPT Agent 这条新主线上。很多开发者可能没注意到这套切换里藏着好几个“灭绝事件”曾经红极一时的 Assistants API 被官方计划接入新接口教学性质的 Swarm 框架被 Agens SDK 替代GPTs 从最初的爆发式增长逐渐回归工具化。如果你正准备做智能体开发第一件事不是急着写 Agent而是先弄清楚当前版本的技术底座是什么。这篇文章就把 OpenAI 智能体的“三朝”脉络、关键产品、淘汰逻辑和工程实践完整梳理一遍并给出可以照着用的环境准备、代码示例、批量任务思路和问题排查清单。这轮梳理里我会尽量把“能用”“怎么用”“别踩什么坑”讲清楚。对于任何涉及具体版本号、模型可用范围和接口参数的内容都以 OpenAI 官方文档为准。1. 核心脉络OpenAI 智能体三代更迭先看整体脉络。下面这张表把“三朝”的核心区别列出来方便快速定位你现在处于哪个阶段以及新项目应该往哪个方向选型。“三朝”不是官方说法只是便于大家理解技术演进的一种划分方式。阶段大致时间窗口核心 API / 产品代表能力已经退场或正在退场的对象第一朝GPT-4 发布前后Chat Completions API、Function Calling、Assistants API、GPTs让模型输出结构化工具调用参数实现有状态的 Assistant 流程早期纯文本补全接口旧版functions参数第二朝多 Agent 概念集中爆发时期Swarm、Codex CLI、各类第三方 Agent 框架多智能体交接、终端编程智能体、任务拆解Swarm 转为教学示例老版 Codex CLI 被新版本替代第三朝当前主线Responses API、Agents SDK、ChatGPT Agent统一工具协议、生产级 Agent 编排、对话即工作流Assistants API、旧版工具链、大量依赖旧 API 的上层产品对开发者来说“灭绝”不一定是产品当天消失更常见的是官方宣布停止维护、给出迁移窗口或者新接口不再兼容旧参数。只要你的项目还在用旧路线迟早会遇到功能失灵、接口报错或者安全更新停止的问题。这个信号非常明确新项目不要从已经进入迁移周期的技术起步。2. 第一朝函数调用与 Assistants API 时代OpenAI 智能体的起点可以追溯到 Function Calling 的引入。在那之前LLM 基本只能做“对话补全”模型输出什么就是什么程序拿到文本后还得自己解析。函数调用改变了这一点模型可以根据用户问题按照开发者定义的 JSON Schema 输出“该调用哪个函数、参数是什么”真正执行逻辑的还是开发者自己的代码。这是后来所有 Agent 产品的地基。举个例子一个最简单的工具调用流程是先定义一个get_weather函数然后让模型判断用户是否在问天气。下面这段代码展示了最早的 Chat Completions 工具调用方式from openai import OpenAI client OpenAI() tools [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: 北京今天适合出门跑步吗} ], toolstools, ) print(resp.choices[0].message.tool_calls)这一步只是让模型“决定要不要调用工具”真正拿到天气数据后还要把它作为tool消息回传给模型模型才能继续组织最终回答。这个“模型出参数程序执行工具结果回填给模型”的小循环成了当时所有 Agent 应用的标配。随后 OpenAI 发布了 Assistants API 和 GPTs。Assistants API 把 Threads、Runs、Files 这些有状态组件收进了服务端开发者不需要自己管理多轮对话状态就可以搭建“有记忆的助手”。GPTs 则是把这种能力包装成 ChatGPT 里的可分享应用。这一朝解决的问题非常具体LLM 怎么调用外部工具以及怎么在不需要开发者设计复杂状态机的情况下维护多轮对话。但问题也随之暴露。Assistants API 的 Threads 状态结构比较重和开发者已有的业务状态很难灵活对接GPTs 主要长在 ChatGPT 生态内部外部产品调用并不方便。更关键的是工具调用协议本身也经历了一次升级从早期functions字段演进到tools字段新的 Responses API 又把这套能力收得更紧。与其在一代一代的兼容层上修修补补OpenAI 干脆选择了一个更激进的方案重新定义 Agent 开发的结构。3. 第二朝Swarm、Codex 与多 Agent 工具箱2024 年前后多 Agent 概念进入爆发期。开发者不再满足于“一个助手调用几个工具”而是想让不同的 Agent 各管一块业务再通过交接机制协同完成任务。OpenAI 在 2024 年开源了 Swarm看起来很火但它从一开始就明确是“教学示例”不是生产级框架。Swarm 的意义是让开发者快速理解 Agent 之间如何用handoff函数转移控制权真要拿到生产环境还得自己做大量工程化补全。同一时期Codex CLI 是一个更真实的产品。它以终端命令行的方式运行开发者直接在里面用自然语言描述任务例如“给这个项目新增一个导出功能并把测试跑通”。Codex CLI 会自己读写文件、执行命令、查看结果把“智能体写代码”从演示变成了可用工作流。# 安装 Codex CLI需要先完成 OpenAI 账号登录配置 npm install -g openai/codex安装完成后在终端输入codex进入交互界面后就可以直接提需求。Codex 的优势是它天然长在代码仓库里能通过终端读写上下文和 Git、测试命令、包管理器配合很顺手。对熟悉命令行的开发者来说这种交互方式比网页聊天更直接。但第二朝的问题也很明显生态碎片化。模型层还是 Chat Completions可上层框架百花齐放LangGraph、AutoGen、Swarm 各有各的 Agent 抽象。OpenAI 自己的 Swarm 又明确不承担生产责任。很多团队做选型时非常纠结用 Swarm 怕随时被弃用第三方框架怕和官方 API 演进脱节。这种局面注定不会持续太久OpenAI 随后给出了自己的答案。4. 第三朝Responses API、Agents SDK 与 ChatGPT Agent当前 OpenAI 智能体的主线很清楚Responses API 负责统一底层接口Agents SDK 负责 Agent 编排ChatGPT Agent 负责把智能体能力变成产品入口。Responses API 可以理解为 Chat Completions 和 Assistants API 能力的收敛版。它把函数调用、文件搜索、网页搜索、结构化输出等能力放进同一个请求协议里开发者不需要再在多个 API 之间来回切换。配合 Agents SDK可以定义 Agent 对象、设置 system prompt、挂工具、做多 Agent 交接还能用 Guardrails 做输入输出校验。这套组合和之前最大的区别是OpenAI 开始提供“生产级 Agent 运行时”而不是丢给你一堆示例代码。安装 Agents SDK 比较简单pip install openai-agents下面是一个最小可运行的 Agent 示例from agents import Agent, Runner import asyncio agent Agent( name客服助手, instructions你是客服智能体回答时保持简洁不确定时直接说明。, modelgpt-4o, ) async def main(): result await Runner.run(agent, 帮我查一下订单超时处理规则) print(result.final_output) if __name__ __main__: asyncio.run(main())多 Agent 场景下可以定义多个 Agent再通过handoffs做任务交接from agents import Agent triage_agent Agent( name总机, instructions把售后问题转给售后 Agent把销售问题转给销售 Agent。, modelgpt-4o, handoffs[], ) support_agent Agent( name售后, instructions处理退货、退款、物流问题。, modelgpt-4o, ) sales_agent Agent( name销售, instructions处理产品咨询和价格问题。, modelgpt-4o, ) triage_agent.handoffs [support_agent, sales_agent]从工程角度看第三朝更适合生产落地Agent 是明确的对象交接是官方支持的机制状态管理有 Sessions防护逻辑有 Guardrails调试有 Tracing。这套设计让团队可以按照“先做单个 Agent再拆多 Agent”的顺序推进不需要从零搭 Agent 运行时。ChatGPT Agent 则是另一条产品线用户不写代码也能在 ChatGPT 里创建一个智能体、设置指令、接入日历、邮件等外部工具并把智能体分享给其他人。它把“开发智能体”的门槛拉到了普通用户能操作的水平也意味着智能体的分发入口正在从“开发者 API”扩展到“对话产品内部”。对技术团队来说ChatGPT Agent 适合快速验证业务场景但真正要定制化还是得回到 API 和 SDK 这条路上来。5. “灭绝事件”的技术与商业逻辑为什么 OpenAI 要反复推倒重来表面上是一次次 API 升级底层其实有三个逻辑。第一接口统一逻辑。一个平台维护多套互不兼容的 API对官方和开发者都是负担。functional到tools是一次统一Assistants API 到 Responses API 又是一次统一。统一的好处是未来新增工具能力时只需要扩展协议而不是再造一套新 API。第二Agent 运行时的掌控逻辑。OpenAI 已经不满足于只提供“底层模型”它希望开发者把 Agent 的编排、状态、防护、追踪都跑在官方的一套体系里。Agents SDK 走到生产级就是这个意图的直接体现。Swarm 的退役非常典型它完成了“教育市场”的使命等开发者学会了多 Agent 概念官方自然要用更正式的产品来接盘。第三商业分发逻辑。GPTs 和 ChatGPT Agent 的意义不只是功能更是把智能体做成“可分享、可订阅、可协作”的产品形态。谁掌握了分发入口谁就能在 Agent 生态里获取更多真实用户和使用场景。对依赖 OpenAI 生态的第三方项目来说这意味着两条路要么跑在官方 API 之上做应用层创新要么做官方暂时看不上的垂直场景绝不能把核心资产整个压在某个托管 Agent 产品里。换到开发者视角“灭绝事件”其实是最好的选型参考。当 OpenAI 自己都在加速替换旧技术栈时你有没有必要在一个即将退役的 API 上开发新项目答案很清楚。新的智能体开发团队应该把时间花在 Responses API、Agents SDK、Codex 和可迁移的工具抽象上。6. 环境准备与 OpenAI 智能体开发工程实践在开始开发之前先把环境准备好。这里给出一个通用清单具体版本以你自己的系统和 OpenAI 官方文档为准。Python建议使用 3.10 及以上版本。OpenAI API Key在 OpenAI 账号后台创建通过环境变量注入不要写死在代码里。依赖包openai、openai-agents如果需要读本地配置可以加python-dotenv。网络环境确保服务器可以正常访问 OpenAI 官方 API。模型可用范围同一个账号下不同模型的可用状态可能不同先在账号后台确认你要用的模型已经开通。工程目录建议这样组织agent_project/ ├── .env ├── config.py ├── agent.py ├── tools/ ├── outputs/ ├── logs/ └── requirements.txt环境变量文件示例OPENAI_API_KEY你的_API_Key OPENAI_MODELgpt-4o安装依赖pip install openai openai-agents python-dotenv一个比较稳妥的做法是把模型名放到环境变量里代码里只读配置不写死。因为 OpenAI 的模型列表更新很快同一个模型在不同时间的可用性和价格也可能变化。模型名一旦写死后面换模型就要改代码、重新发版非常不划算。第一次开发时建议只保留“一个 Agent、一个工具、一个 prompt、一个测试用例”的最小闭环先跑通再扩展。直接上多 Agent 架构遇到问题会很难定位是模型问题、工具问题还是交接逻辑问题。7. 智能体工作流与 API 代码示例下面给出几种常见的开发方式从底层 API 到上层 SDK 再到批量任务你可以按项目复杂度选择。7.1 使用 Responses API 直接调用如果只是做轻量验证不引入 Agent 框架可以直接用requests或curl调用 Responses APIcurl https://api.openai.com/v1/responses \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, input: 用一句话说明智能体是什么 }返回结果里包含模型回复、token 消耗、会话标识等字段。这种方式适合脚本、自动化工具和简单的智能体实验。Responses API 的设计目标是统一工具调用、文件搜索和结构化输出所以正式项目的建议是直接基于它开发。7.2 使用 Agents SDK 组织业务逻辑Agents SDK 适合业务逻辑较重的项目。你可以把“客服助手”“数据分析助手”“文档整理助手”分别定义为 Agent再在主流程里用Runner.run驱动。核心业务代码这样写更可控import asyncio from agents import Agent, Runner agent Agent( name文档助手, instructions根据用户问题从已有文档中提取关键信息输出结构清晰的回答。, modelgpt-4o-mini, ) async def main(): resp await Runner.run(agent, 这篇文档的核心结论是什么) print(resp.final_output) if __name__ __main__: asyncio.run(main())如果需要把结果返回给 Web 服务可以把final_output封装成 JSON 响应。不要把 Agent 对象直接暴露给 HTTP 层中间加一个 service 层方便做缓存、限流和日志记录。7.3 批量任务与并发控制批量处理是智能体落地的高频需求比如给一批文档生成摘要、给一批客服工单打标签。批量任务最关键的是控制并发否则很容易触发 API 限流。下面是一个用asyncio.Semaphore控制并发数的示例import asyncio from agents import Agent, Runner async def run_one(agent, prompt): try: result await Runner.run(agent, prompt) return {prompt: prompt, ok: True, output: result.final_output} except Exception as exc: return {prompt: prompt, ok: False, error: str(exc)} async def batch_run(agent, prompts, max_concurrency5): sem asyncio.Semaphore(max_concurrency) async def limited(prompt): async with sem: return await run_one(agent, prompt) return await asyncio.gather(*(limited(p) for p in prompts)) async def main(): agent Agent(name批量助手, instructions简洁回答, modelgpt-4o-mini) prompts [ 一句话介绍函数调用, 一句话介绍 Responses API, 一句话介绍 Agents SDK, ] results await batch_run(agent, prompts, max_concurrency2) print(results) if __name__ __main__: asyncio.run(main())批量任务一定要给每个任务记录状态和日志建议至少记录输入、输出、耗时、是否成功、异常信息。不要把大量 prompt 一次性提交后不跟踪结果一旦某个任务失败排查成本会非常高。8. 资源占用、成本与性能观察智能体项目不像本地大模型那样直接看显存它更关注 API 侧的 token 消耗、请求耗时、并发数量和上下文长度。这里给出一套可操作的观察维度。token 消耗是最直接的成本指标。每次请求后程序返回里通常会包含输入 token、输出 token 和总 token 数。建议在日志里统一打印这些数据usage resp.usage print(input_tokens:, usage.input_tokens) print(output_tokens:, usage.output_tokens) print(total_tokens:, usage.total_tokens)不同 SDK 版本的usage字段结构可能不同以实际返回为准。关键是团队里要有一个统计口径不能只看功能跑通不看成本。上下文长度是另一个容易被忽略的点。很多人习惯把历史对话全部塞进messages结果 prompt 越来越长请求越来越慢成本越来越高。更合理的做法是只保留最近几轮对话或者把早先内容做摘要再配合外置记忆存储关键信息。Responses API 和 Agents SDK 都支持会话态但工程上还是要主动控制上下文大小。并发限制也是常见的隐藏瓶颈。OpenAI API 有 rate limit超过限制会返回 429。批量任务里要用信号量限制并发并加入指数退避重试。不要以为“asyncio.gather开一百个并发任务就能加速一百倍”最终会被限流拉回现实。如果把观察结果汇总到一张表可以这样记录观察项影响优化手段输入 token 总量成本、延迟精简 prompt、只传必要上下文输出 token 总量成本、延迟限制max_output_tokens、控制回答长度上下文长度延迟、模型窗口是否溢出历史摘要、外置记忆并发数量是否触发 429信号量限流、指数退避工具数量模型选择工具的开销按场景拆分 Agent缩小工具白名单9. 常见问题排查与合规边界9.1 常见问题与排查方法问题现象可能原因排查方式解决方案请求返回 401API Key 错误或未设置环境变量检查环境变量和 Key 是否泄漏重新生成 Key通过环境变量注入请求返回 429请求频率超出限制或额度不足查看账号用量和限流返回头降低并发增加退避重试使用 Batch API请求返回 400工具参数格式不合法检查tools参数是否符合 JSON Schema用官方结构化工具校验参数模型没有返回 tool_calls提示词没要求或模型选择不合适打印原始响应检查 messages调整提示词或切换到能力更强的模型上下文超长历史消息塞得太多查看 usage 里上下文 token截断、摘要、外置记忆Swarm 旧代码失效Swarm 已退役检查 import 是否报错迁移到 Agents SDK某个模型不可用账号未开通或模型下线查看账号可用模型列表更换可用模型如果你是从 Swarm 或 Assistants API 迁移过来建议先不要直接复制旧代码。先跑通一个新的最小 Agent再把业务逻辑逐步搬进去。很多时候报错不是理解不了而是新旧接口的对象和参数完全不一样与其逐行改不如照着官方迁移文档重写。9.2 合规与安全边界智能体能调用外部工具、操作文件、执行代码能力越强风险边界越要清晰。第一API Key 必须严格保管。不要出现在前端代码、公开仓库或日志里推荐用环境变量或密钥管理服务。第二涉及用户数据时要做脱敏和最小化处理。不要把一个真实用户的长对话全量丢给模型除非你确认已经满足对应的隐私合规要求。第三自主行动类智能体必须做权限控制。要让 Agent 只能调用白名单里的工具而不是给它一个无限制的 Shell。工具调用前要有一层校验工具执行后要记录日志。第四涉及图像、视频、声音、数字人等内容生成或处理时必须确认素材版权和肖像授权。智能体能替代流程但不能替代授权义务。所有对外发布的内容都应该有版本记录和人工复核机制。10. 总结三条选型建议OpenAI 智能体的“三朝”演进本质上是从“模型对话”走向“Agent 运行时”的路径。Assistants API 会被替代、Swarm 会退役、旧工具链会失效这都不是偶然而是接口统一、运行时掌控和产品分发三重逻辑叠加的结果。给正在做技术选型的团队三条建议第一新项目不要从已经进入迁移周期的 API 起步。优先使用 Responses API 和 Agents SDK它们才是当前主线。第二不要把业务核心绑定在某个托管 Agent 产品上。用官方 API 和 SDK 做底层再留一层自己的工具抽象未来即使 OpenAI 再换一轮接口也不至于推倒重来。第三先做最小闭环再放大批量任务。第一次开发先跑通“一个 Agent、一个工具、一个测试用例”确定成本、延迟和输出质量符合预期再考虑多 Agent 交接、并发排队和复杂工作流。这套演进速度说明智能体开发已经过了“随便搭一个 demo”的阶段接下来拼的是工程化、成本控制和合规边界。建议收藏备用动手前先确认你选的技术路线还站在官方主线这一边。