Tool Use Concepts / 工具调用核心概念

This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the python/, typescript/, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see agent-design.md.

本文件介绍 Claude API 工具调用的概念基础。特定语言的代码示例请参见 python/、typescript/ 或其他语言文件夹。关于应暴露哪些工具、如何在长时运行代理中管理上下文以及缓存策略的决策经验，请参见 agent-design.md。

User-Defined Tools / 用户自定义工具

Tool Definition Structure / 工具定义结构

Note: When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), jsonschema struct tags (Go), or BaseTool subclasses (Ruby). The raw JSON schema format below is for the manual approach - including PHP's BetaRunnableTool, which wraps a run closure around a hand-written schema - or SDKs without tool runner support.

注意： 使用 Tool Runner（beta）时，工具 schema 会根据你的函数签名（Python）、Zod schema（TypeScript）、注解类（Java）、jsonschema 结构体标签（Go）或 BaseTool 子类（Ruby）自动生成。下方的原始 JSON schema 格式适用于手动方式——包括 PHP 的 BetaRunnableTool（它把运行闭包包在手写的 schema 外面）——以及不支持工具运行器的 SDK。

Each tool requires a name, description, and JSON Schema for its inputs:

每个工具都需要一个名称、一段描述，以及针对其输入的 JSON Schema：

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and state, e.g., San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit"
      }
    },
    "required": ["location"]
  }
}

Best practices for tool definitions:

工具定义的最佳实践：

• Use clear, descriptive names (e.g., get_weather, search_database, send_email)
  使用清晰、具有描述性的名称（例如 get_weather、search_database、send_email）
• Write detailed descriptions - Claude uses these to decide when to use the tool. Be prescriptive about when to call it, not just what it does (e.g. "Call this when the user asks about current prices or recent events"). On recent Opus models, which reach for tools more conservatively, trigger conditions in the description give measurable lift in should-call rate.
  编写详细的描述——Claude 依靠描述来决定何时使用该工具。要明确规定何时调用它，而不仅仅是它做什么（例如"当用户询问当前价格或近期事件时调用此工具"）。在较新的 Opus 模型上（这类模型调用工具更为保守），在描述中写明触发条件可以切实提升"应调用率"。
• Include descriptions for each property
  为每个属性编写描述
• Use enum for parameters with a fixed set of values
  对取值集合固定的参数使用 enum
• Mark truly required parameters in required; make others optional with defaults
  把真正必需的参数标记在 required 中；其余参数设为可选并提供默认值

Eager input streaming (default for streaming requests with client tools) / 输入预流式（对于带客户端工具的流式请求为默认行为）

By default the API buffers and validates each tool-input parameter before it emits any input_json_delta for it. For a small {"location": "Paris"} that is invisible; for a tool that takes a file body, a code block, or a document, nothing arrives until the whole parameter is generated (a 20K-token parameter is a multi-minute silent gap on the stream). Setting eager_input_streaming: true on the tool turns off that buffering for that tool: fragments stream as they are generated, the first fragment arrives immediately, and the fragments are longer. The events are the same (content_block_start -> input_json_delta × N -> content_block_stop) - only the timing and the validation guarantee change.

默认情况下，API 在为某个工具输入参数发出任何 input_json_delta 之前，会对该参数进行缓冲与校验。对于 {"location": "Paris"} 这样的小参数，这一机制不可感知；但对于接收文件内容、代码块或文档的工具参数，在整个参数生成完毕之前不会有任何数据到达（一个 20K token 的参数意味着流上数分钟的静默空窗）。在工具上设置 eager_input_streaming: true 可为该工具关闭这种缓冲：片段随生成即流出，第一个片段立即到达，且片段更长。事件序列不变（content_block_start -> input_json_delta × N -> content_block_stop）——改变的只是时序与校验保证。

Default rule: when a request is streamed (client.messages.stream(...), stream=True, tool runner with streaming on) and defines user-defined tools, set eager_input_streaming: true on each of those tools. Do not set it on non-streaming requests (it is ignored), on server tools (web_search, code_execution, mcp_toolset, etc. - it is not a valid field there), or when the client has no way to handle invalid JSON.

默认规则： 当请求以流式发出（client.messages.stream(...)、stream=True、开启了流式的工具运行器）并定义了用户自定义工具时，为其中每个工具设置 eager_input_streaming: true。不要在非流式请求上设置（会被忽略）、不要在服务端工具上设置（web_search、code_execution、mcp_toolset 等——该字段在那里不合法）、也不要在客户端无法处理非法 JSON 时设置。

【评论】默认的缓冲行为把 JSON 完整性校验放在服务端；开启 eager 模式换取更早的首字节到达，代价是把参数校验责任转移到客户端，文档用大量防御性条款来补偿这一转移。

{
  "name": "write_file",
  "description": "Write text to a file",
  "eager_input_streaming": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {"type": "string"},
      "contents": {"type": "string", "description": "Full file contents"}
    },
    "required": ["path", "contents"]
  }
}

Tool runner: Python @beta_tool(eager_input_streaming=True) passes it through. TypeScript betaZodTool() has no option for it - spread the field onto the returned tool: { ...betaZodTool({ name, description, inputSchema, run }), eager_input_streaming: true }. Go/Java/Ruby/C#/PHP: the field is on the tool param type (EagerInputStreaming, .eagerInputStreaming(true), eager_input_streaming:).

工具运行器：Python 的 @beta_tool(eager_input_streaming=True) 可直接透传该选项。TypeScript 的 betaZodTool() 没有对应选项——把该字段展开附加到返回的工具上：{ ...betaZodTool({ name, description, inputSchema, run }), eager_input_streaming: true }。Go/Java/Ruby/C#/PHP：该字段位于工具参数类型上（EagerInputStreaming、.eagerInputStreaming(true)、eager_input_streaming:）。

What you give up, and how to handle it. Without buffering the API does not validate or coerce the parameter, so the accumulated partial_json can be (a) cut off at max_tokens mid-parameter or (b) invalid JSON the model emitted. Both SDKs accumulate it with a tolerant partial-JSON parser, so malformed input often comes back as a silently truncated object (an unescaped inner quote ends the string early; trailing garbage is dropped) rather than an exception. Do not rely on an exception. Always:

你会失去什么，以及如何应对。 没有缓冲时，API 不再对参数做校验或类型矫正，因此累积的 partial_json 可能出现两种情况：(a) 参数中途因 max_tokens 被截断，或 (b) 模型输出了非法 JSON。两个 SDK 都用宽容的部分 JSON 解析器来累积数据，因此格式错误的输入往往以静默截断的对象形式返回（未转义的内部引号会提前结束字符串；尾部的垃圾数据被丢弃），而不是抛出异常。不要依赖异常。务必做到：

1. Validate the parsed input against the tool's schema before running the tool. The typed runner helpers do this for you and never call run on input that fails: TS betaZodTool (Zod), Python @beta_tool on a function with typed parameters, Java's annotated classes, Go's struct tags, Ruby's BaseTool. The raw JSON-Schema helpers do not validate at runtime - TS betaTool() and PHP's BetaRunnableTool hand run whatever was parsed - so with those, validate inside run (or leave eager_input_streaming off for that tool). In a manual loop, validate yourself (schema.safeParse(block.input) in TS, a pydantic model or explicit type checks in Python) and treat a failure exactly like invalid JSON. A raw SSE / cURL client should JSON.parse the accumulated fragments strictly and then validate.
   在运行工具之前，先对照工具 schema 校验解析出的输入。 带类型的运行器辅助函数会替你完成这一步，且绝不会对校验失败的输入调用 run：TS 的 betaZodTool（Zod）、Python 中带类型参数函数上的 @beta_tool、Java 的注解类、Go 的结构体标签、Ruby 的 BaseTool。原始 JSON-Schema 辅助函数在运行时不做校验——TS 的 betaTool() 和 PHP 的 BetaRunnableTool 会把解析出的任何内容直接交给 run——因此使用它们时，请在 run 内部自行校验（或为该工具关闭 eager_input_streaming）。在手动循环中，请自行校验（TS 用 schema.safeParse(block.input)，Python 用 pydantic 模型或显式类型检查），并把校验失败完全当作非法 JSON 处理。裸 SSE / cURL 客户端应对累积的片段做严格的 JSON.parse，然后再校验。
2. Check stop_reason == "max_tokens" when a tool_use block is present: a truncated input usually parses as a valid partial object, so this is what catches it; retry with a higher max_tokens rather than running the tool. Also stop on stop_reason == "refusal" - a refusal can cut a tool_use off mid-input, so never execute that turn's tools.
   当存在 tool_use 块时检查 stop_reason == "max_tokens"：被截断的输入通常仍能解析为合法的部分对象，所以这一检查才能真正抓住问题；应以更高的 max_tokens 重试，而不是运行该工具。同时在 stop_reason == "refusal" 时停止——拒答可能在输入中途切断 tool_use，因此绝不要执行该轮的工具。
3. Still guard the exceptions the SDKs do raise for JSON they cannot parse at all: Python raises ValueError from the stream iterator (wrap the with client.messages.stream(...) block); TypeScript materializes the input at content_block_stop, so the error rejects whatever you are awaiting at that moment - the for await (const event of stream) loop if you iterate events, otherwise await stream.finalMessage() - so wrap the whole consumption of the stream (iteration and final read together), as the Python guidance wraps the whole with block; the tool runners surface the same error from their iteration (wrap the loop). Catch only that error - rethrow the SDK's typed API errors (RateLimitError, AuthenticationError, ...) so an auth or rate-limit failure is not mistaken for bad JSON - and cap retries.
   对于 SDK 在遇到完全无法解析的 JSON 时仍会抛出的异常，也要加以防护：Python 会从流迭代器抛出 ValueError（把 with client.messages.stream(...) 块包进异常处理）；TypeScript 在 content_block_stop 时实例化输入，因此该错误会拒绝（reject）你当时正在 await 的东西——如果你在迭代事件，就是 for await (const event of stream) 循环，否则就是 await stream.finalMessage()——所以要包住流的整个消费过程（迭代与最终读取一起包住），正如 Python 的建议是包住整个 with 块；工具运行器会从其迭代中抛出同样的错误（包住循环）。只捕获这一个错误——SDK 的带类型 API 错误（RateLimitError、AuthenticationError 等）要重新抛出，以免认证或限流失败被误判为非法 JSON——并限制重试次数。
4. When validation fails and you still hold the tool_use block (manual loop after finalMessage() / get_final_message(), raw SSE), do not run the tool; return the raw text to Claude as an error result so it can retry:
   当校验失败而你仍持有 tool_use 块时（在 finalMessage() / get_final_message() 之后的手动循环、裸 SSE），不要运行工具；把原始文本作为错误结果返回给 Claude，让它重试：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01...",
  "is_error": true,
  "content": "{\"INVALID_JSON\": \"<the unparseable input you received>\"}"
}

When the SDK raised before the block completed (Python stream, either tool runner), there is no tool_use_id to answer, so re-issue the request instead.

如果 SDK 在块完成之前就抛出了异常（Python 流、任一工具运行器），此时没有可应答的 tool_use_id，因此应改为重新发起请求。

Build that wrapper with the JSON library (not string concatenation) so quotes in the bad input are escaped. With the buffered default the server would have delivered the same broken parameter as a single string value instead; eager mode moves that failure to the client, it does not create it.

请使用 JSON 库（而不是字符串拼接）来构造该包装对象，这样坏输入中的引号才能被正确转义。在默认的缓冲模式下，服务端本会把同样损坏的参数作为单个字符串值传递过来；eager 模式只是把这一失败点移到了客户端，并不是它制造了失败。

Availability: Claude API, Claude Platform on AWS, Vertex AI, and Microsoft Foundry for all current models (shared/platform-availability.md). On Amazon Bedrock only the newer serving stack accepts the field (Opus 4.7 / 4.8 / 5, Fable 5, Sonnet 4.6 / 5); older Bedrock deployments (Opus 4.5 / 4.6, Sonnet 4.0 / 4.5, Haiku 4.5) return 400 on the unknown field - drop it there. shared/platform-availability.md is the source of truth for this list. Any proxy or gateway in front of the API may likewise reject it; if the user's code points at a custom base_url, leave it off unless they confirm the upstream is the real API.

可用性： Claude API、AWS 上的 Claude Platform、Vertex AI 以及 Microsoft Foundry 上的所有当前模型均支持（见 shared/platform-availability.md）。在 Amazon Bedrock 上，只有较新的服务栈接受该字段（Opus 4.7 / 4.8 / 5、Fable 5、Sonnet 4.6 / 5）；较旧的 Bedrock 部署（Opus 4.5 / 4.6、Sonnet 4.0 / 4.5、Haiku 4.5）会对未知字段返回 400——在这些部署上请去掉该字段。shared/platform-availability.md 是此列表的最终权威来源。位于 API 前面的任何代理或网关同样可能拒绝该字段；如果用户的代码指向自定义 base_url，除非其确认上游是真正的 API，否则不要启用该字段。

Tool Choice Options / 工具选择选项

Control when Claude uses tools:

控制 Claude 何时使用工具：

Any tool_choice value can also include "disable_parallel_tool_use": true to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.

任何 tool_choice 取值都可以附带 "disable_parallel_tool_use": true，迫使 Claude 在每次响应中最多使用一个工具。默认情况下，Claude 可以在单个响应中请求多个工具调用。

Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, and Claude Sonnet 5.5 reject forced tool use: {"type": "any"} and {"type": "tool", "name": ...} return a 400 there (tool_choice: type "tool" and "any" are not supported for this model. - on count_tokens and Batches too). It is a model-specific restriction (Claude Fable 5 and Claude Opus 5 accept them). Because auto does not guarantee a call, check that one was made and retry if it wasn't. Use {"type": "auto"} and state the expectation in the prompt ("Use the get_weather tool to answer") - strict: true on the tool keeps the schema-valid-arguments guarantee any gave you - or structured outputs (output_config.format) when the forced call only existed to extract JSON. auto and none are unaffected; disable_parallel_tool_use with auto still means at most one call (the "exactly one" combination with any/tool is gone). Combining tool_choice any with strict: true applies only on models that support forced tool use. See shared/model-migration.md -> Migrating to Claude Fable 5.1 from Claude Fable 5.

Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5 与 Claude Sonnet 5.5 拒绝强制工具调用： 在这些模型上，{"type": "any"} 与 {"type": "tool", "name": ...} 会返回 400（错误信息为 tool_choice: type "tool" and "any" are not supported for this model.——count_tokens 和 Batches 上同样如此）。这是模型级别的限制（Claude Fable 5 与 Claude Opus 5 仍然接受它们）。由于 auto 不保证一定发生调用，请检查是否确实发生了调用，没有则重试。使用 {"type": "auto"} 并在提示词中说明预期（"Use the get_weather tool to answer"）——工具上的 strict: true 可以保留 any 原本给你的"参数符合 schema"保证——如果强制调用只是为了提取 JSON，也可以改用结构化输出（output_config.format）。auto 与 none 不受影响；disable_parallel_tool_use 配合 auto 仍表示最多一次调用（与 any/tool 组合出的"恰好一次"已不存在）。tool_choice any 与 strict: true 的组合只适用于支持强制工具调用的模型。参见 shared/model-migration.md -> Migrating to Claude Fable 5.1 from Claude Fable 5。

【评论】新一代模型取消服务端强制工具调用、改由提示词表达调用意图，是"硬约束"向"模型自主性"的取舍变化；依赖 any 保证结构化参数的存量代码迁移时需要自行补上校验。

Tool Runner vs Manual Loop / 工具运行器与手动循环

Tool Runner (Recommended): The SDK's tool runner handles the agentic loop automatically - it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, PHP, and C# SDKs (beta). The Python SDK also provides MCP conversion helpers (anthropic.lib.tools.mcp) to convert MCP tools, prompts, and resources for use with the tool runner - see python/claude-api/tool-use.md for details. Default to the tool runner for any custom-tool agent.

Tool Runner（推荐）： SDK 的工具运行器会自动处理代理式循环——它调用 API、检测工具使用请求、执行你的工具函数、把结果回传给 Claude，并不断重复直到 Claude 停止调用工具。可用于 Python、TypeScript、Java、Go、Ruby、PHP 和 C# SDK（beta）。Python SDK 还提供 MCP 转换辅助工具（anthropic.lib.tools.mcp），可将 MCP 工具、提示词和资源转换为工具运行器可用的形式——详见 python/claude-api/tool-use.md。对于任何自定义工具代理，默认使用工具运行器。

The tool runner is not a black box - "I need control" is rarely a reason to drop to the manual loop. Each iteration yields the assistant message before the tools run and lets you intervene, so most "fine-grained control" needs are covered without hand-writing the loop:

工具运行器并不是黑盒——"我需要控制权"很少是退回手动循环的理由。 每次迭代都会在工具运行之前产出助手消息并允许你介入，因此大多数"细粒度控制"需求无需手写循环即可满足：

• Human-in-the-loop approval / gating - gate in the tool's run function (return a "user declined" result instead of executing), or inspect the tool call in the yielded message and override the pending request with set_messages_params() / setMessagesParams() / append_messages() / pushMessages() to allow or deny before the tool executes. The runner runs your function automatically only if you don't intervene.
  人工审批 / 门控——在工具的 run 函数内做门控（返回"用户已拒绝"的结果而不执行），或检查产出消息中的工具调用，并用 set_messages_params() / setMessagesParams() / append_messages() / pushMessages() 在工具执行之前覆盖待处理的请求以允许或拒绝。只有你不干预时，运行器才会自动执行你的函数。
• Error interception - inspect the tool result before it returns to Claude (generate_tool_call_response() / generateToolResponse()); stop early or handle it yourself.
  错误拦截——在工具结果返回给 Claude 之前进行检查（generate_tool_call_response() / generateToolResponse()）；可提前停止或自行处理。
• Result modification - mutate the tool result before it goes back (e.g. add cache_control for prompt caching, or transform the output).
  结果修改——在结果回传前进行修改（例如为提示词缓存添加 cache_control，或对输出做变换）。
• Per-turn retries / param changes - e.g. bump max_tokens and re-run a truncated turn; bound the whole loop with max_iterations.
  按轮重试 / 参数调整——例如调大 max_tokens 后重跑被截断的一轮；用 max_iterations 限制整个循环。
• Streaming and automatic compaction are both supported.
  流式与自动压缩均受支持。

These hooks are SDK helper features, not separate API parameters - for the exact method names and worked examples, WebFetch the per-language SDK repo listed in shared/live-sources.md -> Claude API SDK Repositories (the tool-runner helpers live in each repo's tools.md / helpers.md). The bundled python/claude-api/tool-use.md and typescript/claude-api/tool-use.md show the basic tool-runner setup.

这些钩子是 SDK 辅助功能，而非独立的 API 参数——确切的方法名与完整示例请通过 WebFetch 获取 shared/live-sources.md -> Claude API SDK Repositories 中列出的各语言 SDK 仓库（工具运行器辅助函数位于各仓库的 tools.md / helpers.md）。随附的 python/claude-api/tool-use.md 与 typescript/claude-api/tool-use.md 展示了工具运行器的基本配置。

Don't drop to a manual loop because of these misconceptions:

不要因为以下误解而退回手动循环：

• The tool runner does not require Zod/Pydantic - betaTool() (TS) and @beta_tool (Python) accept raw JSON Schema; other SDKs use plain structs/maps/classes.
  工具运行器并不要求 Zod/Pydantic——betaTool()（TS）与 @beta_tool（Python）接受原始 JSON Schema；其他 SDK 使用普通的结构体/映射/类。
• The runner makes detecting the final turn easier, not harder - iteration ends when Claude stops calling tools, and the last yielded message is the final response. Most SDKs also offer a one-shot variant (runner.until_done() / runner.runUntilDone() / RunToCompletion()).
  运行器让检测最终一轮变得更容易而非更难——当 Claude 停止调用工具时迭代结束，最后产出的消息就是最终响应。多数 SDK 还提供一次性变体（runner.until_done() / runner.runUntilDone() / RunToCompletion()）。
• Confirmation/approval gates work with the runner (see Security below).
  确认/审批门控与运行器兼容（见下文安全说明）。

Manual Agentic Loop: Reach for this only when you want to own the entire loop - you need control the runner does not expose (e.g., a custom transport, request shapes the SDK cannot build, per-token streaming on SDKs whose runner does not support it), you'd rather not take the beta dependency, or your control flow doesn't fit the runner's per-turn hooks (e.g. interleaving unrelated work mid-loop). Approval gates, logging, interception, result modification, and conditional execution do not require it - the tool runner covers those (above). Loop until stop_reason == "end_turn", always append the full response.content to preserve tool_use blocks, and ensure each tool_result includes the matching tool_use_id.

手动代理循环： 只有当你想完全拥有整个循环时才考虑它——你需要运行器未暴露的控制能力（例如自定义传输层、SDK 无法构造的请求形态、在不支持流式的 SDK 运行器上做逐 token 流式输出），你不想引入 beta 依赖，或者你的控制流程无法套入运行器的按轮钩子（例如在循环中途插入无关工作）。审批门控、日志、拦截、结果修改与条件执行都不需要手动循环——工具运行器已覆盖这些（见上）。循环直到 stop_reason == "end_turn"，始终完整追加 response.content 以保留 tool_use 块，并确保每个 tool_result 都带有匹配的 tool_use_id。

Stop reasons for server-side tools: When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have stop_reason: "pause_turn". To continue, re-send the user message and assistant response and make another API request - the server will resume where it left off. Do NOT add an extra user message like "Continue." - the API detects the trailing server_tool_use block and knows to resume automatically.

服务端工具的停止原因： 使用服务端工具（代码执行、网页搜索等）时，API 会在服务端运行一个采样循环。如果该循环达到默认的 10 次迭代上限，响应将带有 stop_reason: "pause_turn"。要继续，重新发送用户消息和助手响应并再次发起 API 请求——服务端会从中断处继续。不要添加"Continue."之类的额外用户消息——API 会检测到尾部的 server_tool_use 块并自动知道要继续。

# Handle pause_turn in your agentic loop
if response.stop_reason == "pause_turn":
    messages = [
        {"role": "user", "content": user_query},
        {"role": "assistant", "content": response.content},
    ]
    # Make another API request - server resumes automatically
    response = client.messages.create(
        model="claude-opus-5-5", messages=messages, tools=tools
    )

Note: the SDK tool runners do not auto-resume pause_turn (as of @anthropic-ai/sdk 0.110.0 / anthropic 0.116.0) - a paused turn ends the runner and is returned as the final message, with no error. In TypeScript you can resume inside the iteration body (push the paused assistant turn back onto the runner); in Python the runner cannot be resumed mid-loop - restart a new runner with the paused turn appended, or handle pause_turn in a manual loop. See each language's tool-use.md for the pattern.

注意： SDK 的工具运行器不会自动恢复 pause_turn（截至 @anthropic-ai/sdk 0.110.0 / anthropic 0.116.0）——暂停的一轮会结束运行器并作为最终消息返回，不报错误。在 TypeScript 中，你可以在迭代体内恢复（把暂停的助手轮推回运行器）；在 Python 中，运行器无法在循环中途恢复——应把暂停的轮次追加后重启一个新的运行器，或在手动循环中处理 pause_turn。具体模式见各语言的 tool-use.md。

Set a max_continuations limit (e.g., 5) to prevent infinite loops. For the full guide, see: https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

设置 max_continuations 上限（例如 5）以防止无限循环。完整指南见：https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

Security: The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs and gate destructive operations behind human approval. Both the tool runner and the manual loop support this - with the tool runner, gate inside the tool's run function (prompt the user and return a "user declined" result instead of executing), or inspect the tool call in each yielded message and take over message history with set_messages_params() / setMessagesParams() to allow or deny before the tool runs (it executes your function automatically only if you don't intervene); with the manual loop you gate inline before calling the function.

安全： 只要 Claude 发出请求，工具运行器就会自动执行你的工具函数。对于有副作用的工具（发送邮件、修改数据库、金融交易），请校验输入，并把破坏性操作置于人工审批之后。工具运行器与手动循环都支持这一点——使用工具运行器时，在工具的 run 函数内做门控（提示用户并返回"用户已拒绝"的结果而不执行），或检查每条产出消息中的工具调用，并用 set_messages_params() / setMessagesParams() 接管消息历史，在工具运行之前允许或拒绝（只有你不干预时它才会自动执行你的函数）；使用手动循环时，在调用函数前内联做门控。

Handling Tool Results / 处理工具结果

When Claude uses a tool, the response contains a tool_use block. You must:

Claude 使用工具时，响应中会包含一个 tool_use 块。你必须：

1. Execute the tool with the provided input
   用提供的输入执行该工具
2. Send the result back in a tool_result message
   以 tool_result 消息把结果回传
3. Continue the conversation
   继续对话

Error handling in tool results: When a tool execution fails, set "is_error": true and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.

工具结果中的错误处理： 当工具执行失败时，设置 "is_error": true 并提供有信息量的错误消息。Claude 通常会确认该错误，然后尝试其他方法或请求澄清。

Multiple tool calls: Claude can request multiple tools in a single response. Handle them all before continuing - send all results back in a single user message.

多个工具调用： Claude 可以在单个响应中请求多个工具。请先处理完所有调用再继续——在单条 user 消息中回传全部结果。

Server-Side Tools: Code Execution / 服务端工具：代码执行

The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure - you don't execute anything client-side. Just include the tool definition and Claude handles the rest.

代码执行工具让 Claude 能在安全、沙箱化的容器中运行代码。与用户自定义工具不同，服务端工具运行在 Anthropic 的基础设施上——你不需要在客户端执行任何东西。只需包含工具定义，剩下的由 Claude 处理。

Key Facts / 关键事实

• Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
  运行在隔离容器中（1 个 CPU、5 GiB 内存、5 GiB 磁盘）
• No internet access (fully sandboxed)
  无互联网访问（完全沙箱化）
• Python 3.11 with data science libraries pre-installed
  预装数据科学库的 Python 3.11
• Containers persist for 30 days and can be reused across requests
  容器保留 30 天，可跨请求复用
• Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
  与网页搜索/网页抓取工具一起使用时免费；否则每个组织每月 1,550 免费小时之后按 $0.05/小时计费

Tool Definition / 工具定义

The tool requires no schema - just declare it in the tools array:

该工具不需要 schema——只需在 tools 数组中声明：

{
  "type": "code_execution_20260120",
  "name": "code_execution"
}

Claude automatically gains access to bash_code_execution (run shell commands) and text_editor_code_execution (create/view/edit files).

Claude 会自动获得 bash_code_execution（运行 shell 命令）和 text_editor_code_execution（创建/查看/编辑文件）的访问权限。

Pre-installed Python Libraries / 预装 Python 库

• Data science: pandas, numpy, scipy, scikit-learn, statsmodels
  数据科学：pandas、numpy、scipy、scikit-learn、statsmodels
• Visualization: matplotlib, seaborn
  可视化：matplotlib、seaborn
• File processing: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
  文件处理：openpyxl、xlsxwriter、pillow、pypdf、pdfplumber、python-docx、python-pptx
• Math: sympy, mpmath
  数学：sympy、mpmath
• Utilities: tqdm, python-dateutil, pytz, sqlite3
  工具库：tqdm、python-dateutil、pytz、sqlite3

Additional packages can be installed at runtime via pip install.

其他包可在运行时通过 pip install 安装。

Supported File Types for Upload / 支持上传的文件类型

Container Reuse / 容器复用

Reuse containers across requests to maintain state (files, installed packages, variables). Extract the container_id from the first response and pass it to subsequent requests.

跨请求复用容器以保持状态（文件、已安装的包、变量）。从第一个响应中提取 container_id，并在后续请求中传入。

Response Structure / 响应结构

The response contains interleaved text and tool result blocks:

响应中交错包含文本和工具结果块：

• text - Claude's explanation
  text——Claude 的解释
• server_tool_use - What Claude is doing
  server_tool_use——Claude 正在做什么
• bash_code_execution_tool_result - Code execution output (check return_code for success/failure)
  bash_code_execution_tool_result——代码执行输出（检查 return_code 判断成功/失败）
• text_editor_code_execution_tool_result - File operation results
  text_editor_code_execution_tool_result——文件操作结果

Security: Always sanitize filenames with os.path.basename() / path.basename() before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.

安全： 在把下载的文件写入磁盘之前，务必用 os.path.basename() / path.basename() 清理文件名，以防路径遍历攻击。请把文件写入专用的输出目录。

Server-Side Tools: Web Search and Web Fetch / 服务端工具：网页搜索与网页抓取

Web search and web fetch let Claude search the web and retrieve page content. They run server-side - just include the tool definitions and Claude handles queries, fetching, and result processing automatically.

网页搜索与网页抓取让 Claude 能搜索网络并获取页面内容。它们在服务端运行——只需包含工具定义，Claude 会自动处理查询、抓取和结果处理。

Tool Definitions / 工具定义

[
  { "type": "web_search_20260209", "name": "web_search" },
  { "type": "web_fetch_20260209", "name": "web_fetch" }
]

Dynamic Filtering (Claude Opus 5.5 / Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Claude Sonnet 5.5 / Sonnet 5 / Sonnet 4.6) / 动态过滤（Claude Opus 5.5 / Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Claude Sonnet 5.5 / Sonnet 5 / Sonnet 4.6）

The web_search_20260209 and web_fetch_20260209 versions support dynamic filtering - Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the code_execution tool or pass any beta header.

web_search_20260209 与 web_fetch_20260209 版本支持动态过滤——Claude 会编写并执行代码，在搜索结果进入上下文窗口之前对其进行过滤，从而提升准确性与 token 效率。动态过滤内建于这些工具版本并自动激活；你无需单独声明 code_execution 工具，也无需传递任何 beta 头。

{
  "tools": [
    { "type": "web_search_20260209", "name": "web_search" },
    { "type": "web_fetch_20260209", "name": "web_fetch" }
  ]
}

Without dynamic filtering, the previous web_search_20250305 version is also available.

如不需要动态过滤，也可使用先前的 web_search_20250305 版本。

Note: Only include the standalone code_execution tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside _20260209 web tools creates a second execution environment that can confuse the model.

注意： 只有当你的应用出于自身目的（数据分析、文件处理、可视化）需要代码执行、且独立于网页搜索时，才应包含独立的 code_execution 工具。把它与 _20260209 网页工具一同包含会创建第二个执行环境，可能使模型产生混淆。

Server-Side Tools: Programmatic Tool Calling / 服务端工具：程序化工具调用

With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens - most of that intermediate data is never needed again.

在标准工具使用方式下，每次工具调用都是一次往返：Claude 发起调用，结果进入 Claude 的上下文，Claude 推理，然后再调用下一个工具。链式调用会不断累积延迟和 token——其中大部分中间数据之后再也不会被用到。

Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.

程序化工具调用让 Claude 能把这些调用组合成一段脚本。脚本在代码执行容器中运行；当脚本调用某个工具时，容器暂停，调用被执行，结果返回给正在运行的代码（而不是进入 Claude 的上下文）。脚本用普通控制流处理结果。只有最终输出会返回给 Claude。当需要链式调用许多工具、或中间结果很大且应在进入上下文窗口前被过滤时，使用该功能。

For full documentation, use WebFetch:

完整文档请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
  URL：https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

Server-Side Tools: Tool Search / 服务端工具：工具搜索

The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in - this preserves the prompt cache (see agent-design.md §Caching for Agents).

工具搜索工具让 Claude 能从大型工具库中动态发现工具，而不必把所有定义都载入上下文窗口。当你有很多工具但任何给定请求只涉及其中少数几个时使用它。被发现的工具 schema 是追加到请求中，而不是替换——这能保持提示词缓存有效（见 agent-design.md §Caching for Agents）。

For full documentation, use WebFetch:

完整文档请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
  URL：https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

Mid-conversation tool changes (Beta) / 对话中途的工具变更（Beta）

Beta header mid-conversation-tool-changes-2026-07-01; Claude Opus 5, Claude Opus 5.5, Claude Opus 4.8, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5, Claude Mythos 5.1, and Claude Sonnet 5.5 - not Claude Sonnet 5; not available on Microsoft Foundry (availability: shared/platform-availability.md). Normally tools is fixed for a conversation's lifetime - editing it changes the very front of the prompt prefix and invalidates the entire cache (see prompt-caching.md § Invalidation hierarchy). This feature lets you add and remove tools between turns while the cached prefix survives.

Beta 头 mid-conversation-tool-changes-2026-07-01；支持 Claude Opus 5、Claude Opus 5.5、Claude Opus 4.8、Claude Fable 5、Claude Fable 5.1、Claude Mythos 5、Claude Mythos 5.1 与 Claude Sonnet 5.5——不支持 Claude Sonnet 5；Microsoft Foundry 上不可用（可用性见 shared/platform-availability.md）。 通常 tools 在对话生命周期内是固定的——修改它会改变提示词前缀的最前端，使整个缓存失效（见 prompt-caching.md § Invalidation hierarchy）。该功能让你能在轮次之间添加和移除工具，同时缓存的前缀得以保留。

Both operations are content blocks on a {"role": "system", ...} message appended to messages[], and both reference a tool by name via a tool_reference:

两种操作都是追加到 messages[] 的 {"role": "system", ...} 消息上的内容块，并且都通过 tool_reference 按名称引用工具：

# Removal - must sit immediately before an assistant message, or last in messages.
{"role": "system", "content": [
    {"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}},
]}

# Addition - surfaces a tool declared up front with defer_loading.
{"role": "system", "content": [
    {"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}},
]}

A tool you plan to add must already be declared in tools[] with "defer_loading": True. Deferred tools are known to the request but not loaded into the model's context until a tool_addition surfaces them:

计划添加的工具必须已以 "defer_loading": True 声明在 tools[] 中。 延迟加载的工具对请求而言是已知的，但在 tool_addition 使其显现之前不会载入模型的上下文：

tools = [
    {"name": "get_weather", "description": "Get weather",
     "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}},
    {"name": "get_forecast", "description": "Get 5-day forecast",
     "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}},
     "defer_loading": True},
]

To change a tool's definition, do it across two requests: send a tool_removal for the old definition on the first, then carry the conversation forward with the updated entry in tools[] on the next.

要修改某个工具的定义，需跨两个请求进行：第一个请求发送针对旧定义的 tool_removal，下一个请求在 tools[] 中携带更新后的条目并延续对话。

Warning: Earlier previews used a different beta header and different block shapes; both are deprecated. Use mid-conversation-tool-changes-2026-07-01 with tool_addition / tool_removal / tool_reference.

警告：更早的预览版使用了不同的 beta 头和不同的块结构；两者均已弃用。请使用 mid-conversation-tool-changes-2026-07-01 配合 tool_addition / tool_removal / tool_reference。

SDK typings lag these blocks - pass them as plain dicts in Python, or add a @ts-expect-error in TypeScript.

SDK 的类型定义滞后于这些块——在 Python 中以普通 dict 传入，或在 TypeScript 中加上 @ts-expect-error。

Choosing between this and tool search: tool search is for discovery - Claude finds what it needs from a large library on its own. Mid-conversation tool changes are for control - your application decides the tool set has changed (a mode switch, a resource that became available, a capability you want to revoke) and says so explicitly.

在本功能与工具搜索之间做选择： 工具搜索面向发现——由 Claude 自己从大型库中找到所需工具。对话中途的工具变更面向控制——由你的应用判定工具集发生了变化（模式切换、某个资源变为可用、要撤销某项能力）并明确声明。

Agent Skills (Messages API) / 代理技能（Messages API）

Agent Skills package task-specific instructions and files that Claude loads when relevant (e.g., the Anthropic pre-built pptx, xlsx, pdf, docx skills). On the Messages API, skills are enabled via the container parameter alongside the code-execution tool - this is not the Managed Agents surface and does not use client.beta.agents / sessions / environments. Availability: see shared/platform-availability.md.

代理技能（Agent Skills）打包了任务相关的指令与文件，Claude 会在相关时加载它们（例如 Anthropic 预构建的 pptx、xlsx、pdf、docx 技能）。在 Messages API 上，技能通过 container 参数配合代码执行工具启用——这不是 Managed Agents 接口，也不使用 client.beta.agents / sessions / environments。可用性见 shared/platform-availability.md。

Required on each request:

每个请求都需要：

1. client.beta.messages.create(...) with the code-execution-2025-08-25 beta flag (Skills is out of beta - no skills-2025-10-02 header needed).
   在 client.beta.messages.create(...) 中带上 code-execution-2025-08-25 beta 标志（Skills 已脱离 beta——无需 skills-2025-10-02 头）。
2. container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]} - the skills list selects which skills are available inside the execution container.
   container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]}——技能列表选定执行容器内可用的技能。
3. tools=[{"type": "code_execution_20260521", "name": "code_execution"}] - skills execute via code execution in the container.
   tools=[{"type": "code_execution_20260521", "name": "code_execution"}]——技能通过容器内的代码执行来运行。

response = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=16000,
    betas=["code-execution-2025-08-25"],
    container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]},
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Create a 3-slide presentation on X"}],
)

Generated files (.pptx, .xlsx, ...) are written inside the container; the response carries a file ID for each. Download by passing that ID to the Files API (client.files.download(file_id) / GET /v1/files/{id}/content).

生成的文件（.pptx、.xlsx 等）写在容器内；响应中为每个文件携带一个文件 ID。把该 ID 传给 Files API 即可下载（client.files.download(file_id) / GET /v1/files/{id}/content）。

List available skills via GET /v1/skills (no beta header).

通过 GET /v1/skills 列出可用技能（无需 beta 头）。

MCP Connector (Beta) / MCP 连接器（Beta）

The MCP connector lets Claude call tools hosted on a remote MCP server directly from the Messages API - Anthropic makes the MCP connection server-side. Requires beta flag mcp-client-2025-11-20 on client.beta.messages.create(...). Availability: see shared/platform-availability.md.

MCP 连接器让 Claude 能直接从 Messages API 调用托管在远程 MCP 服务器上的工具——由 Anthropic 在服务端建立 MCP 连接。需要在 client.beta.messages.create(...) 上使用 beta 标志 mcp-client-2025-11-20。可用性见 shared/platform-availability.md。

Two parameters are required together:

两个参数必须同时提供：

• mcp_servers - array of server connection definitions: [{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]
mcp_servers——服务器连接定义的数组：[{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]
• tools - must include an mcp_toolset entry that references the server by name: [{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]
tools——必须包含一个按名称引用服务器的 mcp_toolset 条目：[{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]

The mcp_server_name in the toolset must match a name in mcp_servers. Omitting the mcp_toolset entry is rejected as a validation error - every server in mcp_servers must be referenced by exactly one toolset.

工具集中的 mcp_server_name 必须与 mcp_servers 中的某个 name 匹配。省略 mcp_toolset 条目会被作为校验错误拒绝——mcp_servers 中的每个服务器都必须被恰好一个工具集引用。

client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url", "url": "https://example/sse", "name": "example-mcp"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=[...],
)

Go uses the typed constant anthropic.AnthropicBetaMCPClient2025_11_20; the older ...2025_04_04 constant is deprecated.

Go 使用带类型的常量 anthropic.AnthropicBetaMCPClient2025_11_20；较旧的 ...2025_04_04 常量已弃用。

Optional toolset fields: default_config (defaults for all tools, e.g. {"enabled": false} for allowlist mode) and configs (per-tool overrides keyed by tool name).

工具集的可选字段：default_config（所有工具的默认配置，例如白名单模式下用 {"enabled": false}）和 configs（以工具名为键的逐工具覆盖配置）。

Tool Use Examples / 工具使用示例

You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.

你可以在工具定义中直接提供示例工具调用，以演示使用模式并减少参数错误。这有助于 Claude 理解如何正确格式化工具输入，对具有复杂 schema 的工具尤其如此。

For full documentation, use WebFetch:

完整文档请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use
  URL：https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use

Client-Side Tools: Computer Use / 客户端工具：计算机使用

Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It is a client-side tool - your application provides the environment and executes the actions Claude requests; Anthropic processes the screenshots and action requests in real time but does not host the environment or retain the data.

计算机使用让 Claude 能与桌面环境交互（截图、鼠标、键盘）。它是客户端工具——由你的应用提供环境并执行 Claude 请求的操作；Anthropic 实时处理截图和操作请求，但不托管环境，也不保留数据。

Two request shapes. The current one is the computer toolset - GA on the Claude API and Google Cloud, no beta header: one tools entry {"type": "computer_toolset_20260801"} with no name and no display dimensions, plus an optional configs map to turn member tools off ({"zoom": {"enabled": false}}; all 17 members, zoom included, are on by default). Claude's calls are tool_use blocks whose name is the member (screenshot, left_click, type, zoom, ...) carrying "toolset_name": "computer", often several per turn; return one tool_result per call in the next user message, each echoing "toolset_name": "computer" (only screenshot / zoom need an image; OK suffices for the rest). Coordinates are in the pixel space of the full screenshots you return, also after a zoom, and screenshots must already fit the model's image limits. The earlier computer_20251124 tool (beta computer-use-2025-11-24, a name: "computer" entry with display_width_px / display_height_px, actions in input.action) keeps working on the models and platforms that offer it - Bedrock, Claude Platform on AWS, and Foundry offer only the earlier beta versions today - and the two forms can't share a request. Claude Opus 5.5 accepts only the toolset: computer_20251124 returns a 400 there (shared/model-migration.md -> Migrating to Claude Opus 5.5 -> Breaking change 4 has the request and agent-loop changes; test them on Claude Opus 5, which accepts both). Claude Sonnet 5.5 accepts only the toolset on the Claude API and Google Cloud (computer_20251124 returns a 400 there; Amazon Bedrock still accepts it, and no platform accepts computer_20250124) - see shared/model-migration.md -> Migrating to Claude Sonnet 5.5 -> Breaking change 4.

两种请求形态。 当前形态是计算机工具集（computer toolset）——在 Claude API 和 Google Cloud 上已正式发布（GA），无需 beta 头：一个 tools 条目 {"type": "computer_toolset_20260801"}，不带 name、不带显示尺寸，另加一个可选的 configs 映射用于关闭成员工具（{"zoom": {"enabled": false}}；全部 17 个成员——包括 zoom——默认开启）。Claude 的调用是 tool_use 块，其 name 为成员工具名（screenshot、left_click、type、zoom 等）并携带 "toolset_name": "computer"，一轮中常有多个；在下一个 user 消息中为每个调用返回一个 tool_result，每个都要回显 "toolset_name": "computer"（只有 screenshot / zoom 需要附图像；其余返回 OK 即可）。坐标处于你返回的完整截图的像素空间内（zoom 之后也是如此），且截图本身必须已符合模型的图像限制。较早的 computer_20251124 工具（beta computer-use-2025-11-24，一个 name: "computer" 条目，带 display_width_px / display_height_px，操作位于 input.action）在提供它的模型和平台上仍可继续使用——Bedrock、AWS 上的 Claude Platform 与 Foundry 目前只提供较早的 beta 版本——而且两种形态不能出现在同一请求中。Claude Opus 5.5 只接受工具集：在该模型上 computer_20251124 返回 400（请求与代理循环的改动见 shared/model-migration.md -> Migrating to Claude Opus 5.5 -> Breaking change 4；可在同时接受两种形态的 Claude Opus 5 上测试）。在 Claude API 和 Google Cloud 上，Claude Sonnet 5.5 只接受工具集（该处 computer_20251124 返回 400；Amazon Bedrock 仍接受它，且没有任何平台接受 computer_20250124）——见 shared/model-migration.md -> Migrating to Claude Sonnet 5.5 -> Breaking change 4。

For full documentation (member reference, batch actions, scaling, the computer_20251124 migration steps), use WebFetch:

完整文档（成员参考、批量操作、缩放、computer_20251124 迁移步骤）请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview
  URL：https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview

Context Editing / 上下文编辑

Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes - the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure.

上下文编辑会在长时运行的代理不断累积轮次时，从对话记录中清除过期的工具结果和思考块。与压缩（compaction，做摘要）不同，上下文编辑是修剪——被清除的内容直接移除，不做替换。当旧的工具输出不再相关、而你想保持对话记录精简又不丢失对话结构时使用它。

Beta. Use client.beta.messages.* with beta context-management-2025-06-27. Configure via context_management.edits with a strategy type of clear_tool_uses_20250919 (clear old tool results; optional clear_tool_inputs: true also clears the tool_use params) or clear_thinking_20251015 (clear thinking blocks). These are not the compaction types - compact_20260112 with beta compact-2026-01-12 is the separate compaction feature.

Beta。 使用 client.beta.messages.* 并带上 beta context-management-2025-06-27。通过 context_management.edits 配置，策略类型为 clear_tool_uses_20250919（清除旧工具结果；可选的 clear_tool_inputs: true 还会清除 tool_use 参数）或 clear_thinking_20251015（清除思考块）。这些不是压缩类型——配合 beta compact-2026-01-12 的 compact_20260112 才是独立的压缩功能。

For full documentation, use WebFetch:

完整文档请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/build-with-claude/context-editing
  URL：https://platform.claude.com/docs/en/build-with-claude/context-editing

Server-Side Tools: Advisor (Beta) / 服务端工具：Advisor（Beta）

The advisor tool pairs a faster, lower-cost executor model (the top-level model on the request) with a higher-intelligence advisor model (the model field inside the tool definition) that provides strategic guidance mid-generation. The executor does most of the token generation; the advisor is consulted for planning. Availability: see shared/platform-availability.md.

Advisor 工具把一个更快、更便宜的执行器模型（请求顶层的 model）与一个智能更高的**顾问（advisor）**模型（工具定义内的 model 字段）配对，后者在生成过程中提供战略性指导。执行器承担大部分 token 生成；顾问用于规划咨询。可用性见 shared/platform-availability.md。

Tool Definition / 工具定义

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-8"
}

Optional fields on the tool definition:

工具定义上的可选字段：

• max_uses - cap on advisor consultations per request. Exceeding it makes the advisor_tool_result block's content the error object {"type": "advisor_tool_result_error", "error_code": "max_uses_exceeded"} - the third member of the content union in the payload-shape table below.
  max_uses——每次请求顾问咨询次数的上限。超出后，advisor_tool_result 块的 content 会变为错误对象 {"type": "advisor_tool_result_error", "error_code": "max_uses_exceeded"}——即下方载荷形态表中 content 联合类型的第三个成员。
• max_tokens - bounds the advisor's total output (thinking + text) per call. At the cap the result block carries stop_reason: "max_tokens" and a truncation note is appended to the advice the executor sees; the server also emits a remaining-tokens budget block in the advisor's prompt so it self-shapes toward the cap.
  max_tokens——限制顾问每次调用的总输出（思考 + 文本）。达到上限时，结果块带有 stop_reason: "max_tokens"，并在执行器看到的建议后附加截断说明；服务端还会在顾问的提示词中发出一个剩余 token 预算块，使其自觉向该上限靠拢。
• caching - cache-control for the advisor's own prompt, same shape as a cache breakpoint: "caching": {"type": "ephemeral", "ttl": "5m"} (ttl is "5m" or "1h", default "5m"). Each call writes a cache entry at that TTL so later calls in the conversation read the stable prefix. Omitted = advisor prompt not cached.
  caching——顾问自身提示词的缓存控制，形状与缓存断点相同："caching": {"type": "ephemeral", "ttl": "5m"}（ttl 为 "5m" 或 "1h"，默认 "5m"）。每次调用都会按该 TTL 写入一个缓存条目，因此对话中后续调用可读取稳定前缀。省略 = 顾问提示词不缓存。

The advisor model must be at least as capable as the executor. An invalid pairing returns 400 invalid_request_error. Valid pairs:

顾问模型的能力必须不低于执行器。 无效配对会返回 400 invalid_request_error。有效配对：

Warning: The advisor's payload shape differs by advisor model. The response block is always advisor_tool_result; what varies is its content, a discriminated union:

content type	Fields	When
advisor_result	text, stop_reason	Advisor returns plaintext (e.g. Opus 4.8)
advisor_redacted_result	encrypted_content, stop_reason	Advisor returns encrypted output - Claude Opus 5.5, Claude Opus 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Sonnet 5.5
advisor_tool_result_error	error_code	Consultation failed - max_uses_exceeded, prompt_too_long, too_many_requests, overloaded, unavailable, execution_time_exceeded, or model_not_found

So switch on advisor_tool_result.content type, not on the block type. Code that reads .text unconditionally gets nothing back from an Claude Opus 5.5 or Claude Opus 5 advisor, because the payload is under encrypted_content instead - and you cannot read it, only replay it.

警告：顾问的载荷形态因顾问模型而异。 响应块始终是 advisor_tool_result；变化的是它的 content，一个可辨识联合（discriminated union）：

content 类型	字段	出现时机
advisor_result	text、stop_reason	顾问返回明文（例如 Opus 4.8）
advisor_redacted_result	encrypted_content、stop_reason	顾问返回加密输出——Claude Opus 5.5、Claude Opus 5、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Sonnet 5.5
advisor_tool_result_error	error_code	咨询失败——max_uses_exceeded、prompt_too_long、too_many_requests、overloaded、unavailable、execution_time_exceeded 或 model_not_found

因此应依据 advisor_tool_result.content 的类型分支处理，而不是依据块类型。无条件读取 .text 的代码在 Claude Opus 5.5 或 Claude Opus 5 顾问那里什么都拿不到，因为载荷在 encrypted_content 之下——而且你无法读取它，只能原样回放。

【评论】advisor_redacted_result 的加密输出意味着调用方无法检查顾问的实际内容，只能把它回放给执行器模型——这是一种对客户端屏蔽模型间中间通信的设计。

Call via client.beta.messages.create(...) with betas=["advisor-tool-2026-03-01"] (or the anthropic-beta: advisor-tool-2026-03-01 header). In multi-turn conversations, append the full response.content - including any advisor_tool_result blocks - back to messages on the next turn. If you remove the advisor tool from tools on a later turn while the history still contains advisor_tool_result blocks, the API returns a 400.

通过 client.beta.messages.create(...) 调用并带上 betas=["advisor-tool-2026-03-01"]（或 anthropic-beta: advisor-tool-2026-03-01 头）。在多轮对话中，下一轮要把完整的 response.content——包括任何 advisor_tool_result 块——追加回 messages。如果后续某一轮从 tools 中移除了 advisor 工具，而历史中仍包含 advisor_tool_result 块，API 会返回 400。

Advisor on Managed Agents: CMA sessions support an advisor too, configured as a {"type": "advisor", "model"} entry in the agent's multiagent roster rather than as a tool definition - no max_uses/max_tokens/caching options, and advice is delivered as thread events on the session's event stream rather than advisor_tool_result blocks. See shared/managed-agents-multiagent.md -> Advisor.

Managed Agents 上的 Advisor： CMA 会话同样支持顾问，配置为代理 multiagent 名册中的 {"type": "advisor", "model"} 条目而非工具定义——没有 max_uses/max_tokens/caching 选项，且建议以会话事件流上的线程事件形式传递，而不是 advisor_tool_result 块。见 shared/managed-agents-multiagent.md -> Advisor。

Client-Side Tools: Memory / 客户端工具：记忆

The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.

记忆工具让 Claude 能通过一个记忆文件目录跨对话存储和检索信息。Claude 可以创建、读取、更新和删除在会话之间持久化的文件。

Key Facts / 关键事实

• Client-side tool - you control storage via your implementation
  客户端工具——存储由你的实现控制
• Supports commands: view, create, str_replace, insert, delete, rename
  支持的命令：view、create、str_replace、insert、delete、rename
• Operates on files in a /memories directory
  操作 /memories 目录中的文件
• The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
  Python、TypeScript 和 Java SDK 提供用于实现记忆后端的辅助类/函数

Security: Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) - check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.

安全： 绝不要在记忆文件中存储 API 密钥、密码、令牌或其他秘密。对个人身份信息（PII）要谨慎——持久化用户数据前先确认数据隐私法规（GDPR、CCPA）。参考实现没有内置访问控制；在多用户系统中，请在工具处理器中实现按用户隔离的记忆目录和身份验证。

【评论】记忆目录跨会话持久化用户相关数据，属于高敏存储位置；若提示词注入能驱动模型调用该工具，可能带来跨会话的数据污染或泄露风险，因此按用户隔离与鉴权需要由调用方自行实现。

For full implementation examples, use WebFetch:

完整实现示例请用 WebFetch 获取：

• Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md
  Docs：https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md

Client-Side Tools: Bash and Text Editor / 客户端工具：Bash 与文本编辑器

The bash and text editor tools are Anthropic-defined, schema-less tools. Declare them by type and name only - the input schema is built into the model and cannot be modified. Do not pass an input_schema, and do not define a custom tool that happens to be named "bash" - that creates a user-defined tool without the built-in behavior.

bash 与文本编辑器工具是 Anthropic 定义的无 schema 工具。只需通过 type 和 name 声明——输入 schema 内置于模型中，不可修改。不要传 input_schema，也不要定义恰好名为 "bash" 的自定义工具——那会创建一个没有内置行为的用户自定义工具。

Both are client-executed: Claude returns a tool_use block, your code performs the action locally, and you send back a tool_result. The API is stateless; your application maintains the shell session or filesystem between turns.

两者都由客户端执行：Claude 返回 tool_use 块，你的代码在本地执行操作，然后你回传 tool_result。API 是无状态的；shell 会话或文件系统由你的应用在轮次之间维护。

Bash tool declaration / Bash 工具声明

{"type": "bash_20250124", "name": "bash"}

Claude's tool_use.input contains either {"command": "<string>"} or {"restart": true}. Check for restart first (reset the session, return a confirmation string); otherwise run command and return combined stdout + stderr.

Claude 的 tool_use.input 包含 {"command": "<string>"} 或 {"restart": true}。先检查 restart（重置会话，返回确认字符串）；否则运行 command 并返回合并后的 stdout + stderr。

Security - commands are untrusted model output. Run in an isolated environment (container, VM, or restricted user); apply an allowlist of permitted executables and reject shell operators (&&, |, ;, `, $()); set timeouts and resource limits; log every command. A blocklist is not sufficient.

安全——命令是不可信的模型输出。 在隔离环境中运行（容器、虚拟机或受限用户）；对可执行文件使用白名单，拒绝 shell 操作符（&&、|、;、`、$()）；设置超时与资源限制；记录每条命令。仅靠黑名单是不够的。

Text editor tool declaration / 文本编辑器工具声明

{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}

Optional field: max_characters to cap view output. Java exposes a typed ToolTextEditor20250728 builder (com.anthropic.models.messages); other statically-typed SDKs follow the same naming pattern - see the Anthropic-Defined Tools section in {lang}/claude-api/tool-use.md for the exact class.

可选字段：max_characters，用于限制 view 的输出量。Java 提供带类型的 ToolTextEditor20250728 构建器（com.anthropic.models.messages）；其他静态类型 SDK 沿用同样的命名模式——确切的类名见 {lang}/claude-api/tool-use.md 的 Anthropic-Defined Tools 一节。

Security - path is untrusted model output. Confine every file operation to a fixed project root. Before executing any command, resolve the model-supplied path to its canonical form and verify it remains within your project root; reject the request if it escapes (.., symlinks, absolute paths outside the root, URL-encoded traversal like %2e%2e%2f). Use your language's built-in path utilities (e.g., Python pathlib.Path.resolve() then check .is_relative_to(root)). Never call open() / writeFile / unlink directly on the raw path value.

安全——path 是不可信的模型输出。把所有文件操作限制在固定的项目根目录内。 执行任何命令之前，先把模型提供的 path 解析为规范形式，并验证它仍位于项目根目录之内；如果越界（..、符号链接、根目录之外的绝对路径、%2e%2e%2f 之类的 URL 编码遍历），则拒绝请求。使用你所用语言内置的路径工具（例如 Python 中先 pathlib.Path.resolve() 再检查 .is_relative_to(root)）。绝不要直接对原始 path 值调用 open() / writeFile / unlink。

tool_use.input.command is one of:

tool_use.input.command 是以下之一：

For both tools, on error return {"type": "tool_result", "tool_use_id": "...", "content": "<error text>", "is_error": true} so Claude can recover.

对这两个工具，出错时返回 {"type": "tool_result", "tool_use_id": "...", "content": "<error text>", "is_error": true}，让 Claude 能够恢复。

Structured Outputs / 结构化输出

Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool - it enhances the Messages API response format and/or tool parameter validation.

结构化输出约束 Claude 的响应遵循特定的 JSON schema，保证输出有效且可解析。它不是一个独立的工具——它是对 Messages API 响应格式和/或工具参数校验的增强。

Two features are available:

有两个可用特性：

• JSON outputs (output_config.format): Control Claude's response format
  JSON 输出（output_config.format）：控制 Claude 的响应格式
• Strict tool use (strict: true): Guarantee valid tool parameter schemas
  严格工具调用（strict: true）：保证工具参数 schema 有效

Supported models: Claude Fable 5, Claude Mythos 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.

支持的模型： Claude Fable 5、Claude Mythos 5、Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8、Claude Sonnet 5.5、Claude Sonnet 5 与 Claude Haiku 4.5。旧模型（Claude Opus 4.5、Claude Opus 4.1）也支持结构化输出。

Recommended: Use client.messages.parse() which automatically validates responses against your schema. When using messages.create() directly, use output_config: {format: {...}}. The output_format convenience parameter is also accepted by some SDK methods (e.g., .parse()), but output_config.format is the canonical API-level parameter.

推荐： 使用 client.messages.parse()，它会自动按你的 schema 校验响应。直接使用 messages.create() 时，请用 output_config: {format: {...}}。某些 SDK 方法（例如 .parse()）也接受 output_format 便捷参数，但 output_config.format 才是规范的 API 级参数。

JSON Schema Limitations / JSON Schema 局限

Supported:

支持：

• Basic types: object, array, string, integer, number, boolean, null
  基本类型：object、array、string、integer、number、boolean、null
• enum, const, anyOf, allOf, $ref/$def
enum、const、anyOf、allOf、$ref/$def
• String formats: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid
  字符串格式：date-time、time、date、duration、email、hostname、uri、ipv4、ipv6、uuid
• additionalProperties: false (required for all objects)
  additionalProperties: false（所有对象都要求此项）

Not supported:

不支持：

• Recursive schemas
  递归 schema
• Numerical constraints (minimum, maximum, multipleOf)
  数值约束（minimum、maximum、multipleOf）
• String constraints (minLength, maxLength)
  字符串约束（minLength、maxLength）
• Complex array constraints
  复杂数组约束
• additionalProperties set to anything other than false
additionalProperties 设为 false 以外的任何值

The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.

Python 和 TypeScript SDK 会自动处理不受支持的约束：把它们从发送给 API 的 schema 中移除，并在客户端进行校验。

Important Notes / 重要注意事项

• First request latency: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
  首次请求延迟：新 schema 会产生一次性的编译开销。相同 schema 的后续请求使用 24 小时缓存。
• Refusals: If Claude refuses for safety reasons (stop_reason: "refusal"), the output may not match your schema.
  拒答：如果 Claude 因安全原因拒答（stop_reason: "refusal"），输出可能不符合你的 schema。
• Token limits: If stop_reason: "max_tokens", output may be incomplete. Increase max_tokens.
  token 限制：如果 stop_reason: "max_tokens"，输出可能不完整。请调大 max_tokens。
• Incompatible with: Citations (returns 400 error), message prefilling.
  不兼容于：引用（Citations，返回 400 错误）、消息预填充。
• Works with: Batches API, streaming, token counting, extended thinking.
  兼容于：Batches API、流式、token 计数、扩展思考。

Tips for Effective Tool Use / 高效工具使用技巧

1. Provide detailed descriptions: Claude relies heavily on descriptions to understand when and how to use tools
   提供详细描述：Claude 高度依赖描述来理解何时以及如何使用工具
2. Use specific tool names: get_current_weather is better than weather
   使用具体的工具名：get_current_weather 优于 weather
3. Validate inputs: Always validate tool inputs before execution
   校验输入：执行前始终校验工具输入
4. Handle errors gracefully: Return informative error messages so Claude can adapt
   妥善处理错误：返回有信息量的错误消息，让 Claude 能够调整
5. Limit tool count: Too many tools can confuse the model - keep the set focused
   限制工具数量：过多工具会使模型混淆——保持工具集聚焦
6. Test tool interactions: Verify Claude uses tools correctly in various scenarios
   测试工具交互：验证 Claude 在各种场景下都能正确使用工具

For detailed tool use documentation, use WebFetch:

详细的工具调用文档请用 WebFetch 获取：

• URL: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
  URL：https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview