Claude 工具调用：用 Python 定义工具并处理调用

开始之前

请先学完第 1 课：这一课沿用了它的客户端、密钥和遍历内容块的循环。工具调用走的是同一个 Messages 接口，只是请求里多了一个 tools 列表。

工具调用总览把工具分成两类，但模型自己都不运行。客户端工具，也就是你定义的那些，由你的代码运行函数并回报结果。网页搜索、网页抓取和代码执行这类服务端工具，则在 Anthropic 那边运行，所以响应到达时，结果可能已经在里面了。这一课讲的是客户端工具。

跑通 tool_use 与 tool_result 往返

一次请求，一个工具，两次调用。下面的代码定义了 get_weather，提出一个需要它的问题，并处理一次往返。第 4 课会把同样的步骤包进循环里。天气函数是为本课写的占位实现，请换成真正的查询。

第二次请求能否被接受，取决于两条规则。带结果的用户消息必须紧跟在含有 tool_use 块的助手消息之后，而且 tool_result 块必须排在它内容的最前面，位于任何文字之前。违反任何一条，API 都会返回 400。

import json
import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": (
            "Get the current weather for a city. Use it when the user asks about "
            "weather, temperature or whether to bring an umbrella. It returns the "
            "temperature in Celsius and a short condition. It does not forecast."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "A city name, for example Lisbon"},
            },
            "required": ["city"],
        },
    }
]


def get_weather(city: str) -> str:
    # Stand-in for a real weather API call.
    return json.dumps({"city": city, "temp_c": 18, "condition": "light rain"})


messages = [{"role": "user", "content": "Do I need an umbrella in Lisbon today?"}]

response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages
)

if response.stop_reason == "tool_use":
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            results.append(
                {
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": get_weather(**block.input),
                }
            )
    messages.append({"role": "user", "content": results})
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages
    )

for block in response.content:
    if block.type == "text":
        print(block.text)

1. 用 name、description 和 input_schema 定义工具，再把列表作为 tools 传入。
2. 发送用户消息。Claude 回复的 stop_reason 是 tool_use，并带有一个或多个 tool_use 块，每个块有 id、name 和 input。
3. 把 response.content 完整、不加修改地追加到历史里，作为助手消息。使用工具时，文档要求每个 thinking 块都原样传回。
4. 对每个 tool_use 块运行你的函数，并构造一个 tool_result 块，其 tool_use_id 与它的 id 相同。
5. 把所有结果放进一条用户消息里，再调用一次 API。这时 Claude 会写出最终回答。

写出 Claude 能用好的工具定义

描述决定了大部分效果。文档把它称作影响工具表现的最重要因素，要求至少写三四句话：这个工具做什么、什么时候用、每个参数是什么意思，以及它返回什么。

少而宽的工具，比多而窄的工具效果更好，所以把相关操作合并成一个带 action 参数的工具。几个工具并排时，名称按服务加前缀，比如 github_list_prs。函数只返回信息量高的数据，因为它返回的一切，都会变成下一次调用的输入 token。

用 tool_choice 引导调用

默认情况下，Claude 自己判断请求需不需要工具。tool_choice 可以改写这一点，在当前的模型上，它的四个取值表现各不相同。从发布说明可以看到，九月以来，强制调用的取值被一个模型接一个模型地关掉了。

并行调用也由同一个字段控制。在 auto 下，把 disable_parallel_tool_use 设为 true，就把 Claude 限制在每个回合最多调用一次工具。

一次响应里的多个工具调用

问两座城市的天气，Claude 可以在同一个响应里返回两个 tool_use 块。你的代码决定是一个接一个地运行，还是同时运行。关键在于回复：把每个 tool_result 都放进同一条用户消息里。

把每个结果分成单独的用户消息发送，一开始也能用，但并行工具调用页面提醒说，这样会教会 Claude 不再做并行调用。每个结果仍然需要自己那次调用的 id，API 靠 id 来配对，不看位置。

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "{\"temp_c\": 18}" },
    { "type": "tool_result", "tool_use_id": "toolu_02", "content": "{\"temp_c\": 24}" }
  ]
}

上报错误，让 Claude 能恢复

工具有两种失败方式：你的函数抛出异常，或者 Claude 发来的输入不合规。两种都用 tool_result 上报，把 is_error 设为 true，并附上说明怎样修正调用的消息。对于参数无效或缺失的调用，文档说 Claude 会先带着修正重试两三次，再向用户道歉。像下面这样的消息给了它修正的依据，一个光秃秃的“Error”则没有。

你决定不运行的调用，也需要一个 tool_result，带上 is_error 和原因。漏掉一个，下一次请求就会失败，错误信息说的是发现了 tool_use id，但后面没有紧跟 tool_result 块。

把工具返回的一切都当作不可信内容。处理工具调用页面提醒，网页或文件里可能带着专门用来引导模型的文字，文档把这叫作间接提示词注入（indirect prompt injection）。所以工具能碰什么，要在你自己的代码里强制限制，不要只写在提示词里。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01",
  "is_error": true,
  "content": "City not found. Pass a city name such as Lisbon, not a country."
}

Anthropic 和 Alex Albert 在 X 上谈工具设计

Anthropic 在 2025-09-11 在 X 上发帖，推荐了工程博客上的为智能体写好工具一文。文章认为，工具越多，效果不一定越好。它举的例子是：只返回匹配行的 search_logs，比把日志全部返回的 read_logs 更好用。定义工具页面至今仍把这篇文章列为命名和返回内容的延伸阅读，所以 get_weather 也照此办理，只返回两个字段，而不是整个天气 API 的响应。

Alex Albert 在 Anthropic 做研究，他在 2026-02-17 发帖说，工具使用示例、工具搜索和程序化工具调用都已正式可用。工具使用示例就是工具字段表里的 input_examples，现在不需要 beta 请求头。先把描述写好，再给带嵌套输入的工具加两三个示例。

X 官方嵌入卡片的截图，拍摄于 2026-11-05，时间为 UTC。点击截图可到 X 上打开原帖。两张卡片都省略了原帖结尾的链接。

常见错误

• 把每个 tool_result 放进单独的用户消息，这会减少并行调用。
• 在同一条消息里，把文字放在 tool_result 块的前面。
• 在结果后面紧跟着加一个文本块，这可能让 Claude 用空回复结束回合。
• 只用文本块重建助手消息，结果丢掉了 API 要求传回的 thinking 块。
• 描述只写一行，然后纳闷 Claude 为什么选错了工具。
• 在会拒绝它的模型上，用 tool_choice 强制调用工具。
• 明明 Claude 只要两个字段，却返回整行数据库记录。

自己试一试

• 再加一个工具 get_time，提一个两个工具都要用的问题。返回了几个 tool_use 块，你是不是在一条用户消息里回复的？
• 让 get_weather 在城市是“Atlantis”时抛出异常，并返回本课的错误 JSON。Claude 是换一个城市重试，还是告诉用户？
• 把描述删到只剩一句话，比较哪些问题仍然会触发这个工具。
• 把 disable_parallel_tool_use 设为 true，再问一遍两座城市的问题。

接下来

这一课的循环只跑一轮就停了，而每多一轮，都要重新发送同样的工具列表和系统提示词。第 3 课会把它们缓存起来。如果你更想接入现成的工具，不想自己写 schema，可以看 MCP 课程里连接服务器的那一课。

常见问题

资料来源

1. Anthropic Docs: Tool use with Claude (2026年11月5日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
2. Anthropic Docs: Define tools (2026年11月5日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
3. Anthropic Docs: Handle tool calls (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
4. Anthropic Docs: Parallel tool use (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use
5. Anthropic Docs: How tool use works (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works
6. Anthropic Docs: Tool runner (2026年11月4日 查阅)https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner
7. Anthropic Docs: Stop reasons and fallback (2026年11月4日 查阅)https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
8. Anthropic Docs: Prompt caching (2026年11月4日 查阅)https://platform.claude.com/docs/en/build-with-claude/prompt-caching
9. Anthropic Docs: Claude API errors (2026年11月4日 查阅)https://platform.claude.com/docs/en/api/errors
10. Claude Docs: Release notes (2026年11月5日 查阅)https://platform.claude.com/docs/en/release-notes/overview
11. Anthropic Engineering: Writing effective tools for agents (2026年11月5日 查阅)https://www.anthropic.com/engineering/writing-tools-for-agents
12. X: Anthropic shares its guide to writing tools for agents (2026年11月5日 查阅)https://x.com/AnthropicAI/status/1966236220868247701
13. X: Alex Albert on tool use examples and tool search becoming generally available (2026年11月5日 查阅)https://x.com/alexalbert__/status/2023834875678298535