Claude Managed Agents 7月22日更新：一次发布关闭三个轮询缺口

Anthropic 在 7 月 22 日对 Claude Managed Agents API 推送了五项变更。其中三项针对同一根本问题：运营商被迫通过轮询或冗余往返请求来确认资源就绪状态。本文覆盖这三项，并说明需要做什么才能让这些变更产生实际价值。

另外两项——让 agent 更新时 version 字段变为可选，以及在 agent 模型配置中新增 effort——是实质性改动，但影响范围足够窄，归为附录。

7 月 22 日关闭的三个缺口

7 月 22 日之前，Managed Agents 事件模型存在以下可观测的轮询陷阱：

1. 会话冷启动需要两次串行请求：先 POST /v1/sessions 创建会话，再单独 POST /v1/sessions/{id}/events 发送第一条用户消息。任何需要立即开始工作的调用方都必须等到第一个响应后才能发出第二个请求。

2. 子 Agent（线程）输出在完成前不透明：会话级流式端点（GET /v1/sessions/{id}/stream）允许预览顶层 Agent 的文本生成，但如果协调 Agent 委托给子 Agent，无法流式获取子 Agent 的输出，只能在完成后拿到汇总结果。

3. 环境和内存存储的就绪状态需要轮询：环境被创建、归档或失败，以及内存存储被创建、更新或删除时，唯一的反应方式是定时轮询 GET /v1/environments/{id} 或 GET /v1/memory_stores/{id}。

这三个缺口现已全部关闭。

initial_events：两次调用合并为一次

POST /v1/sessions 现在接受 initial_events 字段。传入最多 50 个事件——user.message 和 user.define_outcome 的任意组合——Agent 循环在同一次调用中启动。只要列表非空就足够了，无需再调用 POST /v1/sessions/{id}/events。

7 月 22 日之前：

# 步骤 1：创建会话
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent":"$AGENT_ID","environment_id":"$ENV_ID"}')
SESSION_ID=$(jq -r '.id' <<< "$session")

# 步骤 2：发送第一条消息——独立的网络调用，独立的延迟
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"events":[{"type":"user.message","content":[{"type":"text","text":"执行审计"}]}]}'

7 月 22 日之后：

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "agent": "$AGENT_ID",
    "environment_id": "$ENV_ID",
    "initial_events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "执行审计"}]
      }
    ]
  }')
# Agent 已在运行。SESSION_ID 在响应中。

实际节省是每次冷启动少一次网络往返。如果你在响应用户操作——聊天回合、Webhook 触发、定时任务——时启动会话，这次往返就在关键路径上。高并发下，它还多出一类请求需要纳入网关的并发计量。

值得注意的约束：每次创建调用最多 50 个事件，这不是批量突发机制。如果你的初始化逻辑发送超过 50 条种子消息，仍需后续发送请求。实践中，大多数会话初始化都远低于这个数字。

线程级增量流式传输：子 Agent 现在可以推送文本

当 Claude Managed Agent 协调子 Agent 时，每个子 Agent 在一个线程中运行。会话级流式端点（GET /v1/sessions/{id}/stream）接受 event_deltas[] 查询参数来预览顶层模型的文本生成，但线程端点不支持。

7 月 22 日起，GET /v1/sessions/{session_id}/threads/{thread_id}/stream 接受相同的 event_deltas[] 参数。

curl -N "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?event_deltas[]=text_delta" \
  -H "anthropic-beta: managed-agents-2026-04-01"

线程流式连接只预览目标线程，不跨线程聚合。如果你有一个协调器同时运行三个子 Agent，需要三个独立的 SSE 连接来并行流式传输全部三个。

对路由架构的意义：在多 Agent 流水线中，协调器线程通常很短——它委托然后等待。延迟预算主要由子 Agent 线程决定。此前，向下游用户展示增量进度的唯一方式是：(a) 流式传输顶层会话，获得稀疏的协调器注释；或 (b) 定时轮询线程的事件日志。两种方式都不理想。线程级增量让你可以实时将特定线程的输出代理到前端，就像直接代理 API 调用一样。

实用组合：session.thread_created Webhook → 建立线程流式连接 → 将文本增量流式传输到客户端。这三步模式现在可以全程无轮询地端到端运行。

七个新 Webhook 事件类型：停止轮询环境和内存存储

Managed Agents Webhook 目录现在覆盖两类资源的完整生命周期，此前运营商被迫轮询。

环境事件（4 种）：

内存存储事件（3 种）：

Webhook 载荷遵循现有模式：传递事件类型和 ID，而非完整资源对象。收到 Webhook 后，用 GET 调用获取当前资源状态。这使每次传递体积小，重试时也不会传递过期数据。

此前的状况：如果你的运营商基础设施动态创建环境（每租户一个、每部署一个等），你没有就绪状态的推送信号。常见的变通方案：每隔几秒轮询 GET /v1/environments/{id} 检查 status，N 次重试后放弃。内存存储也有同样的问题，尤其是在创建后立即附加到会话的工作流中。

现在可以做什么：注册 Webhook 端点捕获 environment.created 和 environment.failed，收到后获取环境对象，据此路由。一个 Webhook 处理器替代了一个轮询循环及其错误处理样板代码。

运营上要注意：这些事件与其他 Managed Agents Webhook 同样遵循至少一次传递语义。你的处理器必须按事件 ID 实现幂等。如果你已经在处理会话生命周期 Webhook，这一点你已经具备。

跨提供商对比

OpenAI 的 Realtime Agents 和 Gemini Managed Agents 都覆盖会话生命周期 Webhook 事件，但截至本文撰写时，两者均不向运营商暴露环境或内存存储生命周期事件。特别是 environment.failed 事件类型——云沙箱配置失败时的推送通知——在其他竞争框架中没有对应实现，轮询沙箱就绪状态是其他地方的常态。

线程级流式传输也有差异：Gemini Managed Agents 流式传输协调器输出但不暴露子 Agent 级别的流；OpenAI 没有为子 Agent 文本提供线程范围的 SSE。如果你的路由架构需要在 UI 中展示子 Agent 进度——这是编码 Agent 和研究 Agent 中带有可见并行工作流的常见需求——Claude 的线程流式传输是目前无需自定义日志基础设施即可获得每子 Agent 文本增量的唯一方式。

version 和 effort 新增（附录）

Agent 更新时 version 现为可选：PATCH /v1/agents/{id} 之前要求 version 用于乐观并发控制，现在为可选。省略它可无条件应用更新；包含它则在版本不匹配时返回 409。如果你的代码将当前版本作为必填字段传递，无需更改。如果你为了绕过这一要求而总是先获取再修改，现在可以简化该逻辑。

Agent 模型配置中新增 effort：创建或更新 Agent 时，现在可以在 model 对象中设置 effort。这与现有的每会话配置覆盖机制相结合——effort 可以在 Agent 定义级别设置，并可在每个会话中覆盖。当你希望路由到同一 Agent 的不同任务类型有轻量级默认和更重的覆盖时很有用。

{
  "model": {
    "name": "claude-sonnet-5-20261015",
    "effort": "low"
  }
}

Effort 级别（low、medium、high）的行为如 Anthropic 的 effort 级别参考 所述。如果你已经在使用每会话 effort 覆盖（7 月 2 日版本中覆盖），这为你在 Agent 定义时设置更清晰的默认值提供了路径，而不是要求每个会话创建者都传递覆盖。

路由架构需要做的调整

这些变更向后兼容，不会破坏现有功能。但有三件事值得更新：

1. 会话初始化代码：如果你分两步创建-发送，改用 initial_events 合并。每次会话冷启动减少一次往返。

2. Webhook 处理器：添加 environment.* 和 memory_store.* 的处理分支。如果你有任何轮询循环检查环境或内存存储状态，一旦 Webhook 处理器覆盖新事件类型，就可以替换掉。

3. 多 Agent UI 渲染：如果你向用户展示子 Agent 活动，从 session.thread_created 事件中添加线程 ID 跟踪，并为每个子 Agent 建立线程流式连接。之前的方式（会话级流式传输加稀疏协调器注释）低估了运行内部实际发生的事情。

可选 version 变更和 Agent 级 effort 是增量添加，除非想简化现有代码，否则无需修改。