Agents API 现身 OpenAI SDK（beta）：/agents CRUD、environments、sessions 与 vaults 全景

2026-09-10 19:37 UTC，openai-python v3.13.0 与 openai-node v7.15.0 在同一分钟内发布，release notes 的 Features 各写一行——"add Agents API"。距离 Assistants API 关停（2026-08-26）刚好 15 天，SDK 类型层出现了一个全新的智能体接口面：可复用 Agent 的 CRUD、绑执行环境的托管会话、子智能体与凭据保管，四层资源一次到位。

继续沿用本站 SDK 情报文的纪律：只陈述能在 SDK 源码里逐字指出的东西。所有引用来自 2026-09-11 当日重抓的 GitHub release notes 与 v3.13.0 / v7.15.0 tag 源码；OpenAI 官方文档域当日对本站 403，官方公告侧状态一律日期锚定。

1. 概述：四个资源面与一条边界

Agents API 是 2026-09-10 起 OpenAI 官方 SDK 类型层出现的智能体接口面（beta 命名空间）：

边界同样先画清楚：beta 命名空间、无可用性公告、无定价、无 GA 计划（截至 2026-09-11 核对，官方文档域对本站 403）。SDK 类型是自动生成的，它证明"spec 里有"，不证明"已对外提供服务"。

2. 首次出现核验与一个反直觉细节

2026-09-11 用 GitHub tag 树对照核验：

• openai-python v3.11.0 树里 resources/beta/agents 路径数量为 0，types/beta/ 下没有任何 agent 类型文件；v3.13.0 一次性新增 188 个 agent 相关路径（2026-09-11 两 tag 对照计数；v3.11.0 原有的 3 个 agent 字样路径——AGENTS.md 与 2 个 responses 示例——不含在内）
• openai-node v7.13.0 树里没有 src/resources/beta/agents；v7.15.0 起出现

一个值得单独指出的细节：SDK 命名空间与 HTTP 路径前缀不一致。资源类挂在 client.beta.agents（beta 命名空间，与历史上 beta 资源同模式），但方法拼接出来的 HTTP 端点是顶层的 /agents、/agents/sessions、/vaults——没有 /beta/ 路径段。做网关路由、抓包核对或手写 HTTP 调用时以实际路径为准；SDK 对这个不一致没有解释，本文也不解释。

3. Agent 本体：可复用、可 CRUD、可编排子智能体

Agent 对象（types/beta/agent.py）的类注释："A reusable agent scoped to the caller's project"——一个挂在项目下的可复用智能体。CRUD 端点齐全：POST /agents（create）、GET /agents（list）、GET /agents/{agent_id}（retrieve）、POST /agents/{agent_id}（update）、DELETE /agents/{agent_id}（delete → AgentDeleted）。

对象字段全景（v3.13.0 tag 源码）：

创建调用的最小示例（SDK 类型核对版，字段逐项对照 AgentCreateParams，未实跑）：

from openai import OpenAI

client = OpenAI()

agent = client.beta.agents.create(
    model="gpt-5.6-terra",           # 必填，自由字符串
    name="docs-triage-agent",        # 可选
    instructions="优先按严重度分组",   # 可选，追加在基础指令之后
    service_tier="flex",             # 可选：auto/default/flex/priority/fast
)
print(agent.id, agent.object)        # ...  "agent"

两个值得划线的语义：

• instructions 是追加不是覆盖——SDK 原文 "Custom instructions appended to the agent's default base instructions"。这延续了 Assistants 时代 instruction 的心智模型，但基础指令内容是什么、能否关掉，类型层没有信息。
• service_tier 里出现了 fast——与 world 记录的 Fast mode（2026-08-05 长上下文支持）同名。枚举层面这是 Agent 请求模型时可选的服务档，两者是否同一机制，SDK 没有关联注释，不推断。

4. Managed Agents session：状态机 + 执行环境 + 必要动作

POST /agents/sessions 创建会话。AgentSession 的类注释："A Managed Agents session"——"托管"二字落在字段上：

• 状态机：status 四值——idle / in_progress / requires_action / failed（外加 error 字段承载失败原因）
• required_actions：SDK 原文 "Actions that must be completed before the session can continue"——会话跑到需要外部输入（比如工具审批）就挂起等你
• environment："The execution environment for the session"——每个会话绑一个执行环境
• usage：Optional[TokenUsage]，token 用量进会话对象
• agent 快照：会话里嵌的 Agent 的 name 是创建会话时的快照，SDK 原文注明 "Later changes to the agent's name do not affect this value"——改了 Agent 名字，老会话里还是旧名

会话下挂一组子资源端点（均在 /agents/sessions/{session_id} 之下）：items（会话条目）、events（事件流）、artifacts（产物，含 GET .../artifacts/{id}/content 下载内容）、subagents 与 subagents/{subagent_id}/turns（子智能体及其轮次）。

条目（item）类型直接暴露了 Agent 的行为面：agent_function_call_item（函数调用）、agent_command_execution_item（命令执行）、agent_mcp_call_item（MCP 调用）、agent_create_subagent_call_item / close / interrupt（子智能体的创建、收束与打断）。也就是说，一个 Agent session 的执行轨迹里，函数调用、shell 命令、MCP 工具、子智能体调用都是一等公民。

5. Environments：一等执行环境，带 templates 与 files

环境信息对象（EnvironmentInfo）的类注释值得整段引用："Safe metadata for a first-class execution environment"——一等的执行环境。字段：id、files（环境内已安装的文件，不含内容本体）、plugins（不含压缩包内容）、skills（不含内容）、object 固定 agent.environment。

配套管理端点：

• POST/GET /agents/environments/templates、.../templates/{environment_template_id}——环境模板的创建与列表（模板化环境配置）
• /agents/environments/{environment_id} 与 .../files——环境实例与其文件管理

skills 与 plugins 出现在 OpenAI API 的执行环境里，意味着 Agent 生态（本站此前在 MCP 与 Custom GPT 语境下分别讨论过工具与技能）可能正在向"环境预装"方向收敛——但这是字段结构给出的形态信号，官方没有能力说明，不展开推断。

6. Vaults：把凭据从代码里拿出来

/vaults、/vaults/{vault_id}、/vaults/{vault_id}/credentials、.../credentials/{credential_id} 构成凭据保管资源族。SDK 类型层能确认的就这么多：vault 是容器、credential 是内容；credential 的具体形态（API key？OAuth token？）在当次提取的类型清单里没有展开，本文不猜。方向本身值得注意——Agent 替你调外部工具时，凭据不进代码、不进 prompt，挂在 vault 里按会话授权，这是 Agent 安全模型的正确形态。

7. 时间线并置：距 Assistants API 关停 15 天

只并列事实，不下因果结论：

• 2026-08-26：Assistants API 关停（官方 changelog 原文 "The Assistants API shut down on August 26, 2026"），当时官方给出的迁移方向是 Responses API / Conversations API（见本站《OpenAI 生态第 42 周速报（2026-08-30 至 2026-08-31）：Assistants API 已关停 / Sol 降价确认 / 转写模型弃用》）
• 2026-09-10：Agents API 以 beta 形态出现在两包 SDK 类型层，资源面（可复用 Agent + 托管会话 + 执行环境 + 凭据）在概念上与 Assistants 的 Assistant / Thread / Run 三层有可比性，但字段与语义并不一一对应

两者之间是否有承接关系，官方截至 2026-09-11 没有任何说明。对刚做完 Assistants 迁移的团队，正确的动作不是掉头再迁一次，而是：迁移成果（Responses / Conversations 路径）不动，把 Agents API 当作观察对象，等官方公告。

8. 常见错误与排查

• 把 beta 资源面当 GA：client.beta.agents 在 beta 命名空间，端点存在 ≠ 服务开放。截至 2026-09-11 官方文档域对本站 403，无法核对开放状态。
• 按 SDK 命名空间猜 HTTP 路径：命名空间带 beta、路径不带。手写 HTTP 或配网关时直接对照源码里的路径拼接，别按命名空间推导。
• 以为 instructions 是全量覆盖：它是追加语义（appended to the agent's default base instructions）。基础指令内容类型层不可见，写提示词时别假设它是白纸。
• 穷举 status 不留默认分支：四值状态机是当前提取值；beta 接口的枚举随时可能扩展，switch 记得兜底。
• 刚迁完 Assistants 又想迁 Agents：官方迁移指引仍是 Responses / Conversations（08-26 公告），Agents API 无 GA 信息。观望 + feature flag 实验，别在生产里换马。

9. 下一步

• 《Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读》：同日 17:28 UTC 先落地的另一个全新 API 面。
• 《openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5》：本批之前两天的六版 SDK 更新解读，版本总表已含 v3.12.0–v3.13.0 / v7.14.0–v7.15.0。
• 《Responses API vs Chat Completions：该迁移了吗》：Assistants 关停后官方迁移路径的落地解读。
• 《OpenAI 生态第 42 周速报（2026-08-30 至 2026-08-31）：Assistants API 已关停 / Sol 降价确认 / 转写模型弃用》：Assistants API 关停当周的官方公告原文。
• 《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》：SDK 类型层情报的方法论源头。
• 《OpenAI 模型更新日志（2026 持续更新）》：全时间线视角，Agents API 的官宣（若发生）会在这里跟进。