OpenAI Agents API:托管式Codex工具集及团队仍拥有的权限。
OpenAI的Agents API可为您运行Codex框架,支持会话、MCP工具、子代理以及沙箱环境。而您的团队仍需负责:验证、访问权限以及数据管理。
来源: OpenAI’s Agents API: The Code You May No Longer Need to Write
想象一下,有位工程师负责处理那种只有在客户重新提交失败的请求时才会出现的故障。他先阅读相关工单,搜索代码,试图找出可能的原因。但随后情况变得复杂起来:需要安装依赖项,必须重新复现故障,另一个服务也需要检查,同时还得运行各种测试。就在处理过程中,一位同事补充了一个关键信息:只有旧版本的客户端会受到影响。
此时,负责处理该故障的代码需要处理大量任务:它必须保存目前已有的分析结果,纳入新的信息,维持正常的工作环境,并记录所有已经检查过的内容。断开的连接不应让调查工作重新从零开始。
OpenAI的Agents API正是为这类任务而设计的。它以托管服务的形式提供Codex框架,由OpenAI负责会话管理、任务协调、上下文压缩与恢复等工作。从工程角度而言,那些保障智能体高效运行的底层功能可以转化为平台特性,这样团队就无需为每个应用重新构建这些功能。同时,这也改变了团队需要重点关注的内容。
框架才是关键所在
模型可以判断出需要打开文件或运行测试,但仍有其他软件需要执行这些操作、返回结果并准备下一次模型调用。这类软件就是框架,随着任务复杂度的增加,它的职责也会相应扩大:管理对话流程、协调各种工具、应对中断情况,并帮助智能体保持工作连贯性。
Agents API允许其他应用程序使用经过管理的Codex框架版本。其已记录的功能包括总结之前的工作以管理上下文、应用技能、将子任务分配给其他智能体以及恢复会话。OpenAI对不同运行时的对比将选项分为三类:
- Agents API:由OpenAI运行Codex框架并维护智能体会话。
- Agents SDK:智能体循环在您的应用程序内部运行,因此您可以更紧密地控制集成与部署。
- Responses API:您的应用程序直接处理模型的原始响应,并自行设计相关的工作流程。
由于 Responses API 也具备状态管理功能,因此保存的对话记录并非划分界限。Agents API 的新增功能在于会话管理以及托管式的智能体运行环境。有一种观点认为,这改变了以往常见的架构决策:在编写新的协调层之前,团队可以先评估其中有多少部分确实需要由自己来实现。
跟进一项调查
再以重试错误为例。下面的工作流程仅是一种方案,并非对已运行系统的实际报告。应用程序会创建一个包含相关指令、工具及合适工作环境的会话,然后要求智能体重现故障并加以解释,同时引用相关的代码和测试结果。
根据会话文档,会在不同轮次之间保留的包括智能体的配置、对话内容以及已保存的任何工作成果。一轮次即为一个工作周期。当会话处于空闲状态时收到的输入会开启新的一轮次,而在当前工作进行中发送的输入则会继续推进当前轮次。可以通过流式传输或 webhook 来跟踪进度。这样一来,旧版本客户端也能获得明确的处理方向:它们可以直接加入正在进行的任务,而无需重新发起请求或重建历史记录。
接下来是问题追踪系统提供的功能。通过模型上下文协议,服务器可以提供用于搜索问题或获取记录的工具,而智能体 API 能够发现这些工具并向服务器发起请求,这样应用程序就无需逐一处理这些请求。这里的“发现”指的是在已配置的服务器上查找可用功能。不过仍需有人负责搭建合适的系统并设置合理的访问权限。
该代理还可以划分任务,让一个子代理负责研究重试处理机制,另一个子代理则检查旧版客户端是如何发起请求的。多代理架构的文档中描述了子代理各自的独立工作环境,而主代理则负责协调并整合它们的结果。这种方式在问题相互独立时很有效。但如果两个子代理都需要修改同一个函数,协调问题又会出现,OpenAI的指南也明确指出需要对共享文件的修改进行协调。该运行时的显著特点在于,所有这些操作都是围绕同一项持续进行的工作而相互关联的。
会话仍需要一个工作空间
阅读问题并运行复现测试需要不同的资源。根据架构文档,用于运行模型和工具循环的框架与执行环境是分开的,后者会在需要时提供计算资源及文件。您的应用程序负责提交任务、接收事件,并处理其定义的各类功能工具。共有三种环境选项:
- 无环境:代理可以直接调用其配置好的工具,无需shell环境,也没有工作区文件。
- 由OpenAI托管:系统会为您创建并运行一个沙箱环境,命令可在其中执行,文件及生成的成果也会存储在其中。
- 自行托管:您负责提供计算资源及文件,应用程序则负责相关的设置与清理工作。
在缺陷排查过程中,环境必须包含代码、其依赖项以及测试环境配置。即便会话能够记录排查过程,也无法弥补缺失的包或无法访问的测试服务所带来的问题。另一个重要区别也值得注意:OpenAI的文档指出,会话的生命周期可能长于其所在环境,而在自托管执行模式下,应用程序需自行负责计算资源与文件管理。仅仅记住某个测试文件曾被创建,并不意味着它仍然存在,团队在承诺可以顺利继续测试之前,应当同时检查这两点。
保存工作成果并不等同于证明其正确性
假设测试运行结束后得到了令人信服的解释以及绿色测试结果,工程师仍需确认该测试是否真正复现了最初的故障。有可能测试使用的是当前版本的客户端,而缺陷实际上存在于旧版本中;也有可能测试脚本被人为修改过,以至于不再检测那些异常行为。
这就是责任划分的所在。运行时提供了继续执行任务的机制,而应用团队则负责定义何种证据可视为任务已通过验收。在本次调查中,这意味着需要有人能够复现的故障、所分析的具体代码版本、每条命令的执行过程及其输出结果,以及任何剩余的疑问。即便由平台自动循环处理,这些要求也仍应纳入工作流程之中。
代码压缩同样需要重视。摘要会将之前的工作内容压缩到模型可处理的上下文中,但关键决策也应被记录在可供人们查阅的持久性文档中。在此情况下,“仅支持旧客户端”这一要求必须始终作为任务验收标准的一部分。
另一个智能体的分析虽有一定参考价值,但不能视为独立的验证手段。两个智能体可能会持有相同的错误假设,或依赖同样的薄弱证据。由其他工程师重新运行的复现测试才是更可靠的依据。
权威指导也遵循同样的逻辑。OpenAI的沙箱安全指南指出,智能体生成的代码能够访问其环境所暴露的文件、凭证及网络,因此必须刻意设置隔离措施并严格控制访问权限。就这个例子而言,仅具备调查访问权限就已足够;允许查看失败的请求并不等同于拥有修改生产数据的权限。
如何判断
一个合理的测试会采用一种受限的工作流程,例如生成缺陷调查报告以供审核。将其与团队当前的方法进行对比:该方法能多频繁地产生可用证据、需要多少人工修正,以及在中断后恢复工作的可靠性如何。还需计算每个被认可结果的总成本,因为漫长的调查过程可能涉及大量的模型调用、工具使用以及子代理操作。
该 API 提供会话日志、事件记录、保存的历史记录以及令牌使用情况查看功能。文档中也指出了目前的限制:跟踪信息检索和外部跟踪信息导出功能并不包含在公开测试版中,这对于已有监控体系的团队而言很重要。数据相关要求也需要提前了解。概述中提到,在该文档编写时,Agents API 仅支持将数据存储在美国境内,且不提供零数据保留功能,而自托管沙箱也无法打破这一限制。
如果这些限制可以接受,那么问题就转向了实用性:托管运行时能否减少足够的基础设施管理工作,从而使其成为值得依赖的选择?有些团队会喜欢这种交换方式,而另一些团队则希望拥有 SDK 或自行编排的能力。
整体趋势是积极的。控制上下文、运行代码、协调智能体以及推进工作这些功能现在都被视为共享基础设施,这进一步印证了这样一个观点:实用的智能体既依赖于模型本身,也依赖于模型周围的系统。其好处在于,可以将节省下来的工程时间用于提升结果的可靠性。在重试场景中,这意味着可以将可复现的故障及可供检查的证据交给下一位工程师。
此内容基于2026年9月15日审核的OpenAI官方文档。其中的工作流示例与评估建议属于工程分析,而非基准测试结果。
相关阅读
- 为何编码代理仍难以处理私有公司代码 — Real-SWE对八个编码代理在经过授权的私有代码库上的表现进行了测试。表现最好的代理也只能解决38.8%的问题,而五种失败类型则揭示了代理出错的原因。
- 在VS Code中使用Codex:作用范围、恢复点以及常见问题的解决方案 — 详细介绍了使用Codex VS Code扩展的完整流程:安装、登录、执行首个有限范围的代理任务、云端与命令行接口的区别、共享配置,以及针对WSL、审批流程和远程认证等问题的解决方案。