如何实现工具使用
学习如何在Claude中实现工具使用功能,包括模型选择、工具定义、控制输出和错误处理的完整指南。
选择模型
通常,对于复杂工具和模糊查询,使用Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5或Claude Opus 3;它们能更好地处理多个工具,并在需要时寻求澄清。
对于简单工具,使用Claude Haiku 3.5或Claude Haiku 3,但请注意它们可能会推断缺失的参数。
如果使用Claude Sonnet 3.7进行工具使用和扩展思考,请参考我们的指南这里获取更多信息。
指定客户端工具
客户端工具(包括Anthropic定义的和用户定义的)在API请求的tools
顶级参数中指定。每个工具定义包括:
参数 | 描述 |
---|---|
name | 工具的名称。必须匹配正则表达式^[a-zA-Z0-9_-]{1,64}$ 。 |
description | 工具功能、使用时机和行为方式的详细纯文本描述。 |
input_schema | 定义工具预期参数的JSON Schema对象。 |
工具使用系统提示
当您使用tools
参数调用Anthropic API时,我们会从工具定义、工具配置和任何用户指定的系统提示构建一个特殊的系统提示。构建的提示旨在指导模型使用指定的工具并为工具正常运行提供必要的上下文:
工具定义的最佳实践
要在使用工具时获得Claude的最佳性能,请遵循以下准则:
- 提供极其详细的描述。 这是影响工具性能的最重要因素。您的描述应解释工具的每个细节,包括:
- 工具的功能
- 何时应该使用(以及何时不应该使用)
- 每个参数的含义以及它如何影响工具的行为
- 任何重要的注意事项或限制,例如如果工具名称不清楚,工具不返回什么信息。您能为Claude提供的关于工具的上下文越多,它在决定何时以及如何使用工具方面就会越好。每个工具描述至少要3-4句话,如果工具复杂则需要更多。
- 优先考虑描述而非示例。 虽然您可以在工具描述或附带提示中包含如何使用工具的示例,但这不如清晰全面地解释工具的目的和参数重要。只有在完全充实描述后才添加示例。
良好的描述清楚地解释了工具的功能、使用时机、返回的数据以及ticker
参数的含义。糟糕的描述过于简短,让Claude对工具的行为和用法有很多疑问。
控制Claude的输出
强制工具使用
在某些情况下,您可能希望Claude使用特定工具来回答用户的问题,即使Claude认为它可以在不使用工具的情况下提供答案。您可以通过在tool_choice
字段中指定工具来实现:
使用tool_choice参数时,我们有四个可能的选项:
auto
允许Claude决定是否调用任何提供的工具。这是提供tools
时的默认值。any
告诉Claude必须使用提供的工具之一,但不强制使用特定工具。tool
允许我们强制Claude始终使用特定工具。none
阻止Claude使用任何工具。这是未提供tools
时的默认值。
使用提示缓存时,对tool_choice
参数的更改将使缓存的消息块失效。工具定义和系统提示保持缓存,但消息内容必须重新处理。
此图表说明了每个选项的工作方式:
请注意,当您将tool_choice
设置为any
或tool
时,我们将预填充助手消息以强制使用工具。这意味着模型不会在tool_use
内容块之前发出思维链text
内容块,即使明确要求这样做。
在工具使用中使用扩展思考时,不支持tool_choice: {"type": "any"}
和tool_choice: {"type": "tool", "name": "..."}
,会导致错误。只有tool_choice: {"type": "auto"}
(默认值)和tool_choice: {"type": "none"}
与扩展思考兼容。
我们的测试表明这不应该降低性能。如果您希望保持思维链(特别是对于Opus)同时仍要求模型使用特定工具,您可以为tool_choice
使用{"type": "auto"}
(默认值)并在user
消息中添加明确指令。例如:伦敦的天气如何?在您的回复中使用get_weather工具。
JSON输出
工具不一定需要是客户端函数——您可以在任何时候使用工具,当您希望模型返回遵循提供模式的JSON输出时。例如,您可能使用具有特定模式的record_summary
工具。请参阅Claude工具使用获取完整的工作示例。
思维链
使用工具时,Claude通常会显示其”思维链”,即它用来分解问题并决定使用哪些工具的逐步推理。如果tool_choice
设置为auto
(这是默认值,请参阅强制工具使用),Claude Opus 3模型会这样做,Sonnet和Haiku可以通过提示来做到这一点。
例如,给定提示”旧金山现在的天气如何,那里现在几点?“,Claude可能会回应:
这种思维链提供了对Claude推理过程的洞察,可以帮助您调试意外行为。
对于Claude Sonnet 3模型,思维链默认情况下不太常见,但您可以通过在用户消息或系统提示中添加类似”在回答之前,请在标签中逐步解释您的推理。“来提示Claude显示其推理。
重要的是要注意,虽然<thinking>
标签是Claude用来表示其思维链的常见约定,但确切的格式(例如这个XML标签的名称)可能会随时间变化。您的代码应该像对待任何其他助手生成的文本一样对待思维链,而不应依赖<thinking>
标签的存在或特定格式。
并行工具使用
默认情况下,Claude可能使用多个工具来回答用户查询。您可以通过以下方式禁用此行为:
- 当tool_choice类型为
auto
时设置disable_parallel_tool_use=true
,这确保Claude使用最多一个工具 - 当tool_choice类型为
any
或tool
时设置disable_parallel_tool_use=true
,这确保Claude使用恰好一个工具
最大化并行工具使用
虽然Claude 4模型默认具有出色的并行工具使用能力,但您可以通过有针对性的提示来增加所有模型并行工具执行的可能性:
处理工具使用和工具结果内容块
Claude的响应根据它使用客户端还是服务器工具而有所不同。
处理客户端工具的结果
响应将有一个tool_use
的stop_reason
和一个或多个tool_use
内容块,包括:
id
:此特定工具使用块的唯一标识符。这将用于稍后匹配工具结果。name
:正在使用的工具的名称。input
:包含传递给工具的输入的对象,符合工具的input_schema
。
当您收到客户端工具的工具使用响应时,您应该:
- 从
tool_use
块中提取name
、id
和input
。 - 在您的代码库中运行与该工具名称对应的实际工具,传入工具
input
。 - 通过发送一个
role
为user
的新消息继续对话,内容块包含tool_result
类型和以下信息:tool_use_id
:这是工具使用请求的结果的id
。content
:工具的结果,作为字符串(例如"content": "15度"
)或嵌套内容块列表(例如"content": [{"type": "text", "text": "15度"}]
)。这些内容块可以使用text
或image
类型。is_error
(可选):如果工具执行导致错误,设置为true
。
重要的格式要求:
- 工具结果块必须紧跟在消息历史中相应的工具使用块之后。您不能在助手的工具使用消息和用户的工具结果消息之间包含任何消息。
- 在包含工具结果的用户消息中,tool_result块必须在内容数组中排在第一位。任何文本都必须在所有工具结果之后。
例如,这将导致400错误:
这是正确的:
如果您收到类似”在tool_use ids之后立即找到了没有tool_result块的错误”,请检查您的工具结果格式是否正确。
收到工具结果后,Claude将使用该信息继续生成对原始用户提示的响应。
处理服务器工具的结果
Claude在内部执行工具并将结果直接纳入其响应中,无需额外的用户交互。
与其他API的差异
与分离工具使用或使用特殊角色如tool
或function
的API不同,Anthropic的API将工具直接集成到user
和assistant
消息结构中。
消息包含text
、image
、tool_use
和tool_result
块的数组。user
消息包括客户端内容和tool_result
,而assistant
消息包含AI生成的内容和tool_use
。
处理max_tokens
停止原因
如果Claude的响应由于达到max_tokens
限制而被截断,并且截断的响应包含不完整的工具使用块,您需要使用更高的max_tokens
值重试请求以获得完整的工具使用。
处理pause_turn
停止原因
使用网络搜索等服务器工具时,API可能返回pause_turn
停止原因,表示API已暂停长时间运行的轮次。
以下是如何处理pause_turn
停止原因:
处理pause_turn
时:
- 继续对话:在后续请求中将暂停的响应原样传回,让Claude继续其轮次
- 根据需要修改:如果您想中断或重定向对话,可以在继续之前选择性地修改内容
- 保持工具状态:在继续请求中包含相同的工具以保持功能
故障排除错误
使用Claude工具时可能出现几种不同类型的错误: