Claude API

claude-api
分类编程
作者Anthropic
许可Complete terms in LICENSE.txt
评分4.50/5
使用2.1K

使用 Claude 构建 LLM 驱动的应用

本技能旨在帮助您使用 Claude 构建 LLM 驱动的应用。请根据需求选择合适的界面，检测项目语言，然后阅读相关的语言特定文档。

开始之前

扫描目标文件（如果没有目标文件，则扫描提示词和项目）以查找非 Anthropic 供应商的标记 —— 例如 import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5，或像 agent-openai.py 或 *-generic.py 这样的文件名，以及任何要求保持代码供应商中立的明确指令。如果发现任何此类标记，请停止并告知用户本技能生成的是 Claude/Anthropic SDK 代码；询问他们是想将文件切换到 Claude，还是需要一个非 Claude 的实现。不要在非 Anthropic 文件中使用 Anthropic SDK 调用进行编辑。

输出要求

当用户要求您添加、修改或实现 Claude 功能时，您的代码必须通过以下方式之一调用 Claude：

1. 项目语言的官方 Anthropic SDK（如 anthropic、@anthropic-ai/sdk、com.anthropic.* 等）。只要项目语言有支持的 SDK，这就是默认选择。
2. 原生 HTTP（如 curl、requests、fetch、httpx 等）—— 仅在用户明确要求使用 cURL/REST/原生 HTTP、项目为 shell/cURL 项目，或该语言没有官方 SDK 时使用。

切勿混用两者 —— 不要因为觉得更轻量就在 Python 或 TypeScript 项目中使用 requests/fetch。切勿回退到 OpenAI 兼容的适配层（shims）。

绝不要猜测 SDK 的用法。 函数名、类名、命名空间、方法签名和导入路径必须来自明确的文档 —— 无论是本技能中的 {lang}/ 文件，还是 shared/live-sources.md 中列出的官方 SDK 仓库或文档链接。如果您需要的绑定在技能文件中没有明确记录，请在编写代码前通过 WebFetch 访问 shared/live-sources.md 中的相关 SDK 仓库。不要根据 cURL 形式或其他语言的 SDK 来推断 Ruby/Java/Go/PHP/C# 的 API。

如果 WebFetch 或仓库访问失败（网络受限、超时、克隆被拦截）：不要持续重试 —— 请根据 {lang}/ 文件中的模式和命名空间/包表编写代码，运行编译器或解释器，并根据错误输出进行迭代。对于静态类型 SDK（C#、Java、Go），针对本地错误进行“编译-修复”循环比在网络受阻的情况下进行研究能更快地获得可运行的代码。

默认设置

除非用户另有要求，否则请遵循以下设置：

关于 Claude 模型版本，请使用 Claude Opus 5，可通过模型字符串 claude-opus-5 访问。对于任何稍微复杂的任务，请默认使用自适应思考（thinking: {type: "adaptive"}）。最后，对于任何可能涉及长输入、长输出或高 max_tokens 的请求，请默认使用流式传输（streaming）—— 这可以防止请求超时。如果您不需要处理单个流事件，请使用 SDK 的 .get_final_message() / .finalMessage() 辅助方法来获取完整响应。

⚠️ API 漂移 —— 您的训练数据可能已过时

几个常见的 Claude API 形式在 2025-2026 年发生了变化。如果您记得训练中的某种模式，在编写之前请对照本技能中的 {lang}/ 文件进行验证 —— 以下是最高频的漂移点：

| 领域 | 过时模式 | 当前 API |
|---|---|---|
| 扩展思考 (Extended thinking) | thinking: {type: "enabled", budget_tokens: N} | 在 Claude 4.6+ 模型中：thinking: {type: "adaptive"}。budget_tokens 在 Opus 4 中已弃用。 |
| 6 / Sonnet 4.6 以及在 Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7 上被 400 错误拒绝。4.6 之前的模型仍使用 budget_tokens。 |
| Web 搜索 / Web 获取工具类型 | web_search_20250305, web_fetch_20250910 | 在 Opus 5/4.8/4.7/4.6, Sonnet 5 和 Sonnet 4.6 上使用 web_search_20260209, web_fetch_20260209（动态过滤）。旧模型保留基础版本；在 Vertex AI 上仅可用基础版 web_search_20250305（Vertex 不支持 web fetch）—— 详见下方的 Server Tools QR。 |
| PHP 参数名称 | 使用 snake_case 形式的 wire names 作为命名参数 (max_tokens) | 顶层命名参数使用 camelCase (maxTokens)。嵌套数组键根据功能而异（例如 'taskBudget', 'skillID', 'mcp_server_name'）—— 请直接复制文档示例中的准确键名，不要进行批量转换。 |
| Managed Agents 凭据 | 通过自定义工具在主机端保留密钥（在 Vaults 发布前的唯一选择） | Vault environment_variable 凭据 —— 由 Anthropic 存储，在出口处替换，在沙箱中不可见 (shared/managed-agents-tools.md → Vaults)。对于自托管沙箱，主机端自定义工具仍作为备选方案。 |

本技能中的 {lang}/ 文件优先级高于召回的模式。

---

子命令 (Subcommands)

如果本提示词底部的用户请求是一个纯子命令字符串（无正文），请搜索本文档中所有的子命令表格（包括下方附加章节中的表格），并直接执行对应的“操作”列。这允许用户通过 /claude-api <subcommand> 调用特定流程。如果文档中没有匹配的表格，则将请求视为普通正文。

| 子命令 | 操作 |
|---|---|
| migrate | 将现有的 Claude API 代码迁移到更新的模型。立即阅读 shared/model-migration.md 并按顺序执行：步骤 0（确认范围 —— 在任何编辑前询问涉及哪些文件/目录），步骤 1（对每个文件进行分类），然后执行针对目标模型的破坏性变更部分。不要总结指南 —— 直接执行。如果用户未指定目标模型，请在询问范围的同时询问迁移目标。在应用针对目标模型的变更后，根据 shared/prompt-audit.md 审计范围内的提示词文本、工具描述和请求代码 —— 为源模型编写的提示词是每次迁移的一部分，且不会自动显现。 |
| prompt-audit | 审计现有的提示词、技能和工具描述中是否存在为旧模型编写的过时模式（"cruft"）。立即阅读 shared/prompt-audit.md 并按顺序执行：步骤 0（从请求和仓库中确定范围和目标模型 —— 在报告中陈述假设，不要停下来询问），清单盘点，来源分析，然后进行模式扫描。完整提供两项交付物 —— 审计报告（包含 文件:行号、模式、为何对目标模型已过时、置信度）和建议的 diff —— 无需暂停确认；仅在请求明确要求时才应用编辑。不要总结指南 —— 直接执行。 |

---

语言检测

首先判断请求是否涉及特定的 SDK 语言。某些任务不涉及：审计提示词文本 (prompt-audit)、选择模型、价格与限制问题以及 API 概念问题均与语言无关。对于这些任务，跳过本节且无需询问用户语言。

当任务涉及阅读或编写 SDK 代码时，在阅读代码示例前请确定用户使用的语言：

1. 查看项目文件以推断 t
语言判定：

- *.py, requirements.txt, pyproject.toml, setup.py, Pipfile → Python — 从 python/ 读取
- *.ts, *.tsx, package.json, tsconfig.json → TypeScript — 从 typescript/ 读取
- *.js, *.jsx（且不存在 .ts 文件） → TypeScript — JS 使用相同的 SDK，从 typescript/ 读取
- *.java, pom.xml, build.gradle → Java — 从 java/ 读取
- *.kt, *.kts, build.gradle.kts → Java — Kotlin 使用 Java SDK，从 java/ 读取
- *.scala, build.sbt → Java — Scala 使用 Java SDK，从 java/ 读取
- *.go, go.mod → Go — 从 go/ 读取
- *.rb, Gemfile → Ruby — 从 ruby/ 读取
- *.cs, *.csproj → C# — 从 csharp/ 读取
- *.php, composer.json → PHP — 从 php/ 读取

2. 如果检测到多种语言（例如同时存在 Python 和 TypeScript 文件）：

- 检查用户的当前文件或问题涉及哪种语言
- 如果仍然不明确，请询问：“我检测到了 Python 和 TypeScript 文件。您在 Claude API 集成中使用的是哪种语言？”

3. 如果无法推断语言（空项目、无源文件或不支持的语言）：

- 使用 AskUserQuestion 并提供选项：Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
- 如果 AskUserQuestion 不可用，则默认提供 Python 示例并注明：“正在显示 Python 示例。如果您需要其他语言，请告诉我。”

4. 如果检测到不支持的语言（Rust, Swift, C++, Elixir 等）：

- 建议使用 curl/ 中的 cURL/raw HTTP 示例，并注明可能存在社区 SDK
- 提供 Python 或 TypeScript 示例作为参考实现

5. 如果用户需要 cURL/raw HTTP 示例，请从 curl/ 读取。

特定语言的功能支持

上述所有 SDK 语言均支持 beta 版 Tool Runner 和 Managed Agents (beta) —— Python (@beta_tool 装饰器), TypeScript (betaZodTool + Zod), Java (注解类), Go (toolrunner 包中的 BetaToolRunner), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + 原始 JSON schema), PHP (BetaRunnableTool + toolRunner())；代码入口点请参阅下方的 Tool Use Patterns 快速参考。cURL 为原始 HTTP（无 SDK 功能）并支持 Managed Agents。

> Managed Agents 代码示例：请参阅下方 ## Managed Agents (Beta) 章节中的阅读指南。

---

我应该使用哪个界面？

> 从简单开始。 默认选择能满足需求的最低层级。单次 API 调用和工作流可以处理大多数用例 —— 只有在任务确实需要开放式、模型驱动的探索时，才使用 Agent。“最简单”意味着您需要维护的代码最少：对于托管的、定时触发的或具有内存支持的 Agent，Managed Agents 通常是最简单的选择（无需循环代码、状态文件或调度器），尽管它是一个更大的平台。

| 用例 | 层级 | 推荐界面 | 原因 |
| ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ |
| 分类、摘要、提取、问答 | 单次 LLM 调用 | Claude API | 一次请求，一次响应 |
| 批量处理或向量化 (Embeddings) | 单次 LLM 调用 | Claude API | 专用端点 |
| M
| 具有代码控制逻辑的多步流水线 | 工作流 (Workflow) | Claude API + 工具调用 | 由你编排循环 |
| 自定义工具的自定义智能体 | 智能体 (Agent) | Claude API + 工具调用 | 最大灵活性 |
| 带有工作区的服务器管理状态智能体 | 智能体 (Agent) | 托管智能体 (Managed Agents) | Anthropic 运行循环并托管工具执行沙箱 |
| 持久化、版本化的智能体配置 | 智能体 (Agent) | 托管智能体 (Managed Agents) | 智能体为存储对象；会话绑定至特定版本 |
| 支持文件挂载的长运行多轮对话智能体 | 智能体 (Agent) | 托管智能体 (Managed Agents) | 每个会话独立容器，SSE 事件流，Skills + MCP |
| 按计划运行的智能体（cron，“每晚”） | 智能体 (Agent) | 托管智能体 (Managed Agents) — 定时部署 | 部署自动触发会话；无需客户端调度器 |

> 注意： 当你希望 Anthropic 运行智能体循环 *且* 托管工具执行容器时，托管智能体 (Managed Agents) 是正确选择 —— 文件操作、bash、代码执行均在每个会话的工作区中运行。如果你想自行托管计算资源或运行自定义工具运行时，Claude API + 工具调用是正确选择 —— 使用 Tool Runner 来实现智能体循环 —— 其每轮钩子 (per-turn hooks) 仍为你提供审批门禁、日志记录、错误拦截和条件执行（参见 shared/tool-use-concepts.md） —— 或者在你想完全掌控整个循环时使用手动循环。

> 云供应商访问。 AWS 上的 Claude Platform 由 Anthropic 运营，API 功能同步更新 —— 客户端设置请参见 shared/claude-platform-on-aws.md。关于 AWS 上的 Claude Platform、Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 各项功能的可用性，请参见 shared/platform-availability.md —— 该表格是本技能的唯一事实来源；请勿从其他地方推断可用性。

构建智能体：四种方法

一旦你确定确实需要一个智能体（开放式、模型驱动的工具调用），有四种不同的构建方式。两种独立的问题将它们区分开来：谁提供框架 (harness)（智能体循环 + 上下文管理）以及 谁提供部署（智能体运行的基础设施）。Tool Runner 和 Claude Agent SDK 都仅提供 *框架* —— 你仍需自行托管和部署 —— 这就是为什么它们容易被混淆。托管智能体 (CMA) 是唯一同时提供 框架 *和* 托管部署 的选项；而手动循环两者都不提供。

| # | 方法 | 你编写的内容 | 框架与部署 | 可用工具 | 适用场景 |
|---|----------|-----------|----------------------|-----------------|----------|
| 1 | Claude API — 手动循环 | 自行编写 while stop_reason == "tool_use" 循环 | 你构建框架；你托管 | 仅限你定义的工具 | 你想掌控 *整个* 循环 —— 无需依赖 Beta 功能，或 Tool Runner 的每轮钩子无法满足你的控制流 |
| 2 | Claude API — Tool Runner (client.beta.messages.tool_runner + @beta_tool / betaZodTool) | 仅编写工具函数 | SDK 提供循环 (仅框架)；你托管 | 仅限你定义的工具 | 不需要手写循环的自定义工具智能体（大多数情况）。每轮钩子仍提供审批门禁、错误拦截、结果修改（如 cache_control）、重试、流式传输和压缩 |
| 3 | 托管智能体 (Managed Agents) | ... | ... | ... | ... |
| Managed Agents (CMA) (REST, beta) | Agent 配置 + 你的工具执行结果 | Anthropic 提供运行环境 且 为每个会话托管沙箱 (运行环境 + 部署) | Anthropic 托管的沙箱 (bash, 文件, 代码执行) + Skills/MCP + 你的工具 | 你希望 Anthropic 运行循环 并 托管每个会话的工作区；需要持久化/版本化配置；长会话 |
| 4 | Claude Agent SDK — *独立产品* (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | 提示词 + 选项 | SDK 提供 Claude Code 运行环境 + 内置工具 (仅运行环境)；由你托管 | 内置 Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch + MCP + 子代理 | 你希望在自己的基础设施上运行一个功能完备的编码/文件系统代理 |

“运行环境 (harness)”与“部署 (deployment)”的区分是核心逻辑模型：选项 1、2 和 4 都 由你负责部署；只有选项 3 (CMA) 增加了托管部署。选项 1-3 是本技能生成的内容；选项 4 是一个拥有独立文档的不同库 —— 详见下文的区分说明。

> Tool Runner ≠ Claude Agent SDK。 这两者名称相似但属于不同的包：
> - Tool Runner 是常规 Anthropic API SDK (anthropic / @anthropic-ai/sdk) 的一部分，通过 client.beta.messages.tool_runner 调用。它为 *你定义的工具* 自动化“请求 $\rightarrow$ 执行 $\rightarrow$ 循环”周期。它没有内置工具，没有文件系统访问权限，也没有沙箱 —— 你需要提供所有工具并托管计算资源。它对应上述选项 2，是 POST /v1/messages 之上的一个轻量级辅助工具。
> - Claude Agent SDK (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) 是将 Claude Code 封装成的库。它自带内置工具（文件读/写/编辑、bash、grep、网页搜索）、完整的代理循环、上下文管理、钩子 (hooks)、子代理、权限管理和会话管理。你只需调用 query(prompt, options)，它会驱动所有流程。
>
> 两者都 仅提供运行环境 —— 由你负责托管和部署。 区别在于运行环境的范围：Tool Runner 循环执行 *你* 定义的工具（支持每轮的审批、拦截、结果修改和重试钩子，但无内置工具）；Agent SDK 是包含内置工具的完整 Claude Code 运行环境。两者都不提供托管部署 —— 这正是 托管代理 (CMA) 增加的功能（Anthropic 托管循环和每个会话的沙箱）。
>
> 本技能涵盖 Claude API 和托管代理 (选项 1-3)；它不生成 Claude Agent SDK 代码。 如果用户确实需要 Claude Agent SDK，请引导其查阅相关文档 (code.claude.com/docs/en/agent-sdk) —— 不要将 API Tool Runner 与之混淆。

我应该构建代理吗？

在选择代理层级之前，请检查以下四个标准：

  • 复杂度 (Complexity) — 任务是否包含多个步骤且难以预先完全定义？（例如：“将此设计文档转化为 PR” vs “从该 PDF 中提取标题”）
  • 价值 (Value) — 结果是否足以支撑更高的成本和延迟？
  • 可行性 (Viability) — Claude 是否能够胜任此类任务？
  • 错误成本 (Cost of error) — 错误是否可以被捕获并恢复？（通过测试、审核、回滚）

如果其中任何一项的答案为“否”，请保持在更简单的层级（单次调用或工作流）。

---

架构

所有请求都通过 POST /v1/messages 完成。工具和输出约束是该单一端点的功能，而非独立的 API。

用户定义工具 — 你定义工具（通过装饰器、Zod 模式或原始 JSON），SDK 的 tool runner 负责调用 API、执行你的函数，并循环直到 Claude 完成任务。为了获得完全控制权，你也可以手动编写循环。
服务端工具 — 由 Anthropic 托管并在其基础设施上运行的工具。代码执行完全在服务端完成（在 tools 中声明后，Claude 会自动运行代码）。计算机使用（Computer use）可选择服务端托管或自托管。

结构化输出 — 约束 Messages API 的响应格式 (output_config.format) 和/或工具参数验证 (strict: true)。推荐使用 client.messages.parse()，它会自动根据你的 schema 验证响应。注意：旧的 output_format 参数已弃用；请在 messages.create() 中使用 output_config: {format: {...}}。

辅助端点 — 批处理 (POST /v1/messages/batches)、文件 (POST /v1/files)、Token 计数 (POST /v1/messages/count_tokens — 详见 shared/token-counting.md) 和模型 (GET /v1/models, GET /v1/models/{id} — 用于实时查询能力/上下文窗口) 均可为 Messages API 请求提供支持或输入。

---

当前模型 (缓存日期: 2026-06-24)

| 模型 | 模型 ID | 上下文 | 输入 $/1M | 输出 $/1M |
| ----------------- | ------------------- | -------------- | ---------- | ----------- |
| Claude Fable 5 | claude-fable-5 | 1M | $10.00 | $50.00 |
| Claude Mythos 5 (仅限 Project Glasswing) | claude-mythos-5 | 1M | $10.00 | $50.00 |
| Claude Opus 5 | claude-opus-5 | 1M | $5.00 | $25.00 |
| Claude Opus 4.8 | claude-opus-4-8 | 1M | $5.00 | $25.00 |
| Claude Opus 4.7 | claude-opus-4-7 | 1M | $5.00 | $25.00 |
| Claude Opus 4.6 | claude-opus-4-6 | 1M | $5.00 | $25.00 |
| Claude Sonnet 5 | claude-sonnet-5 | 1M | $3.00 (2026-08-31 前促销价 $2.00) | $15.00 (促销价 $10.00) |
| Claude Sonnet 4.6 | claude-sonnet-4-6 | 1M | $3.00 | $15.00 |
| Claude Haiku 4.5 | claude-haiku-4-5 | 200K | $1.00 | $5.00 |

合作伙伴定价： 以上价格为 Anthropic 第一方 API 费率 —— 同样适用于 Microsoft Foundry 上的 Claude（通过 Microsoft Marketplace 按标准 API 费率计费）。Amazon Bedrock 和 Vertex AI 上的 Claude 由合作伙伴运营，定价独立 —— 请参阅 Bedrock 或 Vertex AI。关于 WebFetch，请参考 shared/live-sources.md 中的 Pricing 行。

除非用户明确指定其他模型，否则请始终使用 claude-opus-5。 这是强制性的。除非用户明确说“使用 sonnet”或“使用 haiku”，否则不要使用 claude-sonnet-5、claude-sonnet-4-6 或任何其他模型。绝不要为了节省成本而降低模型版本 —— 这应该是用户的决定，而非你的。仅在用户明确要求 Claude Fable 5、“fable”或 Anthropic 最强大的模型时才使用 claude-fable-5 —— 它的 API 行为与 Opus 系列不同（见下文），且价格高于 Opus 级别。仅使用表格中准确的模型 ID 字符串 —— 它们已经是完整的；绝不要附加日期后缀（例如使用 claude-sonnet-4-6，绝不要使用 claude-sonnet-4-6-20251114 或你从训练数据中记得的任何日期后缀变体）。如果用户请求表格中没有的旧模型（例如 "opus 4.5", "sonnet 3.7"），请查阅 shared/models.md 获取准确 ID —— 不要自行构建。

Claude Fable 5 (claude-fable-5) — 能力最强的广泛发布模型

Claude Fable 5 是 Anthropi
这是目前功能最强且已广泛发布的模型，适用于最苛刻的推理和长周期智能体（agentic）工作；以下所有内容同样适用于 Claude Mythos 5 (claude-mythos-5, Project Glasswing —— 具备相同的能力、定价和 API 接口；是仅限邀请制的 claude-mythos-preview 的继任者)。支持 1M 上下文窗口（最大值即为默认值），最大输出 128K。与 Opus 级别 API 的关键区别请参阅 shared/model-migration.md → Migrating to Claude Fable 5：

  • 思考（Thinking）始终开启 —— 请完全省略 thinking 参数（或发送 {type: "adaptive"}）。任何其他显式配置都将被拒绝：{type: "disabled"} 和 {type: "enabled", budget_tokens: N} 均会返回 400 错误。请使用 output_config.effort 控制深度（支持 low 到 xhigh 以及 max）。
  • 永不返回原始思维链 —— 响应包含常规的 thinking 块（而非 redacted_thinking）：display: "summarized" 返回可读摘要，"omitted"（默认值）将 thinking 字段留空。回传规则：在同一模型上原样传回思考块；其他模型会静默丢弃（不计费，无需手动剔除）；详见 shared/model-migration.md。
  • 分词器（Tokenizer） —— 与 Opus 4.8 相同（随 Opus 4.7 引入）。从 Opus 4.7/4.8 迁移时，Token 计数大致不变，但单 Token 定价不同。若从 Opus 4.6、Sonnet、Haiku 或更旧版本迁移，请使用 count_tokens 重新基准测试（Opus 4.7 分词器的 Token 数量约为之前的 1×–1.35×）。
  • refusal 停止原因 —— 请妥善处理并默认启用回退（fallbacks） —— 安全分类器可能会拒绝请求（HTTP 200，stop_reason: "refusal"，并带有 stop_details 分类）；在读取 content 之前请务必检查 stop_reason。在编写 claude-fable-5 或 claude-opus-5 代码时，请默认包含服务端 fallbacks 参数。 最简形式为：betas: ["server-side-fallback-2026-07-01"] + fallbacks: "default"，该模式根据拒绝类别进行路由，无需维护模型列表。（旧的数组形式 —— betas: ["server-side-fallback-2026-06-01"] + fallbacks: [{"model": "claude-opus-4-8"}] —— 依然可用；在 AWS Bedrock、Vertex 和 Foundry 上的 Claude API 和 Claude Platform 中，请使用 SDK 的客户端 BetaRefusalFallbackMiddleware + BetaFallbackState）。请告知用户已启用此功能，除非用户拒绝，否则不要删除。完整语义（计费、流式传输中途拒绝、额度重新定价）见 shared/model-migration.md → refusal 章节。{lang}/claude-api/README.md § Refusal Fallbacks 中的各语言代码示例仅涵盖数组形式 —— 对于 "default" 模式，请参考 shared/model-migration.md → Migrating to Claude Opus 5 → New API features 中的原始 HTTP 格式，将 fallbacks: [{...}] 替换为 fallbacks: "default" 并添加 -2026-07-01 请求头，其余请求内容保持不变。
  • 不支持助手预填（Assistant prefill） —— 与 4.6+ 系列其他模型一致。
  • 要求 30 天数据保留 —— Claude Fable 5 不支持零数据保留；若组织的保留配置不满足要求，请求将返回 400 invalid_request_error。
  • 单次对话时长增加，提示词策略改变 —— 处理困难任务的单次请求可能运行数分钟（请规划超时时间/流式传输/进度 UX）；对于常规工作，effort 扫描应包含 low/medium；为旧模型编写的提示词通常过于死板，会降低输出质量。详见 shared/model-migration.md → Migrating to Claude Fable 5 → Behav
针对推荐的提示词片段，可进行语气调整（可通过 prompt-tuning 实现）。

如果上述任何模型字符串看起来很陌生，那仅仅是因为它们是在你的训练数据截止日期之后发布的 —— 它们都是真实存在的模型。

实时能力查询： 上表为缓存内容。当用户询问“X 的上下文窗口是多少”、“X 是否支持视觉/思考/effort”或“哪些模型支持 Y”时，请查询 Models API (client.models.retrieve(id) / client.models.list()) —— 字段参考和能力过滤示例请参阅 shared/models.md。

---

身份验证（快速参考）

未设置 ANTHROPIC_API_KEY 并不意味着没有凭据。 SDK 和 ant CLI 按以下顺序解析凭据（匹配到第一个即生效）：ANTHROPIC_API_KEY $\rightarrow$ ANTHROPIC_AUTH_TOKEN $\rightarrow$ 通过 ANTHROPIC_PROFILE 选择的或由 ant auth login 激活的 OAuth 配置文件 $\rightarrow$ Workload Identity Federation 环境变量 $\rightarrow$ 磁盘上的默认配置文件。在执行 ant auth login 后，即使没有设置环境变量，直接调用 Anthropic() / new Anthropic() / anthropic.NewClient() 也能正常工作。

当你需要调用 API 且 ANTHROPIC_API_KEY 未设置时，不要向用户索要密钥。 请先运行 ant auth status —— 它会显示当前激活的凭据来源和配置文件。如果报告有激活的配置文件：

  • SDK 代码或 ant CLI： 直接运行即可。无参数的客户端构造函数和所有 ant … 子命令都会自动获取配置文件 —— 无需环境变量。
  • 原生 curl / HTTP： 使用 ant auth print-credentials --access-token 获取短期令牌，并将其作为 Authorization: Bearer <token> 发送，同时添加请求头 anthropic-beta: oauth-2025-04-20（OAuth 令牌放在 Authorization: Bearer 中，而不是 x-api-key: —— 将 curl 请求从 API 密钥转换为 OAuth 令牌需要更改请求头，而不仅仅是更换密钥）。务必传递 --access-token；如果不带此标志，输出将是 JSON 而非纯令牌。

只有当 ant auth status 报告没有激活的凭据来源（或未安装 ant）时，才向用户索要密钥。建议首选 ant auth login —— 它会将配置文件存储在 ~/.config/anthropic/ 下，SDK 可自动读取 —— 备选方案是导出 ANTHROPIC_API_KEY。

完整的验证详情（命名配置文件、作用域、API 密钥覆盖配置文件的陷阱、刷新令牌过期）：shared/anthropic-cli.md。

---

思考与 Effort（快速参考）

在所有当前模型上均可使用自适应思考 (thinking: {type: "adaptive"}) —— Claude 会动态决定何时思考以及思考多少。各模型规则如下：

| 模型 | 思考配置 | 省略 thinking | budget_tokens | 采样 (temperature/top_p/top_k) | Effort 等级 |
|---|---|---|---|---|---|
| Fable 5 | {type: "adaptive"} 或省略；显式设置 {type: "disabled"} 会返回 400 —— 请直接省略该参数 | 运行自适应模式（思考始终开启） | 已移除 —— {type: "enabled", budget_tokens: N} 返回 400 | 已移除 —— 400 | low/medium/high/xhigh/max |
| Claude Opus 5 | {type: "adaptive"} 或省略；{type: "disabled"} 仅在 effort 为 high 或更低时被接受 —— 在 xhigh/max 时返回 400，详见下文的禁用思考陷阱 | 运行自适应模式（默认开启思考 —— 与 Opus 4.8/4.7 不同） | 已移除 —— 400 | 已移除 —— 400 | low–max (全部五个等级) |
| Opus 4.8 / 4.7 | {type: "adaptive"} 是唯一的开启模式；接受 {type: "disabled"} | 不运行思考 —— 需显式设置 {type: "adaptive"} | 已移除 —— 400 | 已移除 —— 400 | low/medium/high/xhigh/max |
| Sonnet 5 | {type: "adaptive"} 是唯一的开启模式；{type: " | | | | |
| disabled"} 已接受 | 运行自适应 | 已移除 — 400 | 已移除 — 400 | low/medium/high/xhigh/max |
| Opus 4.6 / Sonnet 4.6 | {type: "adaptive"} (推荐；自动启用交错思考，无需 beta 请求头) | 显式设置 {type: "adaptive"} | 已弃用 — 请勿在新代码中使用；仅作为过渡方案 (见下文) | 允许 | low/medium/high/max (xhigh 随 Opus 4.7 引入) |
| 旧版本 (Sonnet 4.5, Haiku 4.5, …) — 仅在明确要求时使用 | {type: "enabled", budget_tokens: N} | 无思考 | 启用思考必填；必须小于 max_tokens 且最小为 1024，否则会报错 | 允许 | effort 仅在 Opus 4.5 上有效 (low/medium/high — 无 xhigh/max)；在 Sonnet 4.5 / Haiku 4.5 上会报错 |

Opus 4.8 保持与 4.7 相同的请求接口（无新的破坏性变更）— 请参阅 shared/model-migration.md 中的 $\rightarrow$ Migrating to Opus 4.8 以了解行为微调，以及 $\rightarrow$ Migrating to Opus 4.7 以查看从 4.6 或更早版本迁移时的完整破坏性变更列表。在禁用 thinking 的情况下，Opus 4.8 可能会在可见响应中写入更长的推理过程 — 请保持自适应思考开启，或添加“仅输出最终答案”的指令（见迁移指南）。

  • Effort (GA 正式版，无需 beta 请求头)： output_config: {effort: "low"|"medium"|"high"|"xhigh"|"max"} — 位于 output_config 内部而非顶层；默认值为 high（等同于省略）。控制思考深度和整体 Token 消耗；建议与自适应思考结合使用，以获得最佳的成本-质量权衡。xhigh（在 Opus 4.7 中引入，介于 high 和 max 之间）是 Fable 5 / Opus 4.7/4.8 / Sonnet 5 在大多数编程和 Agent 场景下的最佳设置，也是 Claude Code 的默认值；在这些模型上，effort 的影响比同级别之前的任何模型都大 — 迁移时请重新调优，并在运行长周期/Agent 任务时使用 high/xhigh 并一次性提供完整的任务规格。对于对智能敏感的工作，请至少使用 high；当正确性高于成本时使用 max；对于子 Agent 或简单任务使用 low — 较低的 effort 意味着更少且更整合的工具调用、更少的开场白以及更简洁的确认（high 通常是平衡质量和 Token 效率的黄金点）。
  • 思考显示 — 在 Fable 5 / Mythos 5 / Opus 5 / 4.8 / 4.7 / Sonnet 5 上默认 "omitted"： display: "summarized" 返回推理的可读摘要；"omitted"（上述六个模型的默认值 — 相比 Opus 4.6 和 Sonnet 4.6 的 "summarized" 这是一个静默变更）会流式传输内容为空的 thinking 块。display 仅控制可见性 — 无论设置如何，思考过程都会发生且计费相同；原始思维链在任何模型上都不会被完全暴露。如果你向用户流式传输推理过程，默认设置看起来像是在输出前有很长的停顿 — 请显式设置 thinking: {type: "adaptive", display: "summarized"}。（与显示无关，在同一模型上继续对话时，请原样回传思考块；其他模型会静默忽略它们 — 见迁移指南。）
  • 当用户要求“扩展思考 (extended thinking)”、“思考预算 (thinking budget)”或 budget_tokens 时： 始终使用 Fable 5, Opus 5, 4.8, 4.7 或 4.6 并配置 thinking: {type: "adaptive"} — 固定思考 Token 预算的概念已弃用，由自适应思考取代。在新的 4.6/4.7/4.8 代码中不要使用 budget_tokens，也不要仅仅因为用户提到该词就切换到旧模型。*渐进迁移特例：* budget_tokens 目前仅在 Opus 4.6 和 Sonnet 4.6 上可用，作为过渡方案。
如果你在调整 effort 之前，现有代码需要硬性的 token 上限，请参阅 shared/model-migration.md → Transitional escape hatch（过渡期逃生口）。该机制在 Fable 5、Opus 5/4.7/4.8 和 Sonnet 5 中已完全移除。

---

压缩 (快速参考)

适用版本：Beta, Fable 5, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, 以及 Sonnet 4.6。 对于可能超过 1M 上下文窗口的长对话，请启用服务端压缩。当接近触发阈值（默认 150K tokens）时，API 会自动总结之前的上下文。需要 beta 请求头 compact-2026-01-12。

至关重要： 每一轮对话都必须将 response.content（而不仅仅是文本）追加回你的消息列表中。响应中的压缩块（compaction blocks）必须予以保留 —— API 在下次请求时利用这些块来替换被压缩的历史记录。如果仅提取文本字符串并追加，将导致压缩状态在无感知的情况下丢失。

代码示例请参阅 {lang}/claude-api/README.md（Compaction 章节）。完整文档可通过 WebFetch 在 shared/live-sources.md 中查看。

---

提示词缓存 (快速参考)

前缀匹配。 前缀中任何位置的字节变化都会使之后的所有内容失效。渲染顺序为 tools → system → messages。请将稳定内容放在前面（固定的系统提示词、确定性的工具列表），将易变内容（时间戳、单次请求 ID、变化的提问）放在最后一个 cache_control 断点之后。

对话中途的操作员指令（适用于 Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5；不适用于 Claude Sonnet 5；无需 beta 请求头）：请将 {"role": "system", ...} 追加到 messages[] 中，而不是修改顶层的 system。这样可以保留已缓存的历史前缀，且是安全的、防提示词注入的操作员通道。详见 shared/prompt-caching.md § Mid-conversation system messages。

顶层自动缓存（在 messages.create() 中设置 cache_control: {type: "ephemeral"}）是在不需要精细控制位置时的最简选项。每次请求最多 4 个断点。可缓存的前缀最小长度约为 1024 tokens —— 短于此长度的前缀将静默失效（不缓存）。

通过 usage.cache_read_input_tokens 验证 —— 如果在重复请求中该值为零，说明存在静默失效因素（如系统提示词中的 datetime.now()、未排序的 JSON 或变化的工具集）。

关于布局模式、架构指南和静默失效审计清单，请阅读 shared/prompt-caching.md。特定语言的语法请参阅 {lang}/claude-api/README.md（Prompt Caching 章节）。

---

快速模式 (快速参考)

研究预览版，仅限 Claude Opus 5 / Opus 4.8 —— 仅支持 Claude API 和 Managed Agents，不支持 Bedrock / Google Cloud / Foundry。Opus 4.7 的快速模式已被移除：在 4.7 上设置 speed: "fast" 将返回错误。Claude Opus 5 的快速模式定价为每 MTok $10 / $50。快速模式运行相同的模型，但输出 token 每秒速度最高可提升 2.5 倍，并收取溢价。每次请求必须满足三个条件：使用 beta 消息端点 (client.beta.messages.…)，传递 beta 标志 fast-mode-2026-02-01，并将 speed: "fast" 设置为顶层请求参数（而非请求头，也不在 extra_body 中）。

python
client.beta.messages.create(
    model="claude-opus-5", max_tokens=4096,
    speed="fast", betas=["fast-mode-2026-02-01"],
    messages=[...],
)

| 语言 | Beta 标志 | Speed 参数 |
|---|---|---|
| Python | betas=["fast-mode-2026-02-01"] | speed="fast" |
| TypeScript / Ruby | betas: ["fast-mode-2026-02-01"] | speed: "fast" |
| Go | []anthropic.AnthropicBeta{anthropic.Anth
| Python | betas=["fast-mode-2026-02-01"] | speed=anthropic.BetaMessageNewParamsSpeedFast |
| Java | .addBeta(AnthropicBeta.FAST_MODE_2026_02_01) | .speed(MessageCreateParams.Speed.FAST) |
| C# | Betas = ["fast-mode-2026-02-01"] | Speed = Speed.Fast (Anthropic.Models.Beta.Messages) |
| PHP | betas: ['fast-mode-2026-02-01'] | speed: 'fast' |
| cURL | anthropic-beta: fast-mode-2026-02-01 请求头 | 正文中的 "speed": "fast" |

response.usage.speed 会报告实际使用的速度。快速模式（Fast mode）拥有独立于标准 Opus 的速率限制；若遇到 429 错误，可在 retry-after 延迟后重试，或删除 speed 参数回退到标准模式（注意：切换速度会使提示词缓存失效）。该功能不支持 Batch API、Priority Tier、AWS 上的 Claude Platform 或第三方平台。

Priority Tier 不涵盖 Claude Opus 5。 它支持除 Opus 5 之外的所有当前模型，包括 Claude Fable 5 和 Opus 4.8。但 Claude Opus 5、Claude Sonnet 5、Claude Mythos 5 和 Mythos Preview 被排除在外 —— 若 Priority Tier 请求中指定这些模型，将导致验证失败。

---

任务预算 (快速参考)

Beta, Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7。 任务预算（Task budget）为 Claude 的智能体循环（agentic loop）提供一个 Token 上限，使其能够控制节奏并优雅地结束，而不是被强制截断 —— 这与 max_tokens 不同，后者是模型感知不到的、针对单次响应的强制上限。total 最小值：20,000。在 client.beta.messages.stream(...) 的 output_config 中设置 task_budget，并携带 beta 标志 task-budgets-2026-03-13 —— 请使用流式传输，以免较大的 max_tokens 导致 HTTP 超时（详情请参阅：shared/model-migration.md → Task Budgets）：

python
with client.beta.messages.stream(
    model="claude-opus-5", max_tokens=128000,
    output_config={"effort": "high", "task_budget": {"type": "tokens", "total": 64000}},
    betas=["task-budgets-2026-03-13"],
    messages=[...], tools=[...],
) as stream:
    response = stream.get_final_message()

task_budget 字段包括：type（始终为 "tokens"）、total 以及可选的 remaining（默认为 total）。服务器会在生成过程中注入一个 Claude 可见的倒计时标记；预算统计的是 Claude 本次生成的 Token 以及其读取的工具结果 —— 而非您每次请求重新发送的完整历史记录。这与 Managed Agents 会话预算 不同 —— 后者是针对单个 CMA 会话的、以美元计价的平台强制上限 (shared/managed-agents-core.md § Session budgets)；而任务预算是建议性的且以 Token 计价。

监控消耗： 如果需要显示进度，请在循环迭代中累加 response.usage.output_tokens（以及您附加的工具结果块的 Token 数）。在常规循环中请保持 remaining 为空 —— 服务器会自动跟踪倒计时，且在重新发送完整历史记录时传递客户端计算的 remaining 会导致预算报告偏低。仅在您在请求之间压缩或重写历史记录，导致服务器无法推断先前消耗时，才传递 remaining。

---

提供商客户端 (快速参考)

当目标是第三方平台上的 Claude 时，请使用该平台专用的客户端类，而不是通过覆盖 base_url 来使用官方的 Anthropic() 客户端。实例化后，该客户端提供与官方 SDK 相同的 messages.create / .stream 接口。

Amazon Bedrock

使用 Mantle 客户端（Messages-API Bedrock 端点）。Bedrock 模型 ID 需要带有 anthropic. 前缀（例如 "anthropic.claude-op
us-5"). 必须提供 Region。

| 语言 | 客户端 |
|---|---|
| Python | from anthropic import AnthropicBedrockMantle → AnthropicBedrockMantle(aws_region="…") |
| TypeScript | import { AnthropicBedrockMantle } from "@anthropic-ai/bedrock-sdk" → new AnthropicBedrockMantle({ awsRegion: "…" }) |
| Go | bedrock.NewMantleClient(ctx, bedrock.MantleClientConfig{ AWSRegion: "…" }) |
| Java | AnthropicOkHttpClient.builder().backend(BedrockMantleBackend.fromEnv()).build() (来自 com.anthropic.bedrock.backends) |
| C# | new AnthropicBedrockMantleClient(new() { AwsRegion = "…" }) (包 Anthropic.Bedrock) |
| PHP | use Anthropic\Bedrock\MantleClient; → new MantleClient(awsRegion: '…') |
| Ruby | Anthropic::BedrockMantleClient.new(aws_region: "…") |

AnthropicBedrock / BedrockClient / BedrockBackend（不含 Mantle）是旧版的 bedrock-runtime InvokeModel 路径 —— 新代码建议优先使用 Mantle 客户端。

Microsoft Foundry

| 语言 | 客户端 |
|---|---|
| Python | from anthropic import AnthropicFoundry → AnthropicFoundry(api_key=…, resource="…") |
| TypeScript | import AnthropicFoundry from "@anthropic-ai/foundry-sdk" → new AnthropicFoundry({ … }) |
| Java | AnthropicOkHttpClient.builder().backend(FoundryBackend.fromEnv()).build() (来自 com.anthropic.foundry.backends) |
| C# | new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(…)) (包 Anthropic.Foundry) |
| PHP | Foundry\Client::withCredentials(…) |

Go 和 Ruby SDK 目前不支持 Foundry。对于 Ruby，可使用标准 Anthropic::Client.new(base_url: "<foundry endpoint>") 作为备选方案（未内置 Entra ID 认证）。关于 AWS 上的 Claude Platform，请参阅 shared/claude-platform-on-aws.md。

Google Cloud Vertex AI

构造函数需要两个参数：GCP project_id 和 region。Vertex 模型 ID 不需要前缀 —— 当前一代模型（Opus 4.8/4.7/4.6, Sonnet 5, Sonnet 4.6）使用纯第一方 ID（例如 "claude-opus-5"）；快照版本模型使用 @ 作为版本分隔符（例如 claude-opus-4-5@20251101，而非 claude-opus-4-5-20251101）。认证采用 GCP ADC (gcloud auth application-default login)，无需 Anthropic API 密钥。region 可以是 "global"（推荐）、多区域（"us"/"eu"）或特定区域。实例化后，使用相同的 messages.create / .stream 接口。

| 语言 | 客户端 |
|---|---|
| Python | from anthropic import AnthropicVertex → AnthropicVertex(project_id="…", region="…") (安装 "anthropic[vertex]") |
| TypeScript | import { AnthropicVertex } from "@anthropic-ai/vertex-sdk" → new AnthropicVertex({ projectId, region }) |
| Go | import "github.com/anthropics/anthropic-sdk-go/vertex" → anthropic.NewClient(vertex.WithGoogleAuth(ctx, region, projectID)) |
| Java | AnthropicOkHttpClient.builder().backend(VertexBackend.builder().region("…").project("…").build()).build() (来自 com.anthropic.vertex.backends) |
| C# | new AnthropicClient { Backend = new VertexBackend(projectId, region) } (包 Anthropic.Vertex) |
| PHP | use Anthropic\Vertex; → Vertex\Client::fromEnvironment(location: '…', projectId: '…') — 注意是 location 而非 region |
| Ruby | Anthropic::VertexClient.new(region: "…", project_id: "…") |

---

上下文编辑 (快速参考)

Beta. 上下文编辑在模型读取对话前，会清除旧的工具结果或思考块；它不是压缩（summarization）。在 client.beta.messages.* 上使用。
使用 beta 版本 context-management-2025-06-27 时，请在 context_management.edits 中传递策略类型：

python
client.beta.messages.create(
    model="claude-opus-5", max_tokens=4096,
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
    tools=[...], messages=[...],
)

策略类型：clear_tool_uses_20250919（清除旧的工具结果；可选的 clear_tool_inputs: true 还会清除 tool_use 参数）和 clear_thinking_20251015（清除思考块）。不要使用 compact_20260112 或 beta 版本 compact-2026-01-12 —— 它们属于独立的压缩功能。

---

对话中途系统消息（快速参考）

适用于 Claude Opus 5, Claude Opus 4.8, Claude Fable 5 和 Claude Mythos 5；不适用于 Claude Sonnet 5；无需 beta 请求头。 将 {"role": "system", "content": "…"} 追加到 messages 数组中（而非顶层的 system 字段），即可在对话中途添加操作员指令，且不会使缓存前缀失效。使用常规的 client.messages.create —— 此功能无需 beta 版本。对话中途的系统消息必须紧跟在 user 消息（或以 server-tool 使用结尾的 assistant 消息）之后，且必须是 messages 的最后一项或其后紧跟 assistant 回复 —— 它不能作为 messages[0]。可用性请参阅 shared/platform-availability.md。详见 shared/prompt-caching.md 第 § Mid-conversation system messages 节。

---

托管代理 (Managed Agents) (Beta)

托管代理 (Managed Agents) 是第三种形态：由服务器管理的状态化代理，支持 Anthropic 托管的工具执行。您先创建一个持久化且带版本的代理配置 (POST /v1/agents)，然后启动引用该配置的会话 (Sessions)。每个会话都会配置一个容器作为代理的工作区 —— bash、文件操作和代码执行均在该容器中运行；代理循环本身运行在 Anthropic 的编排层，并通过工具作用于容器。会话会流式传输事件；您则发送消息和工具结果回传。

可用性请参阅 shared/platform-availability.md。对于 Bedrock / Vertex / Foundry 上的代理（不支持托管代理），请使用 Claude API + 工具调用。

强制流程： 代理 (仅一次) $\rightarrow$ 会话 (每次运行)。model/system/tools 定义在代理上，而非会话上。完整阅读指南、beta 请求头和注意事项请参阅 shared/managed-agents-overview.md。

Beta 请求头： managed-agents-2026-04-01 —— SDK 会为所有 client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.* 调用自动设置此项。Skills API 使用 skills-2025-10-02，Files API 使用 files-api-2025-04-14，但除了 /v1/skills 和 /v1/files 接口外，您无需显式传递这些请求头。

子命令 —— 直接通过 /claude-api <subcommand> 调用：

| 子命令 | 操作 |
|---|---|
| managed-agents-onboard | 引导用户从零开始设置托管代理。立即阅读 shared/managed-agents-onboarding.md 并遵循其访谈脚本：描述 $\rightarrow$ 配置代理（提出建议而非质询） $\rightarrow$ 环境 $\rightarrow$ 会话（流程与 Console 快速入门一致，身份验证推迟到会话步骤） —— 通过默认值和内联建议完成工作，在输出任何代码前设有静默可行性门槛（任务 vs 工具/凭据/数据）。不要进行总结 —— 请直接运行访谈。 |

阅读指南： 从 shared/managed-agents-overview.md 开始，然后阅读相关的 shared/managed-agents-*.md 文件（核心、环境、工具、事件、结果、多代理、Webhooks、内存）。
(例如：scheduled-deployments、client-patterns、onboarding、api-reference)。对于 Python、TypeScript、Go、Ruby、PHP 和 Java，请阅读 {lang}/managed-agents/README.md 以获取代码示例。对于 cURL，请阅读 curl/managed-agents.md。Agent 是持久化的 —— 创建一次，通过 ID 引用。 建议将 Agent 和环境定义为受版本控制的 YAML，并使用 ant CLI 应用 —— 这是推荐的工作流（参见 shared/anthropic-cli.md）：CLI 负责控制平面（创建和更新 Agent），而你的代码负责数据平面（使用存储的 Agent ID 调用 sessions.create）。仅在必须通过程序化配置时才在代码中调用 agents.create()；无论采用哪种方式，请存储返回的 Agent ID 并将其传递给后续的每一次 sessions.create；切勿在请求路径中调用 agents.create()。如果你需要的绑定未在语言 README 中显示，请通过 WebFetch 从 shared/live-sources.md 获取相关条目，而不要凭空猜测。C# 通过 client.Beta.Agents 及相关命名空间提供 Beta 版 Managed Agents 支持 —— 详情请参阅 csharp/claude-api/README.md，或参阅 curl/managed-agents.md 获取原始 HTTP 参考。

当用户想要从零开始设置 Managed Agent 时（例如：“如何入门”、“引导我创建一个”、“设置一个新 Agent”）：阅读 shared/managed-agents-onboarding.md 并运行其访谈流程 —— 该流程与 managed-agents-onboard 子命令一致。

当用户询问“如何编写 X 的客户端代码”时： 参考 shared/managed-agents-client-patterns.md —— 该文档涵盖了无损流重连、processed_at 队列/处理门控、中断、tool_confirmation 往返、正确的空闲/终止中断门控、空闲后状态竞态、流优先排序、文件挂载注意事项等。关于凭据，优先推荐使用 Vault environment_variable 凭据 —— 这是首选机制；密钥在出口处被替换，永远不会进入沙箱 (shared/managed-agents-tools.md → Vaults)。在 Vault 凭据不适用的情况下（例如自托管沙箱），通过自定义工具在主机端保留凭据是备选方案。

当用户希望 Agent 按计划运行时间时（cron、 “每晚”、“每周报告”）：阅读 shared/managed-agents-scheduled-deployments.md —— 部署将根据 cron 节奏自主触发会话，并提供单次触发的运行记录和生命周期控制（暂停/恢复/归档）。

当 Agent 的工作需要扇出时（跨多个来源研究、按文件或记录工作、“调查 N 件事然后总结”）或者单次循环会因读取而填满上下文时： 阅读 shared/managed-agents-multiagent.md 并推荐多 Agent 会话 —— 首先在名册中仅添加 {"type": "self"}，以便 Agent 可以委派给自己的副本，然后将读取密集型的子任务转移给通过 ID 引用的更廉价的工作 Agent（例如 Claude Haiku 4.5）。

---

服务器工具 (快速参考)

服务器端工具运行在 Anthropic 的基础设施上 —— 无需客户端执行循环。在 tools 中声明；结果将作为内容块随同一响应返回。除非另有说明，否则无需 Beta 请求头。请优先选择你的模型支持的最新类型变体。 下方 _20260209 版本的网页搜索/网页获取变体（支持动态过滤）需要 Opus 5/4.8/4.7/4.6、Sonnet 5 或 Sonnet 4.6；旧版模型的常规变体列在表格之后。

| 工具 | type | name | 关键可选参数 | 结果块类型 |
|---|---|---|---|---|
| 网页搜索 | web_search_20260209 | web_search | max_uses, allowed_domains/blocked_domains, user_location | we
| b_search_tool_result → .content 是 web_search_result 列表 |
| :--- | :--- |
| Web 抓取 | web_fetch_20260209 | web_fetch | max_uses, allowed_domains/blocked_domains, citations, max_content_tokens | web_fetch_tool_result → .content 是包含 document 块的 web_fetch_result |
| 代码执行 | code_execution_20260521 | code_execution | 无 | bash_code_execution_tool_result → .content.stdout / .stderr / .return_code |
| 工具搜索 (正则) | tool_search_tool_regex_20251119 | tool_search_tool_regex | 将其他工具标记为 defer_loading: true | tool_search_tool_result |
| 工具搜索 (BM25) | tool_search_tool_bm25_20251119 | tool_search_tool_bm25 | 将其他工具标记为 defer_loading: true | tool_search_tool_result |

web_search_20260209 / web_fetch_20260209 具有内置的动态过滤——代码执行在后台运行，因此不要在 tools 中单独声明 code_execution（第二个执行环境会干扰模型）。对于早于 Opus 4.6 / Sonnet 4.6 的模型，请使用基础版本 web_search_20250305 / web_fetch_20250910；在 Vertex AI 上仅可用基础版 web_search_20250305。code_execution_20260120（支持 REPL 持久化 + 编程化工具调用）运行在 Opus 4.5+ / Sonnet 4.5+ 上。仅限 Go SDK：code_execution_20260521 位于 client.Beta.Messages.New 且需配置 Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"}（其他语言使用普通的 client.messages.create）；code_execution_20260120 在 Go 中像其他语言一样使用非 beta 的 client.Messages.New。Web 抓取仅抓取对话中已存在的 URL。各工具的供应商可用性有所不同，请参阅 shared/platform-availability.md。关于 pause_turn 的处理，请参阅 shared/tool-use-concepts.md。

文档与文件输入（快速参考）

PDF (base64, 非 beta)： 在用户内容中，将 {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": <b64 string>}} 放置在文本块之前。Base64 字符串不得包含换行符。限制：请求大小 32 MB，最多 600 页（200k 上下文模型为 100 页）。Java：ContentBlockParam.ofDocument(DocumentBlockParam... Base64PdfSource.builder().data(...))。

Files API (beta files-api-2025-04-14)： 通过 client.beta.files.upload(...) 上传 $\rightarrow$ 响应中的 id 即为 file_id。PDF/文本引用为 {"type": "document", "source": {"type": "file", "file_id": "..."}}，图像引用为 {"type": "image", ...} —— 内容块类型必须与文件的 MIME 类型匹配。上传和引用该文件的 messages.create 请求均需要 beta 请求头。可用性详见 shared/platform-availability.md。

引用 (Citations, 非 beta)： 在每个 document 内容块上设置 citations: {enabled: true}（全部开启或全部关闭）。响应将拆分为多个 text 块；被引用块将携带 citations 数组。每条引用包含 cited_text、document_index、document_title 以及由 type 定义的位置：纯文本使用 char_location (start_char_index/end_char_index)，PDF 使用 page_location (start_page_number/end_page_number，从 1 开始计数)，自定义内容使用 content_block_location。与 output_config.format 不兼容（会返回 400 错误）。

工具使用模式（快速参考）

严格工具使用 (Strict tool use, 非 beta)： 在工具定义（与 name/description/input_schema 并列）中将 strict: true 设置为顶层字段，而不是在 tool_choice 中设置。Schema 必须包含 additionalProperties: false 和 required。这保证了 tool_
use.input 进行精确验证。Go：Strict: anthropic.Bool(true) + 通过 InputSchema.ExtraFields 设置 additionalProperties；Java：.strict(true) + .putAdditionalProperty("additionalProperties", JsonValue.from(false))。

并行工具调用（默认开启）： 一条助手消息可能包含多个 tool_use 块。请并发执行这些调用，然后将所有 tool_result 块放在一条用户消息中返回 —— 将其拆分到多条消息中会潜移默化地训练 Claude 停止进行并行调用。对于失败的工具，请返回 is_error: true 的 tool_result —— 不要将其丢弃。

Tool Runner（SDK beta 助手）： 通过 client.beta.messages.* 为你驱动工具调用循环。Python：@beta_tool 装饰器 + client.beta.messages.tool_runner(...) $\rightarrow$ runner.until_done()。TypeScript：@anthropic-ai/sdk/helpers/beta/zod 中的 betaZodTool({...}) + client.beta.messages.toolRunner(...) $\rightarrow$ await runner。Go：toolrunner.NewBetaToolFromJSONSchema(...) + client.Beta.Messages.NewToolRunner(...) $\rightarrow$ .RunToCompletion(ctx)。Java 需要 .addBeta("structured-outputs-2025-11-13")。Ruby：Anthropic::BaseTool 子类 + client.beta.messages.tool_runner(...)。PHP：BetaRunnableTool + ->toolRunner(...)。C#：原始 JSON-schema 工具 + 通过 client.Beta.Messages.ToolRunner(...) 使用 BetaToolRunner。

编程化工具调用（无需 beta 标头）： Claude 在代码执行内部调用你的自定义工具。请添加 {"type": "code_execution_20260120", "name": "code_execution"} 并且 在自定义工具上设置 "allowed_callers": ["code_execution_20260120"]。支持 Opus 4.5+ / Sonnet 4.5+（可用性详见 shared/platform-availability.md）。在响应待处理的编程化调用时，用户消息必须仅包含 tool_result 块（不能有文本）。不兼容 strict: true、disable_parallel_tool_use、强制 tool_choice 或 MCP 工具。

其他 API 接口（快速参考）

消息批处理（无需 beta；可用性详见 shared/platform-availability.md）： client.messages.batches.create(requests=[{custom_id, params}, ...]) $\rightarrow$ 轮询 client.messages.batches.retrieve(id).processing_status 直到变为 "ended" $\rightarrow$ 流式获取 client.messages.batches.results(id)。每个结果包含 .custom_id + .result.type (succeeded/errored/canceled/expired)；成功时读取 .result.message.content。Python 将请求封装为 Request(custom_id=..., params=MessageCreateParamsNonStreaming(...))。结果以任意顺序返回 —— 请通过 custom_id 匹配，绝不要依赖位置。

模型 API（无需 beta；可用性详见 shared/platform-availability.md）： client.models.list()（自动分页）和 client.models.retrieve("claude-opus-5")。每个模型对象包含 id、display_name、created_at，以及（自 2026 年 3 月起）max_input_tokens（上下文窗口）、max_tokens（输出上限）和 capabilities。没有 context_window 字段。

停止详情（GA，Opus 4.7+）： response.stop_details 仅在 stop_reason == "refusal" 时有值（字段包括：type: "refusal", category —— 一个开放集，例如 "cyber", "bio", "reasoning_extraction", "frontier_llm" 或 null；完整列表请参阅文档 —— 以及 explanation）。对于所有其他 stop_reason (end_turn, max_tokens, tool_use, pause_turn 等) 该字段均为 null —— 读取前请务必进行判空检查。

客户端配置（无需 beta）： timeout 默认 10 分钟；单位因 SDK 而异 —— Python/Ruby：秒；TypeScript：毫秒；Go option.WithRequestTimeout(time.Duration)；Java Duration；C# TimeSpan。
pan。对于非流式请求，若 max_tokens 较大，TS 会将默认超时时间延长至 60 分钟；Java 则在流式请求中如此处理（Java 非流式请求的范围为 30 秒至 10 分钟）。max_retries/maxRetries 默认为 2（重试 408/409/429/5xx 及连接错误）。base_url 可通过参数或 ANTHROPIC_BASE_URL 环境变量设置。单次请求覆盖方式：Python client.with_options(timeout=5.0).messages.create(...)；TS client.messages.create({...}, {timeout: 5_000})；Ruby request_options: {timeout: 5}。超时会触发重试 —— 实际墙钟时间最高可达 timeout × (max_retries+1)。

工作负载身份联合 (WIF) 快速参考

已正式发布 (GA)，无需 beta 请求头。 构建常规的无参客户端 (Anthropic() / new Anthropic() / anthropic.NewClient() / AnthropicOkHttpClient.fromEnv())；当 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_IDENTITY_TOKEN_FILE（或 ANTHROPIC_IDENTITY_TOKEN）全部设置时，SDK 会自动检测 WIF，在 /v1/oauth/token 交换 JWT 并自动刷新。ANTHROPIC_WORKSPACE_ID 不决定是否激活 —— 仅在联合规则跨多个工作区时才必需（否则报 400 workspace_id_required），单工作区规则则可选。ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN（即使为空）优先级高于 WIF，且设置了 ANTHROPIC_PROFILE 也会覆盖联合环境变量（缺失命名配置文件会报错，而不会回退） —— 请取消设置这三者。

---

阅读指南

在检测到语言后，根据用户需求阅读相关文件。

所有 SDK 语言均采用相同的多文件布局 —— 目录 {lang}/claude-api/ 包含 README.md（安装、客户端初始化、基础请求、思考、缓存、停止详情、杂项）、tool-use.md（工具定义、智能体循环、Anthropic 定义的工具、结构化输出）、streaming.md、batches.md、files-api.md。并非每种语言都有所有文件（例如 Ruby 没有 batches.md）；如果文件缺失，说明该功能的示例尚未在该语言中记录 —— 请参考 cURL 格式或通过 shared/live-sources.md 使用 WebFetch 访问 SDK 仓库。cURL $\rightarrow$ curl/examples.md。

下方的快速任务参考对所有语言均使用 {lang}/claude-api/FILE.md 路径表示法。

快速任务参考

单次文本分类/摘要/提取/问答：
$\rightarrow$ 仅阅读 {lang}/claude-api/README.md —— 任何任务（安装、快速上手、常见模式、错误处理）请务必先阅读 README

聊天 UI 或实时响应显示：
$\rightarrow$ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/streaming.md

长对话（可能超过上下文窗口）：
$\rightarrow$ 阅读 {lang}/claude-api/README.md —— 查看 Compaction（压缩）章节

迁移到更新的模型 (Fable 5 / Opus 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6)、替换已弃用模型，或将 budget_tokens / prefill 模式转换为当前 API：
$\rightarrow$ 阅读 shared/model-migration.md

针对 Fable 5 的提示词工程或调优（长轮次、努力程度、冗长程度、自主运行、子智能体）：
$\rightarrow$ 阅读 shared/model-migration.md $\rightarrow$ Migrating to Fable 5 $\rightarrow$ Behavioral shifts (prompt-tunable) + Long-running agent recommendations

提示词缓存 / 优化缓存 / “为什么我的缓存命中率低”：
$\rightarrow$ 阅读 shared/prompt-caching.md（前缀稳定性设计、断点放置、会导致缓存失效的反模式）+ {lang}/claude-api/README.md（Prompt Caching 章节）

审计或清理提示词、技能或工具描述：
提示词审计（如“此提示词是否过时”、“删除冗余”、“这是为旧模型编写的”）：
→ 阅读 shared/prompt-audit.md —— 包含带有可搜索信号的日期模式表、保留列表（不要删除的内容）以及报告 + 建议差异（proposed-diff）的输出约定。

统计文件/提示词/差异的 Token 数量（如“X 有多少个 token”）：
→ 阅读 shared/token-counting.md —— 使用 messages.count_tokens，绝不要使用 tiktoken。

函数调用 / 工具使用 / 智能体 (Agents)：
→ 阅读 {lang}/claude-api/README.md + shared/tool-use-concepts.md（概念基础：函数调用、代码执行、内存、结构化输出）+ {lang}/claude-api/tool-use.md（特定语言的代码示例：工具运行器、手动循环、代码执行、内存、结构化输出）。

智能体设计（工具界面、上下文管理、缓存策略）：
→ 阅读 shared/agent-design.md（bash 与专用工具的对比、程序化工具调用、工具搜索/技能、上下文编辑 vs 压缩 vs 内存、缓存原则）。

批处理 (Batch processing)（对延迟不敏感；异步运行，成本降低 50%)：
→ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/batches.md。

跨请求的文件上传（无需重复上传即可使用同一文件）：
→ 阅读 {lang}/claude-api/README.md + {lang}/claude-api/files-api.md。

调试 HTTP 错误或实现错误处理：
→ 阅读 shared/error-codes.md —— 各 SDK 类型化异常类表以及 Go 语言的 errors.As 模式。

最新的官方文档：
→ 使用 WebFetch 访问 shared/live-sources.md 中的 URL。

托管智能体 (Managed Agents)（由服务器管理状态且带有工作空间的智能体）：
→ 查看上方 ## Managed Agents (Beta) 章节中的阅读指南 —— 该部分列出了所有 shared/managed-agents-*.md 文件和特定语言的 README ({lang}/managed-agents/README.md, curl/managed-agents.md)。

---

何时使用 WebFetch

在以下情况下，使用 WebFetch 获取最新文档：

  • 用户询问“最新”或“当前”信息时
  • 缓存数据似乎不正确时
  • 用户询问此处未涵盖的功能时

实时文档 URL 位于 shared/live-sources.md 中。

常见陷阱

  • 不要在将文件或内容传递给 API 时截断输入。 如果内容过长而无法放入上下文窗口，请通知用户并讨论方案（分块、摘要等），而不是静默截断。
  • Prefill（预填）已被移除（Fable 5, Opus 5, Sonnet 5 以及 4.6/4.7/4.8 系列）： 在 Fable 5, Opus 5, Sonnet 5, Opus 4.6, Opus 4.7, Opus 4.8 和 Sonnet 4.6 上，助手消息预填（最后一次助手轮次预填）会返回 400 错误。请改用结构化输出 (output_config.format) 或系统提示词指令来控制响应格式。（唯一例外：fallback-credit 预填声明 —— 当使用 fallback_has_prefill_claim: true 兑换信用额度时，服务器接受回显的助手消息；详见迁移指南的拒绝部分。）
  • 在编辑前确认迁移范围： 当用户要求将代码迁移到更新的 Claude 模型，但未指定具体文件、目录或文件列表时，请先询问适用的范围 —— 是整个工作目录、特定子目录还是特定的一组文件。在用户确认之前不要开始编辑。诸如“迁移我的代码库”、“将我的项目迁移到 X”、“升级到 Sonnet 4.6”或简单的“迁移到 Opus 4.8”等祈使句仍然具有歧义 —— 它们告诉了你做什么，但没告诉你在哪里做，因此请询问。只有当提示词指明了具体文件、特定目录或...时，才在不询问的情况下继续。
  • 提供明确的文件列表（例如 "迁移 app.py"、"迁移 services/ 下的所有内容"、"更新 a.py 和 b.py"）。详见 shared/model-migration.md 的步骤 0。
  • max_tokens 默认值： 不要将 max_tokens 设置得太低 —— 触及上限会导致输出在思考中途被截断并需要重试。对于非流式请求，默认设置为 ~16000（以确保响应在 SDK HTTP 超时限制内）。对于流式请求，默认设置为 ~64000（无需担心超时，给模型留出空间）。仅在有明确理由时降低该值：如分类任务 (~256)、成本限制、刻意要求短输出，或使用 max_tokens: 0 进行缓存预热（见 shared/prompt-caching.md → Pre-warming）。
  • 禁用 Claude Opus 5 的思考功能有两种失效模式 —— 建议优先使用低/中等 effort。 这仅影响明确选择禁用的代码；思考功能默认开启，因此请留意是否继承了 Opus 4.8 的禁用设置。当设置 thinking: {type: "disabled"} 时，模型偶尔会将工具调用写入可见文本而非 tool_use 块：此时回合会成功，但调用从未执行，且不报错，在 Agent 循环中这段文本会污染后续回合。此外，它还可能将 <thinking> 标签泄露到响应中。开启思考并降低 effort 可同时解决这两个问题且依然能降低成本。如果某个路由必须禁用思考：删除所有“不要思考/不要推理”的规则（这会加剧标签泄露），不要命名思考标签，并添加综合指令：*"当你使用工具时，可以先说一句简短的话。如果没有工具能表达用户的要求，请直接说明而非猜测。响应中不要包含内部或系统的 XML 标签。"* 详情见：shared/model-migration.md → Two failure modes when thinking is disabled。
  • 128K 输出 Token： Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8, Sonnet 5 和 Sonnet 4.6 支持最高 128K 的 max_tokens，但 SDK 要求如此大的数值必须使用流式传输以避免 HTTP 超时。请使用 .stream() 配合 .get_final_message() / .finalMessage()。
  • 工具调用 JSON 解析（Fable 5, Opus 5 及 4.6/4.7/4.8 系列）： Fable 5, Opus 5, Opus 4.6, Opus 4.7, Opus 4.8 和 Sonnet 4.6 在工具调用的 input 字段中可能会产生不同的 JSON 字符串转义（例如 Unicode 或正斜杠转义）。请始终使用 json.loads() / JSON.parse() 解析工具输入 —— 绝不要对序列化后的输入进行原始字符串匹配。
  • 结构化输出（所有模型）： 在 messages.create() 中使用 output_config: {format: {...}} 代替已弃用的 output_format 参数。这是一个通用的 API 变更，并非 4.6 特有。
  • 不要重复实现 SDK 功能： SDK 提供了高级辅助方法 —— 请直接使用而非从零构建。具体而言：使用 stream.finalMessage() 而不是用 new Promise() 包装 .on() 事件；使用类型化的异常类（如 Anthropic.RateLimitError 等）而非通过字符串匹配错误消息；使用 SDK 类型（如 Anthropic.MessageParam, Anthropic.Tool, Anthropic.Message 等）而非重新定义等效接口。
  • 错误处理 —— 捕获异常链而非单一宽泛类。 单一的 except APIStatusError / catch (AnthropicServiceException) / rescue APIError 会丢失可重试（429, ≥500, 网络问题）与不可重试（400/404）故障之间的区别。请编写“由具体到通用”的捕获链 —— 例如：NotFoundError → RateLimitError → APIStatusError → APIConnectionError（或 Go 语言等效实现：使用 errors.As 转换为 *anthropic.Error 然后 switch apierr.StatusCode {）。
  • case 404: …; case 429: …; default: … })。各语言的类名和命名空间请参阅 shared/error-codes.md。
  • 不要研究 SDK 类型 —— 先写代码。 如果此技能包含的文档中没有显示某个类型名称，请根据语言特定文档中的命名空间/包表编写代码文件，并让编译器的错误引导你找到正确的名称。不要在编写之前花费过多时间进行 WebFetch、SDK 仓库克隆或编译运行单独的反射程序来探索类型名称 —— 先生成源文件，然后再修复编译器报告的问题。对已安装的 SDK 进行快速的 strings / jar tf / javap 操作以定位名称是可以接受的（因为几秒钟内即可返回），但不要超出此范围。类型名称错误的文件是可以修复的，而花费整个会话进行探索却没写出文件的行为则不然。
  • Bash 和文本编辑器工具由 Anthropic 定义，且无 schema。 请声明 {"type": "bash_20250124", "name": "bash"} / {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"} —— 无需 input_schema。自定义的名为 "bash" 且带有自有 schema 的工具将被视为不同的工具。处理程序路径和安全检查请参阅 shared/tool-use-concepts.md § Client-Side Tools。
  • Advisor 工具模型配对。 Advisor 工具的 model 能力必须至少与请求的顶层 model 一致 —— 例如：执行器 claude-sonnet-5 $\rightarrow$ Advisor claude-opus-4-8 或 claude-opus-4-7。无效的配对将返回 400。配对表见 shared/tool-use-concepts.md § Advisor。可用性见 shared/platform-availability.md。
  • Agent Skills $\neq$ Managed Agents。 若要让 Claude 通过 Agent Skills 生成 .pptx/.xlsx 等文件，请调用 client.beta.messages.create 并配置 container={"skills": [...]}、code_execution_20260521 工具，以及 code-execution-2025-08-25 和 skills-2025-10-02 这两个 beta 版本。此处不要使用 client.beta.agents / sessions / environments —— 那些属于 Managed Agents 界面，而非 Agent Skills。
  • MCP 连接器需要两部分配置。 仅提供 mcp_servers=[{type:"url", url, name}] 会被视为验证错误 —— 还需要添加 tools=[{type:"mcp_toolset", mcp_server_name:<相同名称>}] 并使用 beta 版本 mcp-client-2025-11-20。可用性见 shared/platform-availability.md。
  • inference_geo 是直接的顶层请求参数 —— client.messages.create(..., inference_geo="us") / .inferenceGeo("us")。不要将其放入 extra_body / putAdditionalBodyProperty 中。（仅限 Messages API —— 在 Managed Agents 中，inference_geo 嵌套在 agent 的 model 对象内部，而非顶层；详见 shared/managed-agents-core.md § Pinning inference geography。）支持 Opus 4.6 / Sonnet 4.6 及更高版本；可用性见 shared/platform-availability.md。response.usage.inference_geo 会报告推理运行的位置。
  • 细粒度工具流（Fine-grained tool streaming）不是 beta 功能。 在工具定义中设置 eager_input_streaming: true 并调用常规的 client.messages.stream(...) 即可。无需 beta 请求头，也无需 client.beta.* 路径。
  • 缓存诊断（Cache diagnostics）是 beta 功能。 使用 client.beta.messages.* 并配合 beta 版本 cache-diagnosis-2026-04-07。在第一轮对话中传递 diagnostics: {previous_message_id: null}，在后续轮次中传递 diagnostics: {previous_message_id: <前一次响应 ID>}；结果位于 response.diagnostics 中。可用性见 shared/platform-availability.md。
  • Memory 工具类型为 memory_20250818。 声明 {"type": "memory_20250818", "name": "memory"}。Go 语言使用 beta 命名空间类型 {OfMemoryTool20
  • 250818: &anthropic.BetaMemoryTool20250818Param{}} 用于 client.Beta.Messages.New；Python/TypeScript/Ruby/PHP/C# 请使用非 beta 版本的 client.messages.create；Java 同时提供非 beta 版本的 MemoryTool20250818 和 beta 工具运行路径。Python/TypeScript 提供了 BetaAbstractMemoryTool / betaMemoryTool 辅助类用于实现后端。
  • 使用该功能实际支持的模型。 某些功能仅限于特定的模型层级 —— 快速模式（fast mode）仅支持 Claude Opus 5 / Opus 4.8（且仅限 Claude API）；任务预算（task budgets，仅限 Messages API —— Managed Agents 会话预算无模型层级限制）仅支持 Claude Opus 5 / Fable 5 / Sonnet 5 / Opus 4.8 / 4.7；顾问工具（advisor tool）需要有效的执行器↔顾问配对。如果用户提示词中指定的模型不支持该功能，请改用支持的模型并在输出中注明。
  • 不要为 SDK 数据结构定义自定义类型： SDK 为所有 API 对象导出了类型。消息请使用 Anthropic.MessageParam，工具定义使用 Anthropic.Tool，工具结果使用 Anthropic.ToolUseBlock / Anthropic.ToolResultBlockParam，响应使用 Anthropic.Message。定义自己的 interface ChatMessage { role: string; content: unknown } 会与 SDK 提供的类型重复，并导致丢失类型安全性。
  • 报告与文档输出： 对于需要生成报告、文档或可视化图表的任务，代码执行沙箱已预装 python-docx、python-pptx、matplotlib、pillow 和 pypdf。Claude 可以生成格式化文件（DOCX, PDF, 图表）并通过 Files API 返回 —— 对于“报告”或“文档”类请求，请考虑使用此方式而非简单的 stdout 文本。
  • 服务端工具错误不会抛出异常。 网页搜索（web search）和网页抓取（web fetch）错误会返回 HTTP 200，并包含一个 web_search_tool_result / web_fetch_tool_result 块，其 content 为单个错误对象（例如 {error_code: "max_uses_exceeded"}），而非抛出异常。对于网页搜索，成功时的 content 是一个*列表*，而错误时的 content 是一个*对象* —— 在进行索引操作前请先进行分支判断。
  • 代码执行输出块类型： code_execution_20260521 返回的是 bash_code_execution_tool_result（包含 .content.stdout），而非 旧版的 code_execution_tool_result。请遍历 response.content 并匹配正确的类型。
  • 工具搜索：绝不能全部延迟加载。 搜索工具本身不能设置 defer_loading: true，且 tools 列表中必须至少有一个工具是非延迟加载的，否则 API 将返回 400 错误 All tools have defer_loading set。