切换主题
工具调用（Function Call）使用指南
什么是工具调用？
工具调用（function call）是指机器人在通话过程中，根据客户的问题调用您配置的外部接口，获取实时业务数据后再继续回复客户。
例如，机器人可以通过工具调用查询天气、车辆库存、试驾预约、订单进度等信息。相比只依赖预设话术或知识库，工具调用可以帮助机器人获得最新数据，提升对话的准确性和实用性。
工具调用需要先创建工具，再在对应机器人中启用该工具。机器人发布后，相关配置才会在通话中生效。
使用前准备
创建工具前，请先确认以下内容：
- 已准备可正常访问的外部接口地址。
- 已确认接口需要的参数名称、参数格式及鉴权信息。
- 接口能够在较短时间内稳定返回结果。需要在通话中使用查询结果的接口，建议在 2 秒内返回。
- 不要在工具名称、工具描述、参数描述等公开配置中填写密码、密钥或客户敏感信息。鉴权信息请通过 Header 配置。
配置流程
- 使用工具调用通常分为以下四步：
- 创建工具并填写基本信息。
- 配置外部接口的回调地址、超时、鉴权等信息。
- 定义接口需要接收的参数，并设置承接语。
- 在机器人编辑页启用工具，保存并发布机器人。
创建工具
- 进入「组件」>「工具调用」，点击【+新建】
- 新建工具时，需要依次完成"基础信息配置""回调设置"和"参数设置"。
填写基础信息
- 基础信息用于帮助 AI 理解工具的用途，并判断在什么情况下需要调用它。
| 配置项 | 填写说明 |
|---|---|
| 工具名称 | 使用简洁、明确的名称，例如"查询天气""查询车辆库存""查询试驾预约"。 |
| 工具描述 | 说明工具能解决什么问题、应在什么情况下调用，以及接口会返回哪些关键信息。描述越准确，AI 判断调用时机越准确。 |
- 建议按以下结构编写工具描述：
这是一个用于【查询内容】的工具。当客户询问【触发场景】时调用。接口返回【关键结果】，用于【回复目的】。
例如，"查询天气"工具可以这样描述：
这是一个根据城市和日期查询天气状况的工具。当客户询问某地当天或未来日期的天气时调用。接口返回天气情况、温度范围等信息，用于向客户播报天气并辅助其安排到店看车时间。
不建议只填写"查询天气""查库存"等过于简短的描述。工具描述不清晰时，机器人可能无法准确判断何时调用工具，或在不合适的场景发起调用。
配置回调设置
回调设置用于定义机器人调用外部接口时的请求方式和等待规则。
| 配置项 | 填写说明 |
|---|---|
| 回调URL | 填写外部接口的请求地址。机器人触发工具后，会向该地址发送请求。请确认地址可访问，且接口参数名称与本工具的参数配置一致 |
| 是否异步 | 同步调用会等待接口返回结果后再继续对话，适合天气、库存、预约等需要立即告知客户结果的场景。异步调用发起请求后不等待返回，无需在当前对话中立即使用结果的场景。 |
| 请求超时 | 设置等待接口响应的最长时间、单位为秒。同步接口建议设置为2秒，通常不超过5秒；异步接口最长不超过30秒。超时后会按调用失败处理。 |
| 是否缓存 | 开启后，短时间内相同参数的请求可服用已有结果，减少重复调用。仅建议用于允许短暂数据延迟的查询场景；库存、预约、订单状态等对实时性要求较高的数据，建议谨慎开启。 |
| 是否重试 | 开启后，调用失败时系统会自动再次尝试请求。适合查询类接口。对于提交订单、创建预约等可能重复产生业务记录的接口，请先确认接口支持重复调用。 |
| Header | 如接口需要鉴权或指定请求类型，可配置自定义请求头，例如Authorization、Content-Type。点击【+添加 Header】可增加多条请求头。 |
配置完成后，点击【保存】。
设置输入参数
参数是机器人调用接口时需要提供的信息。AI 会根据客户在通话中的表达，结合参数描述提取对应内容；若必填信息未收集完整，机器人会在对话中引导客户补充。
填写参数时，请确保参数名称和格式与外部接口要求一致。
| 配置项 | 填写说明 |
|---|---|
| 参数名称 | 接口接收的字段名称，例如 city、date、carModel |
| 参数类型 | 根据接口要求选择字符串、数字、布尔值、变量、对象或数组等类型。变量通常用于引用系统中已保存的对话信息。 |
| 默认值 | 当客户未提供该参数时，系统使用的默认内容。只有接口允许缺省时才建议设置。 |
| 参数描述 | 说明参数代表什么、从哪里获取、应使用什么格式。描述应尽量具体，便于 AI 准确提取。 |
| 是否必填 | 开启后，缺少该参数时机器人会优先向客户追问；关闭后，机器人可按默认值或接口的缺省逻辑继续调用。 |
以"查询天气"为例，可配置以下参数：
| 参数名称 | 参数类型 | 是否必填 | 参数描述 |
|---|---|---|---|
| city | 字符串 | 是 | 客户需要查询天气的城市名称，例如"北京""上海"。 |
| date | 字符串 | 否 | 客户希望查询的日期，例如"今天""明天""本周六"。未提供时默认查询当天。 |
如果接口只接受固定格式，请在参数描述中明确格式要求。例如接口只接受日期YYYY-MM-DD时，应在描述中说明这一格式，避免接口因参数格式不正确而调用失败。
需要传入多个字段时，点击【+ 添加参数】继续添加。
设置承接语
承接语是机器人在调用工具过程中播放给客户的话术，可减少等待时的静默感，让对话更自然。
每个阶段最多可配置3条承接语，系统会随机选择其中一条进行播放。
| 阶段 | 使用时机 | 示例 |
|---|---|---|
| 请求开始 | 机器人已发起接口调用时 | "好的，正在帮您查询，请稍等。" |
| 请求完成 | 接口成功返回结果时 | "已经查询到了，我来为您说明。" |
| 请求失败 | 接口调用失败或超时时 | "目前暂时无法查询到相关信息，我先为您记录下来。" |
建议至少配置"请求开始"和"请求失败"承接语。对于同步调用，还建议配置"请求完成"承接语。
承接语应与实际业务能力一致。比如异步调用无法立即获得查询结果时，不建议使用"马上告诉您查询结果"这类承诺即时反馈的话术。
在机器人中启用工具
创建工具后，还需要将它添加到机器人中。
进入对应机器人的编辑页，选择 工具设置，在"选择工具调用"中勾选需要使用的工具，点击 保存。一个机器人可以同时启用多个工具。
完成工具设置后，保存并发布机器人。通话过程中，AI 会结合客户的问题、工具描述和参数描述，自动判断是否调用工具，以及需要传入哪些参数。
常见使用场景
- 工具调用适合需要从业务系统获取实时信息的场景，例如：
- 查询天气：客户询问"明天适合去看车吗？"，机器人调用天气接口，结合客户所在城市和日期反馈天气情况。
- 查询库存：客户询问"这款车现在有现车吗？"，机器人调用库存接口，查询门店或仓库的实时库存。
- 查询预约：客户询问"我上周预约的试驾还有效吗？"，机器人调用预约系统，确认预约状态和预约时间。
- 查询订单：客户询问"我的订单什么时候能到？"，机器人调用订单系统，反馈订单当前进度。
在呼叫记录中查看调用结果
- 工具调用完成后，可在对应的呼叫记录中查看"工具调用"信息，包括本次调用传入的参数和接口返回结果。
- 当工具未按预期工作时，建议优先查看呼叫记录，确认：
- 机器人是否实际触发了工具调用。
- 传入的参数是否完整、格式是否正确。
- 接口是否成功返回结果。
- 是否发生超时、鉴权失败或其他接口错误。
常见问题
- 工具描述需要写多详细？
- 建议至少写清楚三件事：工具的用途、触发调用的场景、接口返回结果的含义。不要只写"查询天气"或"查询库存"。描述越清晰，机器人越容易在合适的时机调用正确的工具。
- 接口已经配置了，为什么机器人没有调用？
- 请检查工具是否已在机器人"工具设置"中启用；其次检查工具描述是否明确了调用场景，以及必填参数是否已从客户对话中收集完整。还应确认机器人已保存并发布最新配置。
- 请求超时设置多少合适？
- 同步接口建议设置为 2 秒，通常不超过 5 秒，以免影响客户的通话体验；异步接口最长不超过 30 秒。设置过短可能导致正常请求被误判为失败，设置过长则会让客户等待过久。
- 一个机器人可以使用多个工具吗？
- 可以。您可以在机器人"工具设置"中选择多个已创建的工具。机器人会根据客户当前的问题和各工具的描述，判断调用哪个工具。
- 工具调用失败后会怎样？
- 系统会播放"请求失败"承接语，并继续后续对话。建议同时在机器人话术中准备兜底回复，例如记录客户需求、转人工跟进或提供其他处理渠道。
- 什么时候不建议开启缓存？
- 当查询结果必须保持实时准确时，例如库存、订单状态、预约状态、账户余额等，建议谨慎开启缓存。缓存更适合短时间内结果变化不大的查询场景。