Claude Opus 5 托管 Agent 实战：会话种子 + 中途换工具不掉缓存 + Webhook 事件驱动

过去创建托管 Agent 会话要两步：先建会话，再单独发一次调用把 Agent 循环启动起来。会话种子（session seeding）把这两步合成一步：

POST /v1/sessions
{
  "model": {
    "name": "claude-opus-5",
    "effort": "high"
  },
  "initial_events": [
    {
      "type": "user_message",
      "content": "把 data/ 目录下的 CSV 全部清洗并生成质量报告"
    }
  ]
}

# initial_events 非空 → 同一个请求内就启动 Agent 循环
# 不再需要额外发一次「开始」调用

这是三个改动里最实用的一个。以前工具定义是死的：想中途从「文件读取工具」换成「数据库连接器」，只能重启会话或重发整个 tools 数组——提示词缓存直接作废，延迟和成本都上去了。

# 带上 beta 头即可启用
anthropic-beta: mid-conversation-tool-changes-2026-07-01

# 然后就能在轮次之间改工具集
{
  "tools": {
    "add":    [ { "name": "db_query", "description": "..." } ],
    "remove": [ "file_read" ]
  }
}

# 关键：缓存保持温热，不用重发整个 tools 数组

可用范围包括 Claude Opus 5 与 Claude Fable 5。这个能力真正解锁的是自适应工具集——Agent 探索代码库时按发现动态换装备，而不是一开始就背着一个装满二十个工具的大包。

长时运行的 Agent 流水线最怕轮询：轮太密浪费配额，轮太稀感知滞后。这版扩展了 Webhook 支持，让外部系统能在状态变化时被动接收通知：

典型可订阅的变化：
  · 记忆存储发生变更
  · 运行环境状态更新
  · 会话进入/离开某个阶段

接入后你的系统可以做：
  记忆变更  → 触发下游工作流
  环境异常  → 立刻告警，不用等下一次轮询
  阶段完成  → 通知人工审核节点

创建 Agent 时可以在 model 对象里指定 effort，按任务难度调节推理深度。Opus 5 的档位一直延伸到 max：

{
  "model": {
    "name": "claude-opus-5",
    "effort": "low"        // 按任务类型分档，别一律 max
  }
}

最小可缓存长度从 1024 降到 512，看着是个小数字，但它改变了缓存策略的设计方式：

以前（1024 起）：
  短系统提示词根本进不了缓存，
  只能刻意「凑长度」，很别扭

现在（512 起）：
  精简的系统提示词也能缓存，
  高频短交互（分类、路由、校验）显著受益

配合工具热插拔的正确姿势：
  ① 稳定不变的内容放最前面（系统提示词、长期规则）
  ② 易变内容放后面（当前任务、临时工具）
  ③ 中途改工具时，前缀缓存依然命中

单独看每个特性都不惊艳，组合起来才是完整的生产形态：

一条代码库分析流水线：

  1. 会话种子创建 Agent
     initial_events 带上「分析这个仓库的技术债」
     effort = medium，起手只带 [file_read, grep]

  2. Agent 发现是个 monorepo，需要跑构建
     → 热插拔加入 [bash, test_runner]
     → 缓存未失效，延迟无抖动

  3. 分析进入深水区，需要权衡重构方案
     → 新建子会话，effort = high

  4. 记忆存储更新（写入分析结论）
     → Webhook 推给你的系统
     → 触发人工审核 + 生成工单

  5. 全程无轮询，无重启，缓存全程命中