旧版工具使用
此工具使用格式已过时
我们强烈建议您尽快切换到我们改进的工具使用结构,它更加可靠,并能实现更高质量的性能,特别是对于更复杂的工具使用任务。
此工具使用格式未针对 Claude 3 进行优化,可能会导致比我们更新的工具使用格式更差的性能。
旧版工具使用的工作原理
使用旧版工具使用时,函数是在提示本身内定义的。当您向 Claude 提供它可以使用的工具和函数的描述时,Claude 能够智能地决定何时以及如何使用这些工具来帮助回答问题和完成任务。
例如,假设您在提示中为 Claude 提供了一个名为 get_weather(location)
的函数,该函数可检索给定位置的当前天气。如果用户随后询问”伦敦现在的天气如何?“,Claude 将识别出它可以使用您提供的 get_weather
函数来查找答案。
在幕后,这是一个多步骤的过程:
- 函数定义和用户问题都在单个提示中传递给 Claude
- Claude 不仅需要工具及其描述才能成功决定是否使用工具,而且可能还需要伴随的示例,说明在哪些情况下应该使用此类工具,具体取决于用例和工具的复杂性。
- Claude 评估用户的问题,并决定使用哪些函数以及使用什么参数
- Claude 构造格式正确的函数调用
- 函数调用通过客户端代码使用明确的
stop_sequence
进行拦截,实际函数在客户端执行 - 函数结果传回给 Claude
- Claude 使用函数结果来制定对用户的最终响应
这种技术允许 Claude 利用外部知识和能力,同时仍然保持对话界面。
定义函数
通过向 Claude 提供包含在 XML 标签中的函数描述来定义函数。描述应包括:
- 函数名称
- 函数功能的纯文本说明
- 预期的参数、它们的类型和描述
- 返回值和类型
- 可能引发的任何异常
以下是函数定义的示例:
<tool_description>
<tool_name>get_weather</tool_name>
<description>
检索指定位置的当前天气。
返回一个包含两个字段的字典:
- temperature:float,当前温度(华氏度)
- conditions:string,当前天气状况的简要描述
如果找不到提供的位置,则引发 ValueError。
</description>
<parameters>
<parameter>
<name>location</name>
<type>string</type>
<description>城市和州,例如 San Francisco, CA</description>
</parameter>
</parameters>
</tool_description>
编写良好的函数描述的一些提示:
- 要清晰简洁,但提供足够的细节,以便 Claude 理解何时应使用该函数
- 指定参数和返回值的类型
- 提及可能引发的任何相关异常
- 使用纯文本描述,而不是代码语法
旧版工具使用格式
为了让 Claude 调用函数,它必须输出一个非常特定格式的 XML 块。格式如下所示:
<function_calls>
<invoke>
<tool_name>function_name</tool_name>
<parameters>
<param1>value1</param1>
<param2>value2</param2>
</parameters>
</invoke>
</function_calls>
如果 Claude 同时调用多个函数,<function_calls>
块可以包含多个 <invoke>
块。每个 <invoke>
包含被调用函数的名称和传入的参数。
您应该将
</function_calls>
作为stop_sequence
传递到您的 API 调用中,以确保 Claude 在调用函数后停止生成文本。
在 <function_calls>
块之后,并假设您有适当的停止序列,Claude 将停止生成并等待函数结果在 <function_results>
块中传回,如下所示:
<function_results>
<result>
<tool_name>function_name</tool_name>
<stdout>
function result goes here
</stdout>
</result>
</function_results>
函数结果应放在 <stdout>
标签内。如果函数引发异常,应返回如下内容:
<function_results>
<error>
error message goes here
</error>
</function_results>
完整的函数结果应作为继续之前对话的消息传回给 Claude。在收到函数结果后,Claude 将继续生成以将结果合并到其响应中。
旧版工具使用提示示例
以下是一个完整的提示示例,它为 Claude 提供了两个函数和一个需要使用它们的问题:
Content | |
---|---|
System | 在此环境中,您可以访问一组工具来回答用户的问题。 您可以像这样调用它们: <function_calls> <invoke> <tool_name>$TOOL_NAME</tool_name> <parameters> <$PARAMETER_NAME>$PARAMETER_VALUE</$PARAMETER_NAME> … </parameters> </invoke> </function_calls> 以下是可用的工具: <tools> <tool_description> <tool_name>get_current_stock_price </tool_name><description>获取公司的当前股票价格。返回 float:当前股票价格。 引发 ValueError:如果输入的符号无效/未知。</description> <parameters> <parameter> <name>symbol</name> <type>string</type> <description>要获取价格的公司的股票代码。</description> </parameter> </parameters> </tool_description> <tool_description> <tool_name>get_ticker_symbol</tool_name> <description>通过公司名称搜索获取其股票代码。返回 str:公司股票的代码。如果未找到匹配的股票代码,则引发 TickerNotFound。 </description> <parameters> <parameter> <name>company_name</name> <type>string</type> <description>公司名称。</description> </parameter> </parameters> </tool_description></tools> |
User | 通用汽车公司目前的股票价格是多少? |
以下是 Claude 的响应方式:
Content | |
---|---|
Assistant | <scratchpad> 要回答这个问题,我需要: 1. 使用 get_ticker_symbol() 函数获取通用汽车公司的股票代码。 2. 使用返回的股票代码通过 get_current_stock_price() 函数获取当前股票价格。</scratchpad> <function_calls> <invoke> <tool_name>get_ticker_symbol</tool_name> <parameters> <company_name>General Motors</company_name> </parameters> </invoke> </function_calls> |
Claude 首先调用 get_ticker_symbol
来检索通用汽车公司的股票代码。我们可以通过 </function calls>
停止序列识别出 Claude 想要调用函数。我们从相关 XML 标签之间提取相关数据,并代表 Claude 运行该函数。然后我们将结果在 <function_results>
标签中传回给 Claude。
Content | |
---|---|
User | <function_results> <result> <tool_name>get_ticker_symbol</tool_name> <stdout> GM </stdout> </result> </function_results> |
现在它知道了股票代码,Claude 随后将决定它必须调用 get_current_stock_price
并获取当前价格。
Content | |
---|---|
Assistant | <function_calls> <invoke> <tool_name>get_current_stock_price</tool_name> <parameters> <symbol>GM</symbol> </parameters> </invoke> </function_calls> |
我们也将这些结果传回。
Content | |
---|---|
User | <function_results> <result> <tool_name>get_current_stock_price</tool_name> <stdout> 38.50 </stdout> </result> </function_results> |
通过这整个对话链为 Claude 提供它需要的所有细节,Claude 将能够提供用户最终输出的答案。
Content |
---|
<answer> 通用汽车公司目前的股票价格为 $38.50。 </answer> |
旧版工具使用常见问题
在给定的交互中,我可以向 Claude 传递多少个工具?
您可以定义任意数量的工具和函数供 Claude 使用,尽管对于这种旧版工具使用结构,我们目前建议不要超过 3-5 个,具体取决于您的用例复杂性和相关函数。
Claude 是否有任何它知道的内置工具?
没有。您希望 Claude 使用的任何工具,您都必须在工具使用提示中自行定义。Claude 没有预定义的最佳工作的函数和定义列表。
新的工具使用格式何时会出现在 Vertex AI 或 Amazon Bedrock 上?
在不久的将来!