[TOC]

过去两年，开发者构建AI Agent时，通常需要自己维护一套循环：

接收任务 → 调用模型 → 解析工具请求 → 执行工具 → 返回工具结果 → 压缩上下文 → 判断是否继续 → 保存任务状态

真正麻烦的往往不是调用模型，而是处理会话状态、工具执行、上下文膨胀、任务恢复和多Agent协调。

现在，OpenAI把这些能力进一步封装成了独立的Agents API。

官方API中已经出现两个关键接口：

  • POST /agents
  • POST /agents/sessions

这意味着Agent不再只是某一次模型请求中的临时配置，而是可以保存、复用和单独管理的项目级资源。

问题也随之而来：

OpenAI开始托管Agent运行循环后，开发者自己写的Agent框架还有没有必要？

先说结论：有必要，但边界变了。

一、Agents API到底是什么？

在传统Responses API中，开发者提交一次请求，模型生成文本或者发起工具调用。

如果模型需要连续操作，应用必须在外部维护循环：

while not task_finished:
    response = call_model(history, tools)
    tool_calls = parse_tool_calls(response)
    results = run_tools(tool_calls)
    history.extend(results)

这段伪代码看起来很简单。

但真正落地时，还要继续解决：

  • 会话状态存在哪里；
  • 进程重启后如何恢复；
  • 工具调用失败如何重试；
  • 长上下文如何压缩；
  • 多个子Agent如何并发；
  • 哪些操作需要人工确认；
  • 如何保存Token使用量；
  • 如何限制单次任务预算；
  • 执行环境如何隔离；
  • 如何把中间事件实时返回前端。

Agents API试图把其中一部分基础设施交给OpenAI管理。

根据官方文档，一个Agent可以保存以下配置：

配置 用途
model Agent使用的模型
name Agent名称
instructions 长期指令
tools 可用工具
reasoning 推理配置
text 文本输出配置
service_tier 服务等级策略
multi_agent 子Agent协调配置
metadata 自定义业务信息

创建完成后，API会返回一个可复用的agent_id。

以后运行任务时，不需要每次重新提交所有Agent配置，只需要基于这个Agent创建Session。

二、Agent和Session有什么区别？

这是理解Agents API最关键的一步。

Agent是配置

Agent描述“谁来执行任务”：

  • 使用哪个模型
  • 拥有哪些工具
  • 遵循哪些长期规则
  • 是否允许创建子Agent
  • 采用什么推理和输出策略

它更像一个可以重复使用的工作模板。

Session是一次运行

Session描述“这次任务怎么执行”：

  • 本次输入是什么
  • 使用哪个Agent
  • 运行在哪个环境
  • 当前执行到哪一步
  • 是否等待工具结果
  • 是否需要人工确认
  • 已经消耗多少Token

一个Agent可以创建多个Session。

例如，可以先创建一个“代码审查Agent”，然后为不同项目分别创建Session：

代码审查Agent

├── Session A：检查支付服务

├── Session B：检查用户系统

└── Session C：检查日志模块

Agent的规则可以保持稳定，每个Session则拥有独立的输入、环境和执行状态。

三、它和Responses API有什么区别？

Agents API不是一个“比Responses API更聪明的模型接口”。

两者解决的问题不同。

对比项 Responses API Agents API
核心定位 模型响应与工具调用 托管Agent资源与运行会话
状态管理 主要由应用控制 Session负责更多运行状态
Agent配置 通常随请求提交 可保存为可复用资源
执行环境 开发者自行准备 Session可关联执行环境
多Agent 应用自行编排 提供明确的多Agent配置
工具结果 应用负责回传 Session通过Required Actions协调
任务恢复 应用自行实现 托管Session更适合持续任务
自定义程度 高 更标准化
平台绑定 相对较低 相对较高

可以这样理解：

Responses API = 给开发者模型能力和工具调用能力

Agents API = 在模型能力之上，再提供一层托管执行框架

如果应用只是进行摘要、分类、问答或者单次工具调用，Responses API已经足够。

如果任务需要运行很长时间、操作多个工具、创建子Agent或者在中断后继续，Agents API更有价值。

四、使用Agents API创建一个可复用Agent

下面使用TypeScript SDK演示基本结构。

安装SDK：

npm install openai

创建Agent：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const agent = await client.beta.agents.create({
  name: "Repository Reviewer",
  model: "gpt-6-astra",
  instructions: [
    "You are a code review agent.",
    "Prioritize security, concurrency, database compatibility and exception handling.",
    "When finding an issue, provide file location, impact and a fix suggestion.",
    "Do not perform deployment without confirmation.",
  ].join("\n"),
  multi_agent: {
    enabled: true,
    max_concurrent_subagents: 3,
  },
});

console.log(agent.id);

这个接口创建的是一个可复用Agent，而不是立即开始执行任务。

官方文档还特别说明，Agent资源不会保存调用凭证。API密钥和第三方服务凭证仍应由应用或者安全的密钥系统管理。

不要把数据库密码、云服务密钥直接写进instructions或者metadata。

五、创建Agent Session运行任务

获得agent_id之后，可以创建Session：

const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  environment: {
    type: "none",
  },
  input: "Check for possible concurrency security issues in the current project.",
});

console.log(session.id);
console.log(session.status);

创建Session时可以：

  • 引用已经保存的Agent；
  • 临时覆盖部分Agent配置；
  • 提交初始任务；
  • 指定执行环境；
  • 提供可访问的Vault；
  • 选择是否使用事件流；
  • 添加本次运行专属Metadata。

Session返回的信息包括：

  • Session ID
  • Agent配置
  • 运行状态
  • 执行环境
  • Required Actions
  • 最近活跃时间
  • 错误信息
  • Token使用量

这让开发者不必再把所有状态都塞进自己的数据库表。

不过要注意，官方文档将Session中的Token使用量描述为“best effort”，也就是可能继续变化，不能把运行中的数字当成最终结算结果。

六、Required Actions解决了什么问题？

Agent执行任务时，不是所有工具都能由平台直接运行。

例如，模型可能决定调用企业内部系统：

  • 查询订单
  • 修改工单
  • 发送邮件
  • 创建部署任务
  • 读取私有数据库

这时Session可能进入等待状态，并返回required_actions。

一个Function Call类型的Required Action通常包含：

  • call_id
  • turn_id
  • 工具名称
  • 工具参数

应用执行工具后，再将结果提交回对应Session，让Agent继续运行。

它的作用是把模型决策和真实业务操作分开：

Agent决定需要做什么

↓

Session返回Required Action

↓

业务系统检查权限

↓

应用执行工具

↓

工具结果交回Session

↓

Agent继续任务

这里不能省略权限校验。

即使模型提出了工具调用，也不代表它天然拥有执行权限。

七、多Agent是不是终于不用自己写了？

Agents API提供了显式的multi_agent配置，可以控制是否启用多Agent及最大并发子Agent数量。

例如：

multi_agent: {
  enabled: true,
  max_concurrent_subagents: 3,
}

这让主Agent可以把不同部分交给子Agent处理。

一个代码审查任务可以拆分为：

  • 主Agent：统筹任务和合并结论
  • 子Agent 1：检查安全问题
  • 子Agent 2：检查数据库兼容
  • 子Agent 3：检查性能和并发

但“支持子Agent”不等于多Agent系统不需要设计。

开发者仍然要决定：

  • 任务应该如何拆分；
  • 哪些子任务可以并行；
  • 子Agent能看到哪些上下文；
  • 结果冲突时以谁为准；
  • 最大并发是多少；
  • 何时停止继续派生任务；
  • 单个Session允许消耗多少Token。

如果不给多Agent设置边界，一个复杂任务可能迅速放大调用量。

八、自己写的Agent框架还有没有必要？

取决于业务需要什么。

适合使用托管Agents API的场景

  • 希望快速搭建Agent产品；
  • 不想自己维护长任务状态；
  • 需要托管执行环境；
  • 需要标准化的Agent和Session资源；
  • 任务经常运行多个回合；
  • 需要多Agent协调；
  • 可以接受较强的平台绑定。

适合继续使用自建框架的场景

  • 需要同时切换多个模型提供商；
  • 已经有成熟的任务队列和状态机；
  • 需要完全控制上下文压缩；
  • 工具执行必须留在内部网络；
  • 对数据位置和审计有严格要求；
  • 需要自定义重试、计费和熔断；
  • 不能把Agent运行状态绑定到单一厂商；
  • 需要在多个兼容API之间动态路由。

因此，Agents API不会直接淘汰LangGraph、AutoGen或者企业自研Agent框架。

它改变的是“哪些基础设施值得自己维护”。

九、不使用托管Agents API，如何实现一个轻量Agent循环？

如果暂时不需要托管Session，可以继续使用Responses API自己维护循环。

下面通过兼容OpenAI SDK的模型入口调用gpt-6-astra：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://genvis.xyz/v1",
)

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={
        "effort": "medium",
    },
    input=[
        {
            "role": "user",
            "content": (
                "Analyze the code structure of a Go API project, "
                "give a review plan first, then list the three modules "
                "most worth checking first."
            ),
        }
    ],
)

print(response.output_text)

这种方式调用的是Responses API，不是新的Agents API。

两者不能混淆：

模型兼容接口 ≠ 自动支持 /agents ≠ 自动支持 /agents/sessions

除非服务提供方明确说明支持Agents API，否则不要直接替换官方Agents API的Base URL。

这是接入时最容易踩的坑。

十、托管Agent和统一模型接口可以同时使用吗？

从架构角度看，它们解决的是不同层次的问题。

Business Application
├── Agent Orchestration Layer
│   ├── Managed Agents API
│   └── Self-built Agent Framework
│
└── Model Invocation Layer
    ├── Primary Model
    ├── Low-cost Model
    ├── Fallback Model
    └── Unified Compatible Interface

Agent编排层负责：

  • 会话；
  • 任务状态；
  • 工具循环；
  • 子Agent；
  • 执行环境；
  • 人工确认。

模型调用层负责：

  • 选择模型；
  • 调用接口；
  • 成本控制；
  • 失败回退；
  • 速率限制；
  • 多供应商切换。

因此，即使使用托管Agents API，企业仍然可能在其他业务中保留统一模型接口。

而选择自建Agent框架的团队，更需要把模型路由和Agent状态解耦。

十一、Agents API目前最值得警惕的五个问题

1. 平台绑定

Agent、Session和运行状态都采用平台定义的数据结构。

未来迁移时，需要转换的不只是模型名称，还有完整的任务状态。

2. Token预算失控

多Agent、长Session和反复工具调用可能迅速增加Token消耗。

建议为每个Session设置业务侧预算：

  • 最大运行时间
  • 最大模型调用次数
  • 最大子Agent数量
  • 最大输入Token
  • 最大输出Token
  • 最大工具调用次数

3. 工具权限过大

模型请求调用工具，不代表应用必须执行。

删除、转账、部署和发送消息等操作，仍应增加人工确认。

4. 运行状态不能代替业务审计

Session状态适合描述Agent运行过程，但企业还需要保存：

  • 操作者；
  • 业务对象；
  • 权限判断；
  • 工具输入输出；
  • 实际副作用；
  • 最终审批记录。

5. Beta接口可能变化

当前Agents API位于Beta命名空间。

生产环境接入时应封装自己的适配层，不要让业务代码直接依赖大量Beta类型。

十二、现在应该迁移吗？

可以按照项目阶段判断。

项目状态 建议
正在验证Agent产品 可以小范围试用
只有简单问答功能 暂时没有必要
已有成熟自建框架 先做对照测试
强依赖多模型路由 保留自建编排
需要快速实现长任务 值得尝试
涉及高风险业务操作 先完善权限与审计
生产系统稳定运行 不建议立即整体重构

最合理的做法不是立刻迁移，而是选择一个真实任务进行对照：

  • 相同任务
  • 相同模型
  • 相同工具
  • 相同预算

分别比较：

  • 任务完成率；
  • 总Token消耗；
  • 平均耗时；
  • 工具调用次数；
  • 失败恢复能力；
  • 开发维护成本；
  • 平台迁移成本。

常见问题

OpenAI Agents API和Responses API是一回事吗？

不是。

Responses API主要提供模型响应和工具调用能力；Agents API在此基础上提供可复用Agent和托管Session等更高层资源。

Agent可以重复使用吗？

可以。官方文档将Agent定义为当前Project范围内可复用的资源。

一个Agent可以运行多个任务吗？

可以。可以基于同一个agent_id创建多个独立Session。

Agents API支持多Agent吗？

支持显式的multi_agent配置，可以启用子Agent并限制最大并发数量。

Agents API会保存第三方服务密钥吗？

官方文档明确说明创建Agent时不会保存凭证。第三方密钥仍应放在安全的密钥管理系统中。

使用兼容OpenAI SDK的接口就能调用Agents API吗？

不能这样假设。

支持Chat Completions或者Responses API，不代表同时支持/agents和/agents/sessions。

自建Agent框架会被淘汰吗？

短期内不会。

托管Agents API适合降低基础设施开发成本；自建框架则在多模型路由、私有环境、数据控制和自定义状态机方面更灵活。

总结

OpenAI Agents API真正重要的变化，不是增加了两个接口。

而是Agent开始从“一段应用代码”，变成一种可以单独创建、保存、复用和运行的API资源。

开发者需要重新划分系统边界：

  • 哪些状态交给平台管理？
  • 哪些工具必须留在内部？
  • 哪些任务允许创建子Agent？
  • 哪些操作必须人工确认？
  • 模型调用是否需要多供应商路由？

如果只是快速构建长任务Agent，托管Agents API会减少大量工程工作。

如果业务需要多模型切换、严格审计、私有工具和完整控制，自建Agent框架依然有存在价值。

真正可能消失的，并不是所有Agent框架。

而是那些只实现了一个简单while循环，却没有状态管理、权限控制、预算限制和失败恢复能力的Agent框架。

参考资料

  • OpenAI：创建Agent
  • OpenAI：创建Agent Session
  • OpenAI：查询Agent
  • OpenAI：Responses API参考