setup-tools

Bolna の関数ツール

ツールを使うと、会話エージェントが実用的になります。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_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 はいつ使用すべきかを認識できます。グラフエージェントの場合は、ノードに function_call: "<tool_name>" を指定すると、LLM の tool_choice が強制されます。

スキーマを1分で理解する

{
  "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": {}
  }
}

次の2つの部分で構成されます。

• 関数定義（name、description、parameters） — OpenAI function calling の仕様に準拠します。LLM はこれを使って、呼び出すタイミングと抽出する内容を判断します。
• Bolna の拡張項目（pre_call_message、key、value） — API 呼び出しをどのように実行するかを Bolna に伝えます。

key は必ず "custom_task" にしてください。 変更しないでください。

絶対に守るべきルール

1. 説明がすべてです。 LLM は説明を読んで、ツールを呼び出すかどうかを判断します。同義語（「ステータス、配送、配達、追跡」）、必須の前提条件（「発信者が注文 ID を伝えた後に限る」）、対象外のケース（「請求に関する質問には使用せず、代わりに lookup_invoice を使用する」）を含めてください。
2. 呼び出しに不可欠なパラメーターだけを required にしてください。 必須フィールドが埋まるまで LLM は質問を続けます。データが厳密には不要な場合、これは煩わしくなります。
3. API の処理に約500ミリ秒以上かかる場合は、必ず pre_call_message を追加してください。 無音のまま待たせるより、「少々お待ちください……」と伝えるほうがずっとよいです。
4. parameters.properties と value.param のパラメーター名を完全に一致させてください。 大文字と小文字は区別されます。
5. value.param では書式指定子を使用してください。 文字列には %(name)s、整数には %(name)i、浮動小数点数には %(name)f を使います。ほとんどの場合は文字列で問題ありません。%i／%f は、API が型付き JSON 値を必要とする場合にのみ使用してください。
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）を追加してください。「どのチームか」というパラメーターを持つ1つのツールよりも、LLM が適切な選択をしやすくなります。

Cal.com — 空き状況を確認してから予約する

2つのツールを順番に使用します。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" }
  }
}

発信者に電話番号を尋ねないようにするには、エージェントプロンプトに {from_number} を追加します。すると、LLM が caller_phone に自動入力します。

DTMF（キーパッド入力）

数字を音声ではなく入力したい場合（OTP、アカウント番号、PIN）は、task_config で有効にします。

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

テレフォニー	対応状況
Plivo	はい
Twilio	はい
Exotel / Vobiz / SIP BYOT	いいえ

プロンプトで、数字を入力した後に # を押すよう発信者に伝え、入力内容の意味をエージェントにも伝えます。

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.

エージェントが受け取る内容：

dtmf_number: 9876543210

エージェントはこれを通常のターンと同様に扱います。確認したり、ツールに渡したり、分岐したりできます。

IVR 形式のメニュー振り分け（「営業は1、サポートは2を押してください」）には、代わりに Bolna の IVR 機能を使用してください。メニューの各ターンで LLM トークンを消費しません。ここでの 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 が含まれていることを確認します
変数が置換されない	変数がエージェントのプロンプトに含まれていない	プロンプトに {variable_name} を追加し、スコープ内にします
API 呼び出し中にエージェントが停止する	pre_call_message が設定されておらず、バックエンドの応答が遅い	「少々お待ちください」などの丁寧なメッセージを追加します
ツールは成功を返すが、エージェントが結果を無視する	結果の扱い方がプロンプトに指示されていない	「X を呼び出した後、結果を要約し、ほかに必要なことがないか尋ねてください」と追加します

関連項目

• create-agent — tools_config.api_tools をエージェント設定に組み込む場所。
• bolna-graph-agents — グラフフローのノードで function_call を使ってツールを利用する方法。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/prompting-tips.md — 発信者に尋ねる場合と、自動挿入された変数を使う場合の判断方法。
• get-executions — 生ログを調べて、ツールが受け取った内容と返した内容を正確に確認する方法。