把 Agent 迁到 Claude API 2026-10-21：采样参数移除、鉴权头切换与四类报错修复

先厘清一个机制：用 SDK 的话，你的请求用的是「该 SDK 大版本发布时对应的 API 版本」，也就是说版本不是你在代码里设的一个开关，而是被包版本决定的。老 SDK 一律发 2023-06-01，新出的那些大版本（Python 2.0.0、TypeScript 1.0.0、C# 13.0.0、Go 2.0.0、Java 3.0.0、PHP 1.0.0、Ruby 2.0.0，以及 ant CLI 2.0.0）一律发 2026-10-21。直接发 HTTP 的调用方则通过 anthropic-version 头选择版本。所以升级这件事，对 SDK 用户是「升包」，对裸 HTTP 用户是「改头」。

# 裸 HTTP：看你现在发的头
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"...","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

# SDK 用户：看你装的包版本
pip show anthropic          # Python
npm list @anthropic-ai/sdk  # TypeScript
go list -m all | grep anthropics   # Go（注意新模块路径以 /v2 结尾）

把范围摸清楚时，别只搜业务代码。至少还要覆盖四类地方：发给 Messages API 的调用、计数 token 的请求、用新版本创建的 Message Batches 里的单条请求，以及会把参数透传下去的提示词模板与配置文件。批量任务尤其容易被漏——它不在主链路上，报错也常常要等运行完才知道。

其中影响面最大的一类是采样参数：temperature、top_p、top_k 在新版本下对所有模型都移除，带任意一个就返回 400（invalid_request_error），与取值无关，传默认值也一样。必须把键本身从请求 JSON 里删掉，改值是没用的。第二类是消息结构：document 内容块直接放在 assistant 消息里会返回 400，要挪到 user 消息里；嵌套在其它块内部的 document（比如网页抓取工具返回的结果）仍然被接受。第三类是引用：user 消息里带非空 citations 数组的 text 块会返回 400，包括搜索结果里的这种块；assistant 回复里的引用仍然接受，给 document 和搜索结果开启引用也仍然可以。第四类是平台限制：Amazon Bedrock 上 2026-10-21 只对 Claude 4.7 及之后的模型可用，还在调 Opus 4.6 或更早模型的请求请保持现有 SDK 与版本，或者先换模型。

// 会 400：assistant 消息里直接放 document
{ role: "assistant", content: [{ type: "document", source: {...} }] }

// 正确：把 document 放进 user 消息
{ role: "user",      content: [{ type: "document", source: {...} }] }

// 会 400：user 的 text 块带非空 citations
{ role: "user", content: [{ type: "text", text: "...",
                            citations: [{ ... }] }] }

// 会 400：带任何一个采样参数（哪怕就是默认值）
{ "temperature": 1.0 }

还有两处读取侧的改动容易在升级后悄悄出错：Admin API 与企业分析 API 的响应不再返回被重命名字段的旧名（roles 变 role_ids、actor.email 变 actor.email_address），API Key 的响应里 workspace_id 被 scope 对象取代（限定工作区的密钥会给出真实 workspace ID，覆盖全部工作区的密钥带组织 scope 且没有 workspace_id）。如果你的后台在读这些字段，升级后会读到 undefined 而不是报错，属于最难发现的一类故障。

新 SDK 与 CLI 把 API Key 放在 Authorization: Bearer 头里发出去，而不是以前的 X-Api-Key。API 服务端两个头都认，所以直连的调用方无需改动。但如果你和 API 之间有一层代理、网关、审计中间件或者测试用的 mock，而这一层是读或写 X-Api-Key 的，升级之后它就找不到密钥了。两条路：让这一层改读 Authorization，或者在客户端显式配置继续发 X-Api-Key（官方迁移指南给了写法）。顺带一提，由于密钥与 auth token 现在走同一个头，一个客户端只能持有一份凭证：Python SDK 里同时给构造器传 API key 和 auth token 会抛 ValueError，而旧版是把两者放在不同头里发出去的。

# Python：需要时显式恢复 X-Api-Key 行为（写法见官方迁移指南）
# 更好的做法是让网关改读 Authorization: Bearer

# 网关侧最小改动示意
# 旧：key = request.headers["x-api-key"]
# 新：
auth = request.headers.get("authorization", "")
key  = auth.split(" ", 1)[1] if auth.lower().startswith("bearer ") else request.headers.get("x-api-key", "")

还有几处语言相关的坑值得提前标出来：Go SDK 的模块路径现在以 /v2 结尾，import 语句必须改，而用 go install 装的 CLI 如果还是旧路径会静默留在 v1；PHP 里单纯跑 composer update 跨不过大版本；CLI 去掉了 --api-key 与 --auth-token 这两个参数，因为密钥作为命令行参数会通过 shell 历史与进程列表泄露。TypeScript 与 Ruby 的 tool runner 不再做客户端压缩，改由 API 侧的压缩承担。

官方的建议是「一次发布里做完」：升 SDK、修破坏性改动、针对 2026-10-21 测一遍、然后一起上线。拆成多次发布会让中间态变成两套行为并存，排查成本陡增。改动清单可以照下面这份走：全局搜索并删除三个采样参数；把 assistant 消息里的 document 挪到 user；清掉 user text 块上的非空 citations；核对 Admin / 分析 API 的字段名与 API Key 的 scope；升级包并跑类型检查与单测；最后跑一次针对新版本的集成测试。

# 1) 找出所有采样参数（含批处理与模板）
rg -n "temperature|top_p|top_k" --glob '!*.lock' .

# 2) 升包（以官方发布说明的版本为准）
pip install "anthropic>=2.0.0"
npm install @anthropic-ai/sdk@latest
go get github.com/anthropics/anthropic-sdk-go/v2

# 3) 跑类型检查与测试
mypy .        # 或 pyright
tsc --noEmit
pytest

Python 侧还有一个细节：MessageParam 类型被拆成了 user、assistant、system 三个独立类型的联合。请求体的结构没变，所以把 messages 写成 dict 的代码不用改，但显式标注了 MessageParam 的代码可能要调整。另外，Python 的 TypeError 与 HTTP 400 是两层不同的故障：TypeError 发生在 SDK 层、还没发网络请求，说明方法参数列表里已经没有这个参数了；400 发生在 API 层，说明请求发出去了但被拒。排查时先分清是哪一层，能省掉一半时间。

对搭 Agent 的人来说，采样参数被拿走的影响比表面更大。很多 Agent 的稳定性做法是「temperature 设 0.2，让工具调用参数别乱飘」，这条路没了。可替代的手段有三类，按优先级排：一是改用结构化输出约束（schema、工具参数校验、JSON mode），把「靠概率稳定」换成「靠契约稳定」；二是把确定性部分从模型里挪出去——路由、校验、重试、状态机都写死，只把真正需要推理的那一小步留给模型，这恰好和薄编排器的思路一致；三是靠提示词把边界写死，明确列出允许的取值范围、不许编造的内容与必须拒绝的情形。这三类都比调 temperature 更费事，但也都比它更可靠。

# 稳输出的三层替代（示意）
# 1) 契约层：工具参数用 schema 约束，不合规就重试而不是放行
TOOL_SCHEMA = {
    "type": "object",
    "properties": {"order_id": {"type": "string", "pattern": "^[A-Z]{2}[0-9]{6}$"}},
    "required": ["order_id"],
    "additionalProperties": False,
}

# 2) 确定性层：能写代码判断的别交给模型
if not re.match(r"^[A-Z]{2}[0-9]{6}$", order_id):
    return ask_user_for_correction(order_id)

# 3) 提示词层：边界写死，不要靠语感
# 「只输出下列枚举之一；缺字段时回问用户，绝不猜测。」

迁移的正确验收方式也只有一种：拿你真实的 Agent 任务集跑一遍回归，比较升级前后的关键指标——工具调用参数合规率、任务完成率、平均步数、以及每条任务的 token 成本。尤其要看「以前靠低 temperature 压住的那些抖动」是不是冒出来了。如果冒出来了，先补结构化约束与确定性校验，而不是急着回退版本。回退本身也有成本：留在旧 SDK 就意味着留在旧的版本分支上，而 Anthropic 的 SDK 改动只会落在新大版本里。

上线策略建议是：先在一个非关键入口灰度（比如内部工具或离线批处理），观察 24 到 48 小时的错误率、400 占比与输出质量指标，再全量。回滚预案要提前写好两套——一套是「回滚代码但保留新 SDK」，适用于发现输出质量下降但还想留在新版 SDK 上的情况；另一套是「整体回退到旧 SDK 与旧版本」，适用于出现无法快速修复的功能性故障。第二套要求你的依赖管理能干净地降回去，所以升级前请确认包版本锁定文件是完整的。

# 上线检查表（逐条打勾再放量）
[ ] 全库已无 temperature / top_p / top_k（含批处理与模板）
[ ] assistant 消息里不再直接放 document
[ ] user text 块不再带非空 citations
[ ] 代理/网关已能读 Authorization: Bearer
[ ] Admin / 分析 API 的字段重命名已同步
[ ] API Key 的 workspace_id → scope 已同步
[ ] Bedrock 老模型仍留在旧版本
[ ] 类型检查与单测通过
[ ] 针对 2026-10-21 的集成测试通过
[ ] Agent 任务集回归：合规率 / 完成率 / 步数 / 成本 无显著劣化
[ ] 回滚预案已写好并演练过一次

最后两件事容易被忘。一是许可证：新 SDK 与 CLI 从 MIT 换成 Apache 2.0，官方未说明原因；如果你的合规流程对许可证敏感，升级前走一遍确认。二是同一天发布的 Claude Code 2.1.307 增加了 /claude-api api-version 命令，用来把 Claude API 相关代码迁到新版本——但它的发布说明并未写明该命令具体改了什么，所以请把它当作起点而不是自动迁移工具，改完仍然要自己过一遍 diff。把这次升级当成一次正常的、有验收条件的依赖升级来做，它就不神秘了。