搬砖程序员带你飞
搬砖程序员带你飞

openai-python v3.13.0 内置托管 Agents API：agent 运行时该放平台还是留本地？

lpflpf
   约 3345 字  预计阅读 7 分钟 

9/10 openai-python v3.13.0 的 release note 只有一行「feat(api): add Agents API」，但代码里其实塞进了一整套 beta.agents——一次 API 调用就能跑起 Codex 那套托管 harness，会话、上下文压缩、沙箱全由 OpenAI 管。代价是把状态和密钥收上了平台，数据还只在美国。这篇文章就替后端/AI 开发者算清这笔账：什么情况下托管划算，什么时候别碰。

先说结论：托管 Agents API 不是「又一个 SDK」，而是把 agent 运行时从应用侧搬到平台侧。你要做的不是挑框架，而是先按一张「运行时责任清单」逐项核对谁管循环、状态、压缩、密钥、沙箱，再决定迁不迁。

一行 release note，下面多了四个资源

先看主证据本身。openai-python v3.13.0 于 2026-09-10 发布，release note 极简，只有一行：

feat(api): add Agents API

但落地代码在 src/openai/resources/beta/agents/ 下，挂了四个子资源：agents.py、environments/、sessions/、vaults/。仓库现在 31.6k star。这四个词已经剧透了托管的范围——不只多一个「调用模型」的接口，而是 session（会话生命周期）、environment（执行沙箱）、vault（凭据保险库）都被抽象成了资源。

同一周，anthropic-sdk-python v1.5.0（也是 9/10）也在给 Managed Agents 加 auto mode tool permissions。这是两个独立事件，别当它们有因果关系，但方向上确实一致：两家都在把 agent 运行时从应用侧往平台侧收。这让你现在的选型不是「换个 SDK」，而是一次运行时归属的重划。

托管 Agents API 到底替你管了什么

官方 9/10 发布「Introducing the Agents API」，公开 beta。一句话：OpenAI 托管的是 Codex 的 harness（官方叫 managed Codex harness），你提供工具、选执行环境。

它替你管的，是把长运行 agent 从「跑得起来」到「跑得稳」的那些脏活：

  • 会话编排（orchestration）：多轮循环、子代理调度都交给平台，你不用自己写主循环。
  • 上下文压缩（context compaction）：session 快接近上下文上限时自动压缩早期上下文，保留关键信息——这以前要么自己写要么交给 SDK。
  • 故障恢复（recovery）：长任务中断后的续跑逻辑平台处理。
  • 工具检索与程序化工具调用（tool search / programmatic tool calling）、多代理并行子代理。

环境分三类：openai_hosted（OpenAI 托管沙箱，就是 Codex 那套隔离）、self_hosted（自己或伙伴的沙箱，官方列了 Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercel）、以及凭据放 vaults。

一个 API 调用就能建一个生产级 agent，Python 侧长这样（官方 quickstart 代码）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {"type": "http", "server_url": "https://developers.openai.com/mcp"},
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "研究怎么给 OpenAI agent 接 MCP server，看下最近的更新，总结推荐做法。"}],
        }
    ],
)

等价 curl 是 POST https://api.openai.com/v1/agents/sessions，注意要带 OpenAI-Beta: agents=v1 这个头，漏了直接报错。模型当前示例是 gpt-6-astra，说明这个 API 默认绑在自家模型上。

关键权衡：一张「运行时责任清单」

这一节是核心。别去比 SDK 功能表（那已经有大量重复文），用「运行时责任归属」来判：同样是 2026 年，你以前要么自己写、要么交给开源 SDK 的活，托管版替你管到哪一层、代价是什么。

运行时职责 开源 Agents SDK（openai-agents-python） 托管 beta.agents
主循环 / 编排 应用侧，你写或 SDK 代管 平台侧，managed harness
会话状态 你的进程 / 你的存储 平台保留，跨 turn 续跑
上下文压缩 自己实现或接 SDK 平台自动 compact
工具执行 你自己拉起工具进程 你在 environment 里自供工具
密钥 / 凭据 你管 上移平台 vaults
沙箱 你的机器 / 容器 平台或伙伴沙箱

把这张表往下读，你会发现真正改变的不是「谁调模型」，而是「审计边界和密钥归谁」：

  • 密钥上移：凭据从你的进程挪进 vaults，本地方没法直接在代码里读。这对「密钥只出不出内网」的安全策略是结构性变化，不是改个配置。
  • 审计边界：agent 执行历史、工具调用日志落到 OpenAI 平台，你拿到的是 session 事件流，不是本地进程日志。合规审计要重新设计链路。
  • 成本归属：官方口径「no additional fees for using the Agents API – you simply pay for the tokens and tools」——但这是指没有「API 使用费」，沙箱/环境本身是否另计，公告没写清楚，要以定价页为准，别当完全免费。长会话的 token 消耗（含自动 compact 前的大量上下文）才是大头。
  • 退出与迁移成本：一旦状态和编排都长在平台上，你想迁回开源 SDK 或换供应商，等于把会话状态和编排逻辑重写一遍。这是很多人低估的隐性成本。

一句话：托管合算的前提是「状态和密钥上移平台」在你的业务里是可接受的。不可接受，就直接留在本地，别纠结。

硬约束与不适用场景

这部分是决定「别碰」的硬门槛，写在前头让你省时间：

  • 数据驻留仅限美国（US-only），且不支持 ZDR（Zero Data Retention）。更关键的是——就算你用 self-hosted 沙箱，也不能让 Agents API 获得 ZDR 资格。金融、医疗、欧盟/国内合规敏感的业务，基本直接出局。
  • beta 接口可能变。官方明说「we’ll iterate quickly toward GA」，接口名、参数、响应结构都可能动。要上就锁版本，别追 latest。
  • 平台与模型锁定：托管 harness 默认绑 gpt-6-astra 这类自家模型，不像开源 Agents SDK 能换 100+ 模型或接本地推理。多模型策略或离线需求，托管不适合。

哪些人适合先试：能把数据放美国、对供应商锁定不敏感、想快速验证「agent 能不能跑稳」的团队——从轻量任务（一个 web_search 工具查个资料）起步，别一上来就迁核心链路。

落地：最小可行验证路径

别一上来就全量迁移。用五分钟走一遍，让账单和事件流说话：

  1. 起一个 openai_hosted 的 session，跑一条指令（就用上面那段 Python，把 environment 换成 {"type": "openai_hosted"}）。
  2. 拉 session 的事件流，看它真的替你做了哪些 step：多轮工具调用、是否自动 compact、子代理有没有起来。这是判断「托管帮你省了多少活」的直接证据。
  3. 看这次调用的 token 账单。算清楚：同样的任务，你自己写循环 vs 托管，token 差多少、有没有产生你原来可以省掉的重复上下文。
  4. 再决定要不要上 self-hosted 沙箱，以及要不要把密钥放进 vaults。

验证完，对照上面那张责任清单重新勾一遍，你的答案大概率就出来了。

给今天就能做的下一步：打开你的 openai-python 依赖，pip show openai 看版本，如果已经 >= 3.13.0，就在一个测试环境起一个 openai_hosted session 跑一条和业务无关的指令，看事件流和账单——这一步成本几乎为零，却能让你把「托管省不省事」从想象变成数据。

一句话收束：托管 Agents API 的价值不是「少写循环」，而是「把状态和密钥交给平台后，审计边界和退出成本你能不能承受」。先勾责任清单，再谈接不接。

参考与验证

本文关键事实均核验于一手来源（访问日期 2026-09-12）：

  1. openai-python v3.13.0 release（2026-09-10，feat(api): add Agents API）：https://github.com/openai/openai-python/releases/tag/v3.13.0
  2. OpenAI 官方公告「Introducing the Agents API」（2026-09-10）：https://openai.com/index/introducing-the-agents-api
  3. Agents API 概览与数据控制（US-only、无 ZDR、self-hosted 不豁免）：https://developers.openai.com/api/docs/guides/agents-api/overview
  4. Python 代码示例（quickstart）：https://developers.openai.com/api/docs/guides/agents-api/quickstart
  5. anthropic-sdk-python v1.5.0 release（2026-09-10，Managed Agents auto mode tool permissions）：https://github.com/anthropics/anthropic-sdk-python/releases/tag/v1.5.0

说明：本文为公开资料分析，未在本机实际运行 Agents API。环境/沙箱计费未在官方公告列明，以定价页为准。

更新于 2026-09-12 
CC BY-NC 4.0
aiagentOpenAIPython后端
返回 | 主页
0%