claude-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building LLM-Powered Applications with Claude

使用Claude构建基于LLM的应用

This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.

本技能可帮助您使用Claude构建基于LLM的应用。根据需求选择合适的交互方式，检测项目语言，然后阅读对应语言的相关文档。

Defaults

默认设置

Unless the user requests otherwise:

For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string

claude-opus-4-6

. Please default to using adaptive thinking (

thinking: {type: "adaptive"}

) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high

max_tokens

— it prevents hitting request timeouts. Use the SDK's

.get_final_message()

.finalMessage()

helper to get the complete response if you don't need to handle individual stream events

除非用户另有要求：

关于Claude模型版本，请使用Claude Opus 4.6，可通过精确的模型字符串

claude-opus-4-6

访问。对于任何稍微复杂的任务，请默认使用自适应思考（

thinking: {type: "adaptive"}

）。最后，对于任何可能涉及长输入、长输出或高

max_tokens

的请求，请默认使用流式传输——这可以避免请求超时。如果不需要处理单个流事件，请使用SDK的

.get_final_message()

.finalMessage()

助手来获取完整响应

Language Detection

语言检测

Before reading code examples, determine which language the user is working in:

Look at project files to infer the language:
- ```
*.py
```
  ,
```
requirements.txt
```
  ,
```
pyproject.toml
```
  ,
```
setup.py
```
  ,
```
Pipfile
```
  → Python — read from
```
python/
```
- ```
*.ts
```
  ,
```
*.tsx
```
  ,
```
package.json
```
  ,
```
tsconfig.json
```
  → TypeScript — read from
```
typescript/
```
- ```
*.js
```
  ,
```
*.jsx
```
  (no
```
.ts
```
  files present) → TypeScript — JS uses the same SDK, read from
```
typescript/
```
- ```
*.java
```
  ,
```
pom.xml
```
  ,
```
build.gradle
```
  → Java — read from
```
java/
```
- ```
*.kt
```
  ,
```
*.kts
```
  ,
```
build.gradle.kts
```
  → Java — Kotlin uses the Java SDK, read from
```
java/
```
- ```
*.scala
```
  ,
```
build.sbt
```
  → Java — Scala uses the Java SDK, read from
```
java/
```
- ```
*.go
```
  ,
```
go.mod
```
  → Go — read from
```
go/
```
- ```
*.rb
```
  ,
```
Gemfile
```
  → Ruby — read from
```
ruby/
```
- ```
*.cs
```
  ,
```
*.csproj
```
  → C# — read from
```
csharp/
```
- ```
*.php
```
  ,
```
composer.json
```
  → PHP — read from
```
php/
```
If multiple languages detected (e.g., both Python and TypeScript files):
- Check which language the user's current file or question relates to
- If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"
If language can't be inferred (empty project, no source files, or unsupported language):
- Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
- If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."
If unsupported language detected (Rust, Swift, C++, Elixir, etc.):
- Suggest cURL/raw HTTP examples from
```
curl/
```
  and note that community SDKs may exist
- Offer to show Python or TypeScript examples as reference implementations
If user needs cURL/raw HTTP examples, read from
```
curl/
```
.

查看代码示例前，请先确定用户使用的开发语言：

查看项目文件推断语言：
- ```
*.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/
```
  目录下的内容
检测到多种语言时（例如同时存在Python和TypeScript文件）：
- 检查用户当前文件或问题涉及哪种语言
- 如果仍不明确，询问：“我检测到同时存在Python和TypeScript文件。您在集成Claude API时使用哪种语言？”
无法推断语言时（空项目、无源码文件或不支持的语言）：
- 使用AskUserQuestion提供选项：Python、TypeScript、Java、Go、Ruby、cURL/原生HTTP、C#、PHP
- 如果无法使用AskUserQuestion，默认展示Python示例并说明：“当前展示Python示例。如果您需要其他语言的示例，请告知。”
检测到不支持的语言时（Rust、Swift、C++、Elixir等）：
- 建议使用
```
curl/
```
  目录下的cURL/原生HTTP示例，并说明可能存在社区SDK
- 可提供Python或TypeScript示例作为参考实现
如果用户需要cURL/原生HTTP示例，读取
```
curl/
```
目录下的内容。

Language-Specific Feature Support

各语言功能支持情况

Language	Tool Runner	Agent SDK	Notes
Python	Yes (beta)	Yes	Full support — `@beta_tool` decorator
TypeScript	Yes (beta)	Yes	Full support — `betaZodTool` + Zod
Java	Yes (beta)	No	Beta tool use with annotated classes
Go	Yes (beta)	No	`BetaToolRunner` in `toolrunner` pkg
Ruby	Yes (beta)	No	`BaseTool` + `tool_runner` in beta
cURL	N/A	N/A	Raw HTTP, no SDK features
C#	No	No	Official SDK
PHP	No	No	Official SDK

语言	工具运行器	Agent SDK	说明
Python	是（测试版）	是	完整支持 — `@beta_tool` 装饰器
TypeScript	是（测试版）	是	完整支持 — `betaZodTool` + Zod
Java	是（测试版）	否	使用注解类的测试版工具支持
Go	是（测试版）	否	`toolrunner` 包中的 `BetaToolRunner`
Ruby	是（测试版）	否	测试版中的 `BaseTool` + `tool_runner`
cURL	不适用	不适用	原生HTTP，无SDK功能
C#	否	否	官方SDK
PHP	否	否	官方SDK

Which Surface Should I Use?

应选择哪种交互方式？

Start simple. Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.

Use Case	Tier	Recommended Surface	Why
Classification, summarization, extraction, Q&A	Single LLM call	Claude API	One request, one response
Batch processing or embeddings	Single LLM call	Claude API	Specialized endpoints
Multi-step pipelines with code-controlled logic	Workflow	Claude API + tool use	You orchestrate the loop
Custom agent with your own tools	Agent	Claude API + tool use	Maximum flexibility
AI agent with file/web/terminal access	Agent	Agent SDK	Built-in tools, safety, and MCP support
Agentic coding assistant	Agent	Agent SDK	Designed for this use case
Want built-in permissions and guardrails	Agent	Agent SDK	Safety features included

Note: The Agent SDK is for when you want built-in file/web/terminal tools, permissions, and MCP out of the box. If you want to build an agent with your own tools, Claude API is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).

从简单开始。 默认选择能满足需求的最简单层级。单次API调用和工作流可处理大多数用例——只有当任务确实需要开放式、模型驱动的探索时，才使用Agent。

用例	层级	推荐交互方式	原因
分类、摘要、提取、问答	单次LLM调用	Claude API	一次请求，一次响应
批量处理或嵌入任务	单次LLM调用	Claude API	专用端点
代码控制逻辑的多步骤流水线	工作流	Claude API + 工具调用	由您编排循环流程
自定义工具的Agent	Agent	Claude API + 工具调用	最大灵活性
具备文件/网页/终端访问能力的AI Agent	Agent	Agent SDK	内置工具、安全机制和MCP支持
Agentic编码助手	Agent	Agent SDK	为此类任务设计
需要内置权限和防护机制	Agent	Agent SDK	包含安全功能

注意： Agent SDK适用于需要内置文件/网页/终端工具、权限和MCP的场景。如果您想使用自定义工具构建Agent，Claude API是正确选择——可使用工具运行器自动处理循环，或手动编写循环实现精细控制。

Decision Tree

决策树

What does your application need?

1. Single LLM call (classification, summarization, extraction, Q&A)
   └── Claude API — one request, one response

2. Does Claude need to read/write files, browse the web, or run shell commands
   as part of its work? (Not: does your app read a file and hand it to Claude —
   does Claude itself need to discover and access files/web/shell?)
   └── Yes → Agent SDK — built-in tools, don't reimplement them
       Examples: "scan a codebase for bugs", "summarize every file in a directory",
                 "find bugs using subagents", "research a topic via web search"

3. Workflow (multi-step, code-orchestrated, with your own tools)
   └── Claude API with tool use — you control the loop

4. Open-ended agent (model decides its own trajectory, your own tools)
   └── Claude API agentic loop (maximum flexibility)

您的应用需要什么？

1. 单次LLM调用（分类、摘要、提取、问答）
   └── Claude API — 一次请求，一次响应

2. Claude在工作中是否需要读取/写入文件、浏览网页或运行Shell命令？
   （注意：不是指您的应用读取文件后交给Claude——而是Claude自身是否需要发现并访问文件/网页/Shell？）
   └── 是 → Agent SDK — 内置工具，无需重新实现
       示例："扫描代码库查找漏洞"、"汇总目录中的所有文件"、
             "使用子Agent查找漏洞"、"通过网页搜索研究主题"

3. 工作流（多步骤、代码编排、使用自定义工具）
   └── 带工具调用的Claude API — 由您控制循环

4. 开放式Agent（模型自主决定执行路径、使用自定义工具）
   └── Claude API Agentic循环（最大灵活性）

Should I Build an Agent?

是否应该构建Agent？

Before choosing the agent tier, check all four criteria:

Complexity — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
Value — Does the outcome justify higher cost and latency?
Viability — Is Claude capable at this task type?
Cost of error — Can errors be caught and recovered from? (tests, review, rollback)

If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).

选择Agent层级前，请检查以下四个标准：

复杂度 — 任务是否为多步骤且难以提前完全明确？（例如“将此设计文档转换为PR” vs “从PDF中提取标题”）
价值 — 结果是否值得更高的成本和延迟？
可行性 — Claude是否能胜任此类任务？
错误成本 — 错误是否可以被捕获并恢复？（测试、审核、回滚）

如果任何一个问题的答案是“否”，请停留在更简单的层级（单次调用或工作流）。

Architecture

架构

Everything goes through

POST /v1/messages

. Tools and output constraints are features of this single endpoint — not separate APIs.

User-defined tools — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.

Server-side tools — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in

tools

, Claude runs code automatically). Computer use can be server-hosted or self-hosted.

Structured outputs — Constrains the Messages API response format (

output_config.format

) and/or tool parameter validation (

strict: true

). The recommended approach is

client.messages.parse()

which validates responses against your schema automatically. Note: the old

output_format

parameter is deprecated; use

output_config: {format: {...}}

messages.create()

Supporting endpoints — Batches (

POST /v1/messages/batches

), Files (

POST /v1/files

), and Token Counting feed into or support Messages API requests.

所有请求均通过

POST /v1/messages

处理。工具和输出约束是该单一端点的功能——而非独立API。

用户定义工具 — 您可以通过装饰器、Zod模式或原生JSON定义工具，SDK的工具运行器会处理API调用、执行函数并循环直到Claude完成任务。如果需要完全控制，也可以手动编写循环。

服务器端工具 — Anthropic托管的工具，运行在Anthropic的基础设施上。代码执行完全在服务器端（在

tools

中声明，Claude会自动运行代码）。计算机使用功能可以是服务器托管或自托管。

结构化输出 — 约束Messages API的响应格式（

output_config.format

）和/或工具参数验证（

strict: true

）。推荐使用

client.messages.parse()

，它会自动根据您的模式验证响应。注意：旧的

output_format

参数已被弃用；请在

messages.create()

上使用

output_config: {format: {...}}

。

辅助端点 — 批量处理（

POST /v1/messages/batches

）、文件上传（

POST /v1/files

）和Token计数功能为Messages API请求提供支持。

Current Models (cached: 2026-02-17)

当前模型（缓存时间：2026-02-17）

Model	Model ID	Context	Input $/1M	Output $/1M
Claude Opus 4.6	`claude-opus-4-6`	200K (1M beta)	$5.00	$25.00
Claude Sonnet 4.6	`claude-sonnet-4-6`	200K (1M beta)	$3.00	$15.00
Claude Haiku 4.5	`claude-haiku-4-5`	200K	$1.00	$5.00

ALWAYS use
claude-opus-4-6
unless the user explicitly names a different model. This is non-negotiable. Do not use

claude-sonnet-4-6

claude-sonnet-4-5

, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours.

CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes. For example, use

claude-sonnet-4-5

, never

claude-sonnet-4-5-20250514

or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read

shared/models.md

for the exact ID — do not construct one yourself.

A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.

模型	模型ID	上下文窗口	输入成本$/1M	输出成本$/1M
Claude Opus 4.6	`claude-opus-4-6`	200K（1M测试版）	$5.00	$25.00
Claude Sonnet 4.6	`claude-sonnet-4-6`	200K（1M测试版）	$3.00	$15.00
Claude Haiku 4.5	`claude-haiku-4-5`	200K	$1.00	$5.00

除非用户明确指定其他模型，否则始终使用
claude-opus-4-6
。这是必须遵守的规则。不要使用

claude-sonnet-4-6

、

claude-sonnet-4-5

或任何其他模型，除非用户明确说“使用sonnet”或“使用haiku”。绝不要为了降低成本而降级模型——这是用户的决定，不由您做主。

重要提示：仅使用上表中的精确模型ID字符串——这些ID是完整的。不要添加日期后缀。 例如，使用

claude-sonnet-4-5

，绝不要使用

claude-sonnet-4-5-20250514

或您可能记得的任何带日期后缀的变体。如果用户请求上表中未列出的旧模型（例如“opus 4.5”、“sonnet 3.7”），请阅读

shared/models.md

获取精确ID——不要自行构造。

说明：如果上表中的某些模型字符串看起来不熟悉，这是正常的——这意味着它们是在您的训练数据截止日期之后发布的。请放心，这些都是真实存在的模型，我们不会故意误导您。

Thinking & Effort (Quick Reference)

思考与算力快速参考

Opus 4.6 — Adaptive thinking (recommended): Use

thinking: {type: "adaptive"}

. Claude dynamically decides when and how much to think. No

budget_tokens

needed —

budget_tokens

is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). When the user asks for "extended thinking", a "thinking budget", or
budget_tokens
: always use Opus 4.6 with
thinking: {type: "adaptive"}
. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use
budget_tokens
and do NOT switch to an older model.

Effort parameter (GA, no beta header): Controls thinking depth and overall token spend via

output_config: {effort: "low"|"medium"|"high"|"max"}

(inside

output_config

, not top-level). Default is

high

(equivalent to omitting it).

max

is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Use

low

for subagents or simple tasks;

max

for the deepest reasoning.

Sonnet 4.6: Supports adaptive thinking (

thinking: {type: "adaptive"}

budget_tokens

is deprecated on Sonnet 4.6 — use adaptive thinking instead.

Older models (only if explicitly requested): If the user specifically asks for Sonnet 4.5 or another older model, use

thinking: {type: "enabled", budget_tokens: N}

budget_tokens

must be less than

max_tokens

(minimum 1024). Never choose an older model just because the user mentions

budget_tokens

— use Opus 4.6 with adaptive thinking instead.

Opus 4.6 — 自适应思考（推荐）： 使用

thinking: {type: "adaptive"}

。Claude会动态决定思考的时机和深度。不需要

budget_tokens

——

budget_tokens

在Opus 4.6和Sonnet 4.6上已被弃用，严禁使用。自适应思考还会自动启用交错思考（无需测试版头信息）。当用户要求“扩展思考”、“思考预算”或
budget_tokens
时：始终使用Opus 4.6并设置
thinking: {type: "adaptive"}
。固定思考Token预算的概念已被弃用——自适应思考已取代它。请勿使用
budget_tokens
，也不要切换到旧模型。

算力参数（正式发布，无需测试版头信息）： 通过

output_config: {effort: "low"|"medium"|"high"|"max"}

控制思考深度和整体Token消耗（位于

output_config

内，而非顶级参数）。默认值为

high

（等同于省略该参数）。

max

仅适用于Opus 4.6。适用于Opus 4.5、Opus 4.6和Sonnet 4.6。在Sonnet 4.5 / Haiku 4.5上使用会报错。结合自适应思考可实现最佳的成本-质量平衡。对于子Agent或简单任务使用

low

；对于深度推理使用

max

。

Sonnet 4.6： 支持自适应思考（

thinking: {type: "adaptive"}

）。

budget_tokens

在Sonnet 4.6上已被弃用——请使用自适应思考替代。

旧模型（仅在明确请求时使用）： 如果用户特别要求使用Sonnet 4.5或其他旧模型，使用

thinking: {type: "enabled", budget_tokens: N}

。

budget_tokens

必须小于

max_tokens

（最小值1024）。绝不要因为用户提到

budget_tokens

就切换到旧模型——请使用Opus 4.6和自适应思考。

Compaction (Quick Reference)

压缩功能快速参考

Beta, Opus 4.6 only. For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header

compact-2026-01-12

Critical: Append

response.content

(not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.

See

{lang}/claude-api/README.md

(Compaction section) for code examples. Full docs via WebFetch in

shared/live-sources.md

测试版，仅适用于Opus 4.6。 对于可能超过200K上下文窗口的长对话，启用服务器端压缩。当接近触发阈值（默认：150K Token）时，API会自动总结早期上下文。需要测试版头信息

compact-2026-01-12

。

关键注意事项： 在每一轮对话中，将

response.content

（不仅仅是文本）追加到消息中。必须保留响应中的压缩块——API会在下次请求中使用它们替换已压缩的历史记录。仅提取文本字符串并追加会静默丢失压缩状态。

代码示例请参见

{lang}/claude-api/README.md

的压缩部分。完整文档请参见

shared/live-sources.md

中的WebFetch链接。

Reading Guide

阅读指南

After detecting the language, read the relevant files based on what the user needs:

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

Quick Task Reference

快速任务参考

Single text classification/summarization/extraction/Q&A: → Read only

{lang}/claude-api/README.md

Chat UI or real-time response display: → Read

{lang}/claude-api/README.md

{lang}/claude-api/streaming.md

Long-running conversations (may exceed context window): → Read

{lang}/claude-api/README.md

— see Compaction section

Function calling / tool use / agents: → Read

{lang}/claude-api/README.md

shared/tool-use-concepts.md

{lang}/claude-api/tool-use.md

Batch processing (non-latency-sensitive): → Read

{lang}/claude-api/README.md

{lang}/claude-api/batches.md

File uploads across multiple requests: → Read

{lang}/claude-api/README.md

{lang}/claude-api/files-api.md

Agent with built-in tools (file/web/terminal): → Read

{lang}/agent-sdk/README.md

{lang}/agent-sdk/patterns.md

单一文本分类/摘要/提取/问答： → 仅阅读

{lang}/claude-api/README.md

聊天UI或实时响应展示： → 阅读

{lang}/claude-api/README.md

{lang}/claude-api/streaming.md

长对话（可能超过上下文窗口）： → 阅读

{lang}/claude-api/README.md

— 查看压缩部分

函数调用/工具使用/Agent： → 阅读

{lang}/claude-api/README.md

shared/tool-use-concepts.md

{lang}/claude-api/tool-use.md

批量处理（对延迟不敏感）： → 阅读

{lang}/claude-api/README.md

{lang}/claude-api/batches.md

跨多个请求的文件上传： → 阅读

{lang}/claude-api/README.md

{lang}/claude-api/files-api.md

带内置工具的Agent（文件/网页/终端）： → 阅读

{lang}/agent-sdk/README.md

{lang}/agent-sdk/patterns.md

Claude API (Full File Reference)

Claude API完整文件参考

Read the language-specific Claude API folder (

{language}/claude-api/

{language}/claude-api/README.md
— Read this first. Installation, quick start, common patterns, error handling.
shared/tool-use-concepts.md
— Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
{language}/claude-api/tool-use.md
— Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
{language}/claude-api/streaming.md
— Read when building chat UIs or interfaces that display responses incrementally.
{language}/claude-api/batches.md
— Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
{language}/claude-api/files-api.md
— Read when sending the same file across multiple requests without re-uploading.
shared/error-codes.md
— Read when debugging HTTP errors or implementing error handling.
shared/live-sources.md
— WebFetch URLs for fetching the latest official documentation.

Note: For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus
shared/tool-use-concepts.md
and
shared/error-codes.md
as needed.

阅读对应语言的Claude API文件夹（

{language}/claude-api/

）：

{language}/claude-api/README.md
— 优先阅读。安装、快速开始、常见模式、错误处理。
shared/tool-use-concepts.md
— 当用户需要函数调用、代码执行、内存或结构化输出时阅读。涵盖概念基础。
{language}/claude-api/tool-use.md
— 阅读对应语言的工具使用代码示例（工具运行器、手动循环、代码执行、内存、结构化输出）。
{language}/claude-api/streaming.md
— 构建聊天UI或增量显示响应的界面时阅读。
{language}/claude-api/batches.md
— 离线处理大量请求（对延迟不敏感）时阅读。异步运行，成本降低50%。
{language}/claude-api/files-api.md
— 在多个请求中发送同一文件而无需重新上传时阅读。
shared/error-codes.md
— 调试HTTP错误或实现错误处理时阅读。
shared/live-sources.md
— 获取最新官方文档的WebFetch链接。

注意： Java、Go、Ruby、C#、PHP和cURL各有一个涵盖所有基础内容的单一文件。根据需要阅读该文件以及
shared/tool-use-concepts.md
和
shared/error-codes.md
。

Agent SDK

Read the language-specific Agent SDK folder (

{language}/agent-sdk/

). Agent SDK is available for Python and TypeScript only.

{language}/agent-sdk/README.md
— Installation, quick start, built-in tools, permissions, MCP, hooks.
{language}/agent-sdk/patterns.md
— Custom tools, hooks, subagents, MCP integration, session resumption.
shared/live-sources.md
— WebFetch URLs for current Agent SDK docs.

阅读对应语言的Agent SDK文件夹（

{language}/agent-sdk/

）。Agent SDK仅支持Python和TypeScript。

{language}/agent-sdk/README.md
— 安装、快速开始、内置工具、权限、MCP、钩子。
{language}/agent-sdk/patterns.md
— 自定义工具、钩子、子Agent、MCP集成、会话恢复。
shared/live-sources.md
— 当前Agent SDK文档的WebFetch链接。

When to Use WebFetch

何时使用WebFetch

Use WebFetch to get the latest documentation when:

User asks for "latest" or "current" information
Cached data seems incorrect
User asks about features not covered here

Live documentation URLs are in

shared/live-sources.md

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

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

实时文档链接位于

shared/live-sources.md

中。

Common Pitfalls

常见陷阱

Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
Opus 4.6 / Sonnet 4.6 thinking: Use
```
thinking: {type: "adaptive"}
```
— do NOT use
```
budget_tokens
```
(deprecated on both Opus 4.6 and Sonnet 4.6). For older models,
```
budget_tokens
```
must be less than
```
max_tokens
```
(minimum 1024). This will throw an error if you get it wrong.
Opus 4.6 prefill removed: Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (
```
output_config.format
```
) or system prompt instructions to control response format instead.
128K output tokens: Opus 4.6 supports up to 128K
```
max_tokens
```
, but the SDKs require streaming for large
```
max_tokens
```
to avoid HTTP timeouts. Use
```
.stream()
```
with
```
.get_final_message()
```
/
```
.finalMessage()
```
.
Tool call JSON parsing (Opus 4.6): Opus 4.6 may produce different JSON string escaping in tool call
```
input
```
fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with
```
json.loads()
```
/
```
JSON.parse()
```
— never do raw string matching on the serialized input.
Structured outputs (all models): Use
```
output_config: {format: {...}}
```
instead of the deprecated
```
output_format
```
parameter on
```
messages.create()
```
. This is a general API change, not 4.6-specific.
Don't reimplement SDK functionality: The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use
```
stream.finalMessage()
```
instead of wrapping
```
.on()
```
events in
```
new Promise()
```
; use typed exception classes (
```
Anthropic.RateLimitError
```
, etc.) instead of string-matching error messages; use SDK types (
```
Anthropic.MessageParam
```
,
```
Anthropic.Tool
```
,
```
Anthropic.Message
```
, etc.) instead of redefining equivalent interfaces.
Don't define custom types for SDK data structures: The SDK exports types for all API objects. Use
```
Anthropic.MessageParam
```
for messages,
```
Anthropic.Tool
```
for tool definitions,
```
Anthropic.ToolUseBlock
```
/
```
Anthropic.ToolResultBlockParam
```
for tool results,
```
Anthropic.Message
```
for responses. Defining your own
```
interface ChatMessage { role: string; content: unknown }
```
duplicates what the SDK already provides and loses type safety.
Report and document output: For tasks that produce reports, documents, or visualizations, the code execution sandbox has
```
python-docx
```
,
```
python-pptx
```
,
```
matplotlib
```
,
```
pillow
```
, and
```
pypdf
```
pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.

向API传递文件或内容时不要截断输入。如果内容太长无法放入上下文窗口，请通知用户并讨论解决方案（分块、摘要等），不要静默截断。
Opus 4.6 / Sonnet 4.6思考设置： 使用
```
thinking: {type: "adaptive"}
```
— 请勿使用
```
budget_tokens
```
（在这两个模型上已弃用）。对于旧模型，
```
budget_tokens
```
必须小于
```
max_tokens
```
（最小值1024）。如果设置错误会抛出错误。
Opus 4.6已移除预填充： 在Opus 4.6上，助手消息预填充（最后一轮助手消息预填充）会返回400错误。请使用结构化输出（
```
output_config.format
```
）或系统提示指令来控制响应格式。
128K输出Token： Opus 4.6支持最高128K的
```
max_tokens
```
，但SDK需要使用流式传输来避免HTTP超时。使用
```
.stream()
```
结合
```
.get_final_message()
```
/
```
.finalMessage()
```
。
工具调用JSON解析（Opus 4.6）： Opus 4.6在工具调用
```
input
```
字段中可能生成不同的JSON字符串转义方式（例如Unicode或正斜杠转义）。始终使用
```
json.loads()
```
/
```
JSON.parse()
```
解析工具输入——绝不要对序列化输入进行原始字符串匹配。
结构化输出（所有模型）： 在
```
messages.create()
```
上使用
```
output_config: {format: {...}}
```
替代已弃用的
```
output_format
```
参数。这是通用API变更，并非4.6版本专属。
不要重新实现SDK功能： SDK提供了高级助手函数——请使用它们而非从头构建。具体来说：使用
```
stream.finalMessage()
```
而非将
```
.on()
```
事件包装在
```
new Promise()
```
中；使用类型化异常类（
```
Anthropic.RateLimitError
```
等）而非字符串匹配错误消息；使用SDK类型（
```
Anthropic.MessageParam
```
、
```
Anthropic.Tool
```
、
```
Anthropic.Message
```
等）而非重新定义等效接口。
不要为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返回——对于“报告”或“文档”类请求，请考虑使用此方式，而非纯标准输出文本。",