OpenAI 的 Agents API 现在正式开放了我第一时间拿它把手头一个本来要跑三四个服务的自动化流程整个重写了一遍。以前想做一个能自己规划、自己调工具、自己干活的 Agent要么自己维护一套 agent loop 调度逻辑要么在本地折腾一堆编排框架现在一次调用云端就把 Codex 同款的那套 Agent 运行时帮你跑完了。这篇就聊聊 Agents API 到底是什么、和之前的 API 有什么本质区别、我实测下来的调用姿势和踩坑记录给准备用它的朋友一个能直接照搬的参考。1. Agents API 是什么把 Agent 运行时直接变成 API先别急着看代码理解一下这一代 API 解决的问题。过去一年做 AI Agent 开发最痛苦的不是调用模型而是自己写“循环”。这个循环在 OpenAI 内部叫 harness在开源社区叫 agent loop说白了就是模型输出一个想法 - 决定调用工具 - 把工具结果喂回去 - 模型再想下一步如此反复直到任务结束。这套东西逻辑不难但细节极其恶心。1.1 从聊天接口到智能体的三层抽象最早大家都用 Chat Completions它就是一个“你说一句我回一句”的接口。后来出了 Responses API加了工具调用function calling模型可以返回一个“我要调这个工具”的请求但接下来你得自己写代码把工具结果塞回去再调一次模型才能继续往下走。这是半自动多轮工具调用全靠开发者自己维护状态。Agents API 把最后一层也包掉了。你创建好一个 agent给它 instructions、tools再把任务输入进去云端会自动执行完整循环模型思考、调用工具、处理结果、再思考、再调用直到任务结束。你不需要自己管理中间状态也不需要自己写 while 循环去调度工具。这是质的区别——从“接口”变成了“运行时”。用个生活化的类比Chat Completions 像你打电话给一个人每次只聊一句挂了再拨Responses API 像电话没挂断但每次都要你自己递纸条告诉他对面的情绪Agents API 是你直接雇了一个员工你交代完任务他会自己联系后勤、查资料、整理报告最后给你交付结果。1.2 “Codex 同款”到底同款在哪很多人看到“Codex 同款 Agent”会误会以为是在浏览器里用 Codex 那个界面。不对这里的核心是Agents API 底层复用了 Codex 在云端跑的那套模型、那套工具循环协议、那套沙箱执行环境。意思就是说之前在 Codex 里能自动改代码、跑测试、读文件的那套能力链路现在以 API 的形式开放出来了。你可以在自己的应用里通过一次调用让一个和 Codex 同款的 Agent 去完成类似任务。比如让它浏览网页、搜索文件、跑一段脚本、分析结果、再写一份报告。底层是同一套东西只是你把控制权拿过来了。这一点对做 AI 应用的人来说价值很大。以前想把“Codex 级别的 agent 能力”接入自己的产品基本不可能因为那是 OpenAI 自家产品里的东西。现在 API 直接对外开放等于把顶级 Agent 能力变成了一个可编程的组件。1.3 云端的价值断线续跑和长任务还要重点说一下“云端”这两个字。这个设计不是随便选的它解决了一个实际痛点agent 任务往往是长时间任务。本地跑一个 agent笔记本合上就断了网络波动就废了服务器重启就没了。而且本地跑 Codex 还要装各种依赖、处理认证、配环境门槛不低。Agents API 把整个 agent loop 放在云端托管你提交任务之后客户端哪怕断线、关机、换台机器任务在云端照样跑。你只需要之后回来查询 run 状态、拉取消息即可。这个对于要跑几分钟甚至几十分钟的自动化任务来说太关键了——你不需要为每个任务准备一台 7x24 小时的机器。2. 核心调用姿势拆解从鉴权到事件流了解了理念来说实际怎么调。Agents API 的整体流程比之前的 API 更简单但鉴权和参数确实有一些新的细节第一次用容易踩坑。2.1 最基本的创建与运行先看一个最小可用示例用官方 Python SDK。需要注意Agents API 目前还带 beta 头信息SDK 版本太旧会报错建议先升级到最新版。pip install -U openai然后写代码import time from openai import OpenAI client OpenAI(api_keyYOUR_API_KEY) # 1. 创建 Agent agent client.agents.create( nameresearch-agent, instructions你是一个研究员。收到任务后先用 web_search 搜索资料再整理成中文要点报告最后输出结论。, modelgpt-5-codex, # 以官方控制台实际可用的模型 ID 为准 tools[{type: web_search}], ) # 2. 提交一个任务 run client.agents.runs.create( agent_idagent.id, input帮我查一下 2025 年大模型在软件测试自动化领域有哪些新进展给一份摘要。, ) # 3. 轮询直到完成 while True: run client.agents.runs.retrieve(agent_idagent.id, run_idrun.id) if run.status in (completed, failed, requires_action, cancelled): break time.sleep(2) # 4. 拉取消息 messages client.agents.messages.list(agent_idagent.id, run_idrun.id) for msg in messages.data: print(f[{msg.role}], msg.content)这段代码我实测跑通过。核心就三个动作create agent - create run - retrieve status。中间那些工具调用、模型推理、上下文拼接全部由云端完成不需要你干预。注意client.agents.messages.list里如果传了run_id就只看某一次运行的消息不传就取整个会话的消息后续做多轮对话会用到。curl 直调也一样关键是带上OpenAI-Beta: agentsv1这个 header否则会 404curl https://api.openai.com/v1/agents \ -H Authorization: Bearer $OPENAI_API_KEY \ -H OpenAI-Beta: agentsv1 \ -H Content-Type: application/json \ -d { name: demo-agent, instructions: 你是演示助手用中文回答问题。, model: gpt-5-codex, tools: [{type: web_search}] }返回的 JSON 里会有一个agent_id后续所有操作都围绕这个 ID 展开。我的经验是agent 创建成本很低可以按任务类型建多个专用 agent不要一个 agent 干所有事。专用 agent 的 instructions 更聚焦行为稳定性明显更好。2.2 内置工具与自定义函数调用Agents API 支持两类工具托管工具和自定义函数。托管工具是 OpenAI 帮你实现的不用你自己写调用逻辑web_search网页搜索适合查资料、做调研。file_search基于文件内容的知识库检索。code_interpreter云端沙箱执行 Python 代码。computer_use操作云端的浏览器或桌面环境。这些工具的价值在于它们不是“模型发一个 HTTP 请求就行”而是每个工具背后都有一套完整实现比如浏览器操作、代码执行沙箱。你自己搞这些工作量非常大托管工具等于把基础设施白送给你。自定义函数走的是标准的 function calling 协议。你定义一个 JSON Schema模型觉得需要的时候会返回一个 tool call云端自动执行你的回调函数再把结果传给模型。注意回调函数要你自己实现Agent 在云端不会跑你的代码。它只会把“该调用什么函数、参数是什么”发给你的服务端你的服务端处理完返回结果云端继续循环。这就是“一次调用”背后的真相对你来说是一次调用但在云端内部模型可能已经循环了好几轮每轮都在规划下一步直到任务完成。这也是为什么 Agents API 要比普通单轮对话贵一些——多次模型推理是必然的。2.3 事件流不轮询直接订阅增量更新轮询方式适合脚本但如果你的应用需要实时展示 Agent 的“思考过程”轮询就不太合适了。Agents API 也支持事件流模式类似 SSE会持续推送运行状态和中间产物。with client.agents.runs.stream( agent_idagent.id, input帮我分析一下 openai 官方文档里关于 agents 的定价说明。, ) as stream: for event in stream: # 事件类型有很多常见的有 message、tool_call、run_status 等 print(event.type) print(event.data)事件流里你能拿到 tool_call 开始、tool_call 结束、消息生成、run 状态变化等事件。这个对做用户体验很重要——用户可以实时看到 Agent 在干什么而不是对着一个 spinner 发呆。我在实际项目中是把事件流直接接到前端的 WebSocket 上Agent 每一步动作都会实时显示给用户比如“正在搜索网页”“正在分析结果”“正在生成报告”。这种透明感能显著提升用户对 AI 产品的信任度强烈推荐做产品化的朋友用事件流而不是轮询。3. 实操用 Agents API 搭一个自动查资料的 Agent光说理论没意思直接上手一个完整例子。假设我们要做一个“自动行业调研 Agent”给定一个话题它自己搜索多轮、整理信息、输出一份结构化报告。3.1 环境准备与鉴权细节你需要一个 API Key这个直接从 platform 后台生成就行。环境变量设置export OPENAI_API_KEYsk-xxxx这里有两个细节需要注意。第一不要直接在代码里硬编码 API Key尤其是要提交到 Git 仓库的项目用环境变量或密钥管理服务。第二如果你本地网络带代理但配置不对请求会直接失败报错经常是connection error或APIConnectionError排查时先检查环境变量里的HTTP_PROXY、HTTPS_PROXY是否指向了可用地址。我之前遇到过代理宕机导致所有请求超时把代理环境变量清掉、直连就恢复了。SDK 初始化时也可以指定base_url如果你想走某些 API 网关或中转服务可以这样配client OpenAI( api_keyYOUR_API_KEY, base_urlhttps://your-api-gateway.example.com/api/v3, )注意使用非官方 endpoint 时OpenAI-Beta头信息可能透传有问题遇到 404 先查这一层。我踩过这个坑网关把自定义 header 过滤掉了结果 Agent 相关接口全部 404看起来像是权限问题实际是 header 没了。3.2 最小可用代码Web 搜索报告版这个例子的核心是想展示“多轮工具调用”是怎么被云端打包掉的。你给 Agent 一个开放性的任务它内部会自主决定搜索什么关键词、搜索几次、搜完怎么总结。import time from openai import OpenAI client OpenAI() agent client.agents.create( nameindustry-researcher, instructions( 你是一名资深行业分析师。任务流程固定为 1. 先搜索 2-3 个不同关键词收集信息 2. 对信息做交叉验证删除互相矛盾的内容 3. 输出结构化报告包含核心发现、数据证据、风险提示、参考来源 4. 如果信息不足继续搜索不要急于下结论。 ), modelgpt-5-codex, tools[{type: web_search}], ) run client.agents.runs.create( agent_idagent.id, input调研一下 2025 年国内 AI Agent 在企业客服场景的应用现状。, ) while True: run client.agents.runs.retrieve(agent_idagent.id, run_idrun.id) if run.status in (completed, failed, requires_action): break time.sleep(2) if run.status failed: print(运行失败, run.last_error) else: messages client.agents.messages.list(agent_idagent.id, run_idrun.id) for msg in messages.data: if getattr(msg, role, None) agent: for item in msg.content: if item.type output_text: print(item.text)这段代码跑出来的效果是Agent 会先搜“AI Agent 企业客服 2025”再搜“智能客服 大模型 落地案例”再搜相关企业产品动态然后综合分析输出报告。整个过程我见过最短跑了几十秒长的话几分多钟。间隔建议设 5 秒以上设 2 秒容易在高峰期打到限流。3.3 升级版接入自定义工具让 Agent 能查你的内部数据真实业务里光让 Agent 搜公网不够它还需要查你自己的数据库、调用内部 API。这时候就用到自定义工具。下面演示一个接入数据库查询的工具import json from openai import OpenAI client OpenAI() # 假设这是你的内部函数实际可以换成数据库查询或调用内部服务 def query_customer_stats(month: str) - str: # 这里简单返回假数据演示结构真实项目换成数据库查询 data { 2025-01: {total_orders: 12000, avg_ticket: 356}, 2025-02: {total_orders: 13800, avg_ticket: 342}, 2025-03: {total_orders: 15200, avg_ticket: 361}, } return json.dumps(data.get(month, {error: no data})) agent client.agents.create( namedata-analyst, instructions你是数据分析师。用户问数据时必须调用 query_customer_stats 获取数据然后基于真实数据做分析禁止编造数字。, modelgpt-5-codex, tools[ { type: function, name: query_customer_stats, description: 查询指定月份客户订单数和客单价月份格式为 YYYY-MM。, parameters: { type: object, properties: { month: {type: string, description: 月份例如 2025-03} }, required: [month], }, } ], ) run client.agents.runs.create( agent_idagent.id, input2025 年第一季度每个月的订单量和客单价分别是多少哪个月增长最快, ) while True: run client.agents.runs.retrieve(agent_idagent.id, run_idrun.id) if run.status requires_action: # 官方 SDK 会根据工具名自动找到我们传入的函数并执行 client.agents.runs.submit_tool_outputs( agent_idagent.id, run_idrun.id, tool_outputsrun.tool_calls, # 具体参数名以 SDK 版本为准 ) elif run.status in (completed, failed, cancelled): break time.sleep(2)这里的关键是requires_action状态。它表示 Agent 在云端循环中决定要调用自定义函数但函数本身在云端没有实现需要你的服务端配合执行。你的服务端拿到工具名和参数执行本地函数把结果返回给云端Agent 会继续往下跑。这个过程本质上是“人机协作”Agent 负责规划你的代码负责提供执行能力。要不要把这个协作封装得更优雅取决于你的项目复杂度。我见过有人就维护一个巨大的if tool_name xxx分发器也能跑但代码很丑建议自己封装一个注册表函数用装饰器注册工具列表自动从注册表生成这样加工具只改一处。3.4 踩坑笔记第二轮就跑挂了的教训读者最好奇的一定是坑我也排过几个有代表性的。第一个坑是instructions 写得太短太泛。刚开始我写“你是助手回答问题”结果 Agent 拿到开放任务后乱撞有时候搜都没搜就直接编。后来把指令改成固定流程步骤明确“先做什么再做什么什么时候停止”行为稳定多了。Agent 开发里指令就是产品需求文档写不清楚行为一定飘。第二个坑是Agent 陷入死循环。遇到过一次 Agent 反复调用同一个工具、得到相同结果、然后再次调用一直不停。排查后发现是工具返回结果太简单模型没拿到足够信息判断下一步。解决办法在工具返回值里给足上下文让模型能做决策。还有成本上要小心我测试时遇到过一次循环 20 多轮账单数字非常难看。第三是并发量大之后线程池被打爆。早期我的实现是收到 tool_call 就用线程池执行回调默认线程数无上限结果同时跑 20 个 Agent 任务时系统直接假死。后来改成有界信号量同时只允许 8 个回调运行其余的排队系统立刻稳了。4. Agents API 与 Codex CLI、Assistants API 的横向对比与选型建议很多朋友之前都用过 Assistants API或者本地 Codex CLI现在 Agents API 出来了怎么选我整理了一张对比表。4.1 一张表看懂核心差异维度Agents APIAssistants API旧Codex CLIAgent 循环云端托管自动执行半托管需手动处理 tool call本地或云端交互式工具调用自动调用托管工具和自定义函数需要开发者手动推工具结果内置文件、终端等工具运行环境OpenAI 云端需要配合自己的调度本地环境或云端 IDE适用任务多步自动化、无人值守流程老项目迁移单轮工具调用居多开发者本机编码辅助会话管理支持多轮对话云端维护状态Thread 模型需要手动管理会话在本地比较随意部署门槛极低一个 API Key 即可需要自建状态管理需要安装 CLI 和认证从表里能看出来Assistants API 属于过渡产物它的 Thread 模型当时看起来先进但 agent loop 还是要自己写——拿到requires_action后手动执行工具、手动把结果塞回去。Agents API 把这个流程完全自动化了。如果你还没有深度绑定 Assistants API直接上 Agents API别犹豫。4.2 什么时候选它什么时候绕开我的选型经验是这样的任务是多步骤、多工具、有明确目标的比如“搜集资料 - 分析 - 生成报告”选 Agents API。任务是实时对话、低延迟要求高的比如聊天机器人选普通的 Responses API加个工具调用即可。因为 Agents API 这种“让模型自主规划”的模式延迟不可控不适合在线交互。任务是本地代码库操作比如写代码、跑测试Codex CLI 依然是第一选择它在本地有终端、文件系统和开发环境集成度高Agents API 主要在云端操作处理不了本地私有代码。如果你需要人工审批环节比如 Agent 要执行一个高风险操作比如发送邮件、删数据Agents API 也支持 human-in-the-loop 的审批流可以让 Agent 在执行关键工具前“暂停”等人确认。这个能力很实因为很多自动化流程不敢全自动有一环人工卡着心里踏实。还有一类值得注意的场景多 Agent 协作。Agents API 原生支持 agent handoff就是一个 Agent 干了一半发现这个任务应该由另一个更专业的 Agent 来做可以直接移交过去。比如客服场景前台 Agent 接到退款请求判断这个问题需要专门处理退款流程的 Agent就把会话整体移交过去。这个机制比我之前用消息队列自己编排多 Agent 要优雅得多不用再自己设计复杂的流程引擎。5. 常见问题速查表与排查实录最后这部分是我这几天高频遇到的坑整理成一个速查表方便你出问题时对着查。5.1 认证、网络和 endpoint 类问题报错或现象原因解决办法auth token is unavailable使用 Codex CLI 时登录态失效或环境变量没传重新登录 CLI用 API Key 时确认OPENAI_API_KEY已设置接口 404可能没带OpenAI-Beta头或 base_url 指向了不支持该接口的网关请求头加OpenAI-Beta: agentsv1检查 base_urlconnection error本地代理不可用或网络波动检查并暂时清空代理环境变量重试rate limit exceeded频率超限指数退避重试间隔拉大关于cc switch local proxy failed while handling codex endpoint /responses这类报错核心问题是网络链路不稳定。我建议调试阶段先用官方 API 直连跑通了再考虑上网关或者代理。不要网络都还没通就急着调业务逻辑这对排查问题是最低效的顺序。5.2 运行期错误与上下文问题场景现象处理思路agent execution terminated due to error.run 状态直接变 failed在 run.last_error 里拿详细原因通常是指令冲突、工具返回格式错误、上下文超出限制run 一直 pending长时间没变化检查是否在等待工具回调检查模型是否过载设置超时兜底Agent 答非所问搜索了相关结果但输出方向偏加强 instructions 里对输出格式的约束用“必须包含”“ 禁止”这类强指令多轮对话串味每一轮都像新会话没有记忆检查是否传了 conversation_id不传就是每次独立会话重点是agent execution terminated due to error的排查思路。这个报错是个笼统的兜底你去拿到last_error才能看到真正原因。最常见的两类一是工具返回值超出了模型能处理的范围把返回值截断到 5000 字以内会好很多二是 Agent 在执行过程中 token 用尽长任务会在中间某一轮爆掉。解决办法是把任务拆成更小的子任务别让一个 run 做太多事。5.3 成本、清理与监控建议Agents API 因为是云端循环成本模型和传统 API 不一样我分享几个实测后的省钱技巧每个 run 前先想清楚任务边界。开放性的任务可能会让 Agent 无限搜索成本完全失控。所以 instructions 里必须写清楚终止条件“找到足够信息就停止”“最多搜索 3 次”。这比省钱参数管用得多。删除不用的 Agent。Agent 对象本身不贵但如果你给 Agent 挂了文件索引file_search存储成本和索引成本是持续的。测完的项目记得清理。监控用事件流而不是轮询。事件流模式下你能拿到每一步状态方便在 Agent “跑偏”时主动 cancel。轮询模式只能两秒一查白白浪费 API 配额还发现不了问题。备一个取消操作的示例长任务跑出问题的时候直接终止client.agents.runs.cancel(agent_idagent.id, run_idrun.id)这个操作我在本地测试时发现cancel 不是瞬时的它要等当前步骤结束才会真正停下来。所以如果你发现 Agent 已经跑偏了越早 cancel 越好别等。我个人在实际操作中的体会是Agents API 让我把之前自己搭的那套 agent 调度框架删掉了一大半复杂流程里那些“自己维护循环、自己处理中断、自己组装上下文”的脏话全被云端托管了。现在我做 Agent 项目的流程是先想清楚任务边界和终止条件再定工具集最后才写业务代码。它不完美比如云端执行对你来说是个黑盒出问题不好排查但它把 Agent 开发的入场门槛砍掉了一大截。如果你之前被 agent loop 折磨过会明白这种“直接把运行时当 API 用”的体验有多舒服。建议你可以拿一个最小的真实场景先跑跑看那种“提交任务后不用守着过几分钟回来收结果”的体验确实不太一样。