setup-tools

Bolna Function Tools

工具能让通话 Agent 真正发挥作用。LLM 根据 description 选择工具，从对话中收集参数，然后由 Bolna 发起 HTTP 请求，并将响应反馈到对话中。

何时添加工具

目标	工具
将来电者转接给人工客服	transfer_call（内置）
查询订单／客户／账户数据	自定义 HTTP GET
在 CRM 中创建工单／潜在客户／预约	自定义 HTTP POST
显示日历空闲时段	fetch_calendar_slots（Cal.com）
预约日历时段	book_calendar_slot（Cal.com）
查询任意地区的当前时间	向 WorldTimeAPI 发起自定义 HTTP GET
通过键盘输入收集 PIN／OTP／电话号码	DTMF（dtmf_enabled: true）

工具在 Agent 配置中的位置

agent_config
  └── tasks[]
        └── tools_config
              └── api_tools
                    ├── tools[]          ← function schemas (OpenAI-style + Bolna extensions)
                    └── tools_params     ← per-tool API config (method, url, headers, param mapping)

在提示词中使用 @function_name 引用工具，让 LLM 知道何时使用该工具。对于图 Agent，在节点上设置 function_call: "<tool_name>"，即可强制 LLM 使用指定的 tool_choice。

一分钟了解架构

{
  "name": "check_order_status",
  "description": "Use this function when the customer asks about their order status, delivery update, shipping progress, or tracking. The customer must provide their order ID.",
  "pre_call_message": "Let me check the status of your order.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The customer's order ID. Usually starts with ORD- followed by numbers, e.g., ORD-78234."
      }
    },
    "required": ["order_id"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": { "order_id": "%(order_id)s" },
    "url": "https://api.yourstore.com/orders",
    "api_token": "Bearer sk_live_abc123",
    "headers": {}
  }
}

分为两部分：

• 函数定义（name、description、parameters）——遵循 OpenAI 函数调用规范。LLM 会据此判断何时调用工具，以及要提取哪些内容。
• Bolna 扩展字段（pre_call_message、key、value）——告知 Bolna 如何执行 API 调用。

key 必须严格设为 "custom_task"。 不要更改。

不容违反的规则

1. 描述至关重要。 LLM 会读取描述，以决定是否调用工具。请包含同义词（“状态、发货、配送、追踪”）、必要的前置条件（“仅在来电者提供订单 ID 后使用”）和排除项（“不用于账单问题——请改用 lookup_invoice”）。
2. 只有在缺少参数就无法执行调用时，才将其标记为 required。 LLM 会不断追问，直到必填字段齐全——如果数据并非必需，这会很恼人。
3. 当 API 调用耗时超过约 500ms 时，务必添加 pre_call_message。 “请稍等片刻……”远胜于一片沉默。
4. 确保 parameters.properties 和 value.param 中的参数名称完全一致。 区分大小写。
5. 在 value.param 中使用格式说明符：字符串用 %(name)s，整数用 %(name)i，浮点数用 %(name)f。字符串几乎适用于所有情况；只有 API 需要带类型的 JSON 值时，才使用 %i／%f。
6. 信任自动注入的上下文变量。 {from_number}、{to_number}、{call_sid}、{agent_id} 以及任何 user_data 键都会自动替换——不要让 LLM 向来电者索取你已经掌握的数据。

快速示例

转接给人工客服

内置的 transfer_call 工具。其配置与自定义函数略有不同——它接入了 Bolna 的电话系统层：

{
  "tools": [
    {
      "key": "transfer_call",
      "name": "transfer_to_sales",
      "description": "Transfer when the caller asks about pricing, demos, or purchasing, or explicitly asks to speak to sales.",
      "parameters": {
        "type": "object",
        "required": ["call_sid"],
        "properties": {
          "call_sid": { "type": "string", "description": "Unique call id" }
        }
      },
      "pre_call_message": "Sure, transferring you to sales — please hold a moment."
    }
  ],
  "tools_params": {
    "transfer_to_sales": {
      "url": null,
      "param": {
        "call_sid": "%(call_sid)s",
        "call_transfer_number": "+919876543210"
      },
      "method": "POST",
      "headers": {}
    }
  }
}

为每个转接目标分别添加工具（transfer_to_sales、transfer_to_support、transfer_to_billing）——相比只用一个带有“选择哪个团队”参数的工具，这样能让 LLM 做出更明确的选择。

Cal.com——检查空闲时段，然后预约

按顺序使用两个工具。LLM 擅长将它们串联起来——先显示选项，再确认，然后预约。

{
  "tools": [
    {
      "key": "calendar_slot_availability",
      "name": "fetch_calendar_slots",
      "description": "Fetch open Cal.com slots after the caller asks about scheduling a meeting or demo. Use the caller's preferred date if provided; otherwise use the next 3 business days.",
      "pre_call_message": "Just a moment, let me check our availability.",
      "parameters": {
        "type": "object",
        "properties": {
          "preferred_date": {
            "type": "string",
            "description": "Preferred date in YYYY-MM-DD format. Optional."
          }
        }
      }
    },
    {
      "key": "calendar_book",
      "name": "book_calendar_slot",
      "description": "Book a Cal.com slot ONLY after the caller has confirmed a specific time. Collect their full name and email first.",
      "pre_call_message": "Booking that for you now.",
      "parameters": {
        "type": "object",
        "properties": {
          "slot": { "type": "string", "description": "ISO 8601 slot start time, e.g. 2026-05-22T14:00:00+05:30" },
          "name": { "type": "string", "description": "Caller's full name" },
          "email": { "type": "string", "description": "Caller's email for the calendar invite" }
        },
        "required": ["slot", "name", "email"]
      }
    }
  ]
}

在仪表板中为每个工具配置一次 Cal.com API 密钥、事件 ID 和时区。Bolna 会自动处理 HTTP 调用——内置的 Cal.com 工具无需编写 url／api_token。

自定义 HTTP POST——创建支持工单

{
  "name": "create_support_ticket",
  "description": "Use when the customer reports a problem, complaint, issue, or bug. Create a ticket with category, summary, and priority. Phone number is auto-injected.",
  "pre_call_message": "I'm creating a support ticket for this right away.",
  "parameters": {
    "type": "object",
    "properties": {
      "caller_phone":    { "type": "string", "description": "Auto-injected from {from_number}" },
      "issue_category":  { "type": "string", "description": "billing, technical, account, shipping, or other" },
      "description":     { "type": "string", "description": "1-2 sentence summary of the issue" },
      "priority":        { "type": "string", "description": "low, medium, or high. Set high if the customer is upset or the issue is time-sensitive." }
    },
    "required": ["caller_phone", "issue_category", "description"]
  },
  "key": "custom_task",
  "value": {
    "method": "POST",
    "param": {
      "caller_phone":   "%(caller_phone)s",
      "issue_category": "%(issue_category)s",
      "description":    "%(description)s",
      "priority":       "%(priority)s"
    },
    "url": "https://api.yourhelpdesk.com/tickets",
    "api_token": "Bearer helpdesk_key_789",
    "headers": { "Content-Type": "application/json" }
  }
}

如果不想询问来电者的电话号码，可在 Agent 提示词中添加 {from_number}，这样 LLM 就会自动填入 caller_phone。

DTMF（键盘输入）

对于数字输入，呼叫者更愿意键入而不是口述（OTP、账号、PIN）。在 task_config 中启用：

{ "task_config": { "dtmf_enabled": true } }

电话服务	是否支持？
Plivo	是
Twilio	是
Exotel / Vobiz / SIP BYOT	否

在提示词中告诉呼叫者输入数字后按 #，并告诉 Agent 这项输入的含义：

When you need the caller's phone number, say:
"Please enter your phone number on your keypad and press the hash key when done."

When you receive a message starting with "dtmf_number:", the digits that follow are
what the caller pressed. Read them back to confirm and proceed.

Agent 收到的内容：

dtmf_number: 9876543210

Agent 会像处理其他轮次一样处理这项输入——可以确认、传递给工具，或进行分支处理。

对于 IVR 式的菜单路由（“按 1 联系销售，按 2 联系支持”），请改用 Bolna 的 IVR 功能——这样就不会在每轮菜单交互中消耗大模型令牌。这里的 DTMF 用于输入内容（电话号码、OTP），而非导航。

深入了解

文件	内容
references/tool-schemas.md	完整的架构参考：所有字段、所有类型、格式说明符、自动注入和常见故障模式。
references/transfer-call.md	多目的地模式、转接后的处理方式、失败时的回退方案。
references/cal-com.md	端到端的获取和预订示例，包含提示词和对话记录示例。
references/dtmf.md	DTMF 提示词模式、电话服务支持情况、语音回退方案。
references/world-time.md	WorldTimeAPI 自定义工具——无需身份验证，可作为实用模板。

调试

症状	可能原因	修复方法
从未调用工具	description 太模糊，或与呼叫者的用词不匹配	使用同义词（“状态、跟踪、运输、配送”）和明确的触发短语重写
工具调用过于频繁	description 范围太宽，与其他工具重叠	收紧“仅当……”的前置条件
工具负载缺少字段	properties 和 param 中的参数名称不匹配	确保两者逐字节完全一致，包括大小写
API 返回 4xx	URL、身份验证或标头错误	先用 curl 测试请求；确认 api_token 格式中包含 Bearer
变量未替换	变量不在 Agent 提示词中	在提示词中添加 {variable_name}，使其位于作用域内
Agent 在 API 调用期间停滞	后端响应缓慢，且没有 pre_call_message	添加一条友好的“请稍等片刻”消息
工具返回成功，但 Agent 忽略结果	提示词中没有关于如何处理结果的说明	添加：“调用 X 后，总结结果并询问对方是否还需要其他帮助。”

另请参阅

• create-agent — 了解 tools_config.api_tools 在 Agent 配置中的位置。
• bolna-graph-agents — 在图流程中使用节点上的 function_call 调用工具。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/prompting-tips.md — 了解何时询问呼叫者，何时使用自动注入的变量。
• get-executions — 检查原始日志，查看工具实际收到和返回的内容。