大模型工具函数调用（Function Calling）实战指南

在上述代码中，tools 列表内的每个元素对应一个工具定义。当用户输入'今天巴黎的天气怎么样'时，模型会解析出意图与天气查询相关，并从对话内容中提取出地点信息，随后生成一条结构化的函数调用指令，而非直接返回文本回复。

模型返回的 response.output 中会包含一个 function_call 类型的输出项。可以看到，模型不仅识别了用户提到的'巴黎'，还自动补全了国家信息以符合参数描述中的格式要求。这一结果本身并不包含天气数据，而是一条等待执行的调用指令。

函数调用的完整交互流程可以概括为五个步骤：

首先，开发者通过 tools 参数传入函数 schema，告知模型可用工具的用途和参数格式。其次，模型根据用户输入判断是否需要调用工具，若需要则生成包含函数名和参数的调用指令。随后，应用程序解析模型输出，调用对应的自定义代码（如请求天气 API 获取实时数据）。接着，将函数执行的返回值以 tool result 的形式回传给模型。最后，模型基于原始问题和函数返回结果，生成一段完整的自然语言回答呈现给用户。

需要注意的是，整个流程中模型本身并不执行任何函数代码，它的职责仅限于意图识别、参数提取和结果整合。实际的 API 调用、数据库查询等操作均由开发者的应用程序负责完成。

函数调用工作流

函数调用的起点是向模型提供准确且完整的函数 schema 定义。这份 schema 是模型理解工具能力边界的唯一依据——模型并不知道函数的实际实现逻辑，它完全依赖 schema 中的描述信息来判断何时调用、如何构造参数。因此，schema 的质量直接决定了函数调用的准确率。

一个标准的函数 schema 需要包含以下核心字段：

其中 description 字段的撰写尤为关键。模糊的描述会导致模型在不恰当的时机触发调用，或者在应该调用时选择了错误的函数。例如，将天气查询函数的描述写为'获取天气'远不如'获取指定城市当前的实时气温和天气状况，适用于用户询问某地天气的场景'来得准确。

在参数定义层面，遵循一些最佳实践能够显著提升调用的可靠性。首先，应为每个参数添加详细的 description 说明，明确格式要求和示例值。其次，必须通过 type 字段指定参数的数据类型，避免类型歧义。对于有限取值的参数，应使用 enum 进行约束。最后，通过 required 数组显式声明必填参数，确保模型不会遗漏关键信息。

当模型决定调用函数后，应用程序需要按照规范的流程处理调用指令并完成结果回传。首先从 response.output 中解析出函数调用信息，提取 name（函数名）、arguments（参数 JSON 字符串）和 call_id（调用标识符）三个关键字段。然后根据函数名路由到对应的实现代码，将 arguments 反序列化为实际参数并执行。函数执行完成后，将返回值格式化为字符串，通过 function_call_output 类型的消息回传给模型，其中必须携带对应的 call_id 以便模型正确关联请求与结果。

在实际工程中，还需要对异常情况进行处理。函数执行可能因网络超时、参数非法、服务不可用等原因失败，此时应将错误信息以结构化的方式回传给模型，而非直接抛出异常。模型在接收到错误描述后，通常能够生成合理的兜底回复，从而保证对话体验的连贯性。

客户端工具实践

客户端工具（Client Tools）是 Claude 工具调用体系中最常用的模式。其核心特征在于：工具的实际执行发生在开发者的应用程序一侧，Claude 仅负责理解用户意图、决定是否调用工具并生成结构化的调用指令，而具体的函数逻辑、API 请求、数据处理等工作均由客户端代码完成。

客户端工具的完整交互流程分为四个阶段。首先，开发者在 API 请求中通过 tools 参数定义可用工具的名称、描述和输入参数的 JSON Schema，同时传入用户的自然语言消息。随后，Claude 评估当前对话是否需要借助工具来完成回答，若判断需要，则构造一条格式规范的工具调用请求，此时 API 响应中的 stop_reason 字段值为 tool_use，明确表示模型希望执行工具调用而非直接生成文本回复。

以下是一个基于 Claude API 的客户端工具调用完整示例，实现了天气查询功能：

import os
import anthropic
import json

API_KEY = os.getenv("CLAUDE_API_KEY")
API_BASE = os.getenv("CLAUDE_API_BASE")

client = anthropic.Anthropic(
    api_key=API_KEY,
    base_url=API_BASE,
)

TOOLS = [
    {
        "name": "get_weather",
        "description": "获取指定城市的当前天气信息，当用户询问某地天气时使用。",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称，例如：San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    }
]

# 第一步：定义工具并发送用户消息
response = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=10000,
    tools=TOOLS,
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}]
)

# 第二步：检查模型是否请求工具调用
if response.stop_reason == "tool_use":
    # 提取工具调用信息
    tool_block = next(b for b in response.content if b.type == "tool_use")
    tool_name = tool_block.name
    tool_input = tool_block.input
    tool_use_id = tool_block.id

    # 第三步：执行本地工具函数
    def get_weather(location: str) -> dict:
        # 实际场景中此处调用天气 API
        return {"temperature": "15°C", "condition": "partly cloudy"}

    result = get_weather(tool_input["location"])

    # 第四步：将结果回传给 Claude
    final_response = client.messages.create(
        model="claude-sonnet-4.6",
        max_tokens=10000,
        tools=TOOLS,
        messages=[
            {"role": "user", "content": "What's the weather in San Francisco?"},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [{"type": "tool_result", "tool_use_id": tool_use_id, "content": json.dumps(result)}]
            }
        ]
    )
    print(final_response.content[0].text)

上述代码中有几个关键细节值得注意。Claude 的工具定义使用 input_schema 字段（而非 OpenAI 的 parameters），这是两个平台在 API 设计上的主要差异之一。当 stop_reason 为 tool_use 时，response.content 中会包含一个 type 为 tool_use 的内容块，其中的 id 字段是调用标识符，在回传结果时必须通过 tool_use_id 进行关联，否则 Claude 无法正确匹配调用请求与返回结果。

在结果回传阶段，需要构造完整的对话历史传入第二次 API 调用，包括原始用户消息、Claude 的工具调用响应（作为 assistant 消息）以及工具执行结果（作为 user 消息中的 tool_result 内容块）。Claude 在接收到工具返回的数据后，会将其与原始问题结合分析，生成一段完整的自然语言回答。整个过程中，模型始终不直接执行任何代码，所有工具逻辑的安全性和正确性由开发者自行保障。

服务端工具实践

与客户端工具不同，服务端工具（Server Tools）的执行完全发生在 Anthropic 的基础设施上，开发者无需编写任何工具实现代码，也无需处理调用指令的解析与结果回传。Claude 在判断需要使用服务端工具后，会在服务端自动完成工具执行，并将结果直接整合到最终响应中。这种模式极大地简化了开发流程，尤其适用于 Anthropic 已经内置支持的通用能力场景。

目前 Claude 提供的服务端工具主要包括 web_search（网页搜索）和 web_fetch（网页内容获取）两种。前者允许模型在对话过程中主动检索互联网上的实时信息，后者则可以抓取指定 URL 的页面内容进行分析。开发者只需在 tools 参数中声明这些工具，无需定义 input_schema，因为服务端工具的参数结构由 Anthropic 预先规定。

import os
import anthropic

API_KEY = os.getenv("CLAUDE_API_KEY")
API_BASE = os.getenv("CLAUDE_API_BASE")

client = anthropic.Anthropic(api_key=API_KEY, base_url=API_BASE)

# 使用服务端工具 - web_search
response = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=10240,
    tools=[{"type": "web_search_20260209", "name": "web_search", "max_uses": 5}],
    messages=[{"role": "user", "content": "搜索一下 2026 年 3 月 13 日 GitHub 热门项目，简要介绍它们。"}]
)
print(response.content)

上述代码的结构相比客户端工具明显更为简洁。服务端工具通过特定的 type 标识（如 web_search_20260209）进行声明，而非使用通用的 "function" 类型。max_uses 参数用于控制工具在单次对话中的调用上限，防止模型过度依赖搜索而消耗过多资源。整个过程中，开发者只需发起一次 API 调用即可获得最终结果，不存在客户端工具中'接收调用指令—执行函数—回传结果'的多轮交互。

服务端工具的一个重要特性是支持内部采样循环（sampling loop）。当一个问题需要多步检索才能获得完整答案时，Claude 可以在服务端连续执行多次工具调用——例如先搜索关键词获取相关链接，再抓取特定页面提取详细内容——整个过程对开发者完全透明，最终返回的响应已经是经过多轮工具调用后综合整理的结果。

下表对客户端工具与服务端工具的核心差异进行了对比：

在实际项目中，客户端工具与服务端工具通常会混合使用。例如一个智能客服系统可以同时配置 web_search 用于检索公开信息，以及自定义的 query_order 客户端工具用于查询内部订单数据库。Claude 会根据用户的具体问题自主选择合适的工具组合，开发者只需确保客户端工具的调用链路正确处理即可。