ブログ · · 約 6 分で読めます

通話中に AI が API を呼ぶ Function Calling:ツールの設計と待ち時間

電話の AI が会話中に予約システムや CRM の API を呼ぶ「ツール(関数呼び出し)」の設計を解説します。名前と説明の書き方、引数、読み取りと書き換えの分け方、待ち時間の扱い、失敗の返し方、署名やテナントの確かめなど安全のための作りまで、設定の例とあわせてまとめます。

要点

  • 会話中のツールは、AI が説明文を読んで「いつ使うか」を決めるので、名前と説明に使う場面と使わない場面をはっきり書きます。
  • 電話では相手が黙って待つ時間が長いと不安になるため、ツールの応答は短く、返す JSON も AI が話す分だけに絞ります。
  • 予約を作るなどの書き換えは読み上げて同意を得てから使い、同じ呼び出しが 2 回届いても 1 回分になる作りにします。

会話中に AI が外部の API を呼ぶには、「ツール(関数呼び出し。Function Calling とも呼ばれます)」を AI に渡します。AI はツールの説明を読んで使うかどうかを決め、引数を組み立て、基盤がその API を呼んで結果を AI に返します。電話では相手が黙って待つことになるため、説明の書き方に加えて、応答の速さ・失敗の返し方・書き換えの前の同意まで含めて設計します。

ツールの呼び出しの流れ

ツールは、AI と外部の API のあいだに立つ「呼んでよい操作の一覧」です。1 回の呼び出しは次のように進みます。

  1. 相手が「来週の火曜は空いてますか」と話す。
  2. AI がツールの説明を読み、空きを探すツールを使うと決め、引数(日付など)を作る。
  3. 基盤がツールの URL を呼ぶ。そのあいだ AI は「お調べしますので、少々お待ちください」とつなぐ。
  4. API が JSON を返す。
  5. AI が結果を読んで、「火曜は午前 10 時と午後 2 時が空いています」と話す。

AI が自分で HTTP を呼ぶわけではありません。呼ぶのは基盤で、AI は「どのツールを、どの引数で」を決めるだけです。だから、URL や鍵を AI に見せずに済みます。

名前と説明の書き方

AI がツールを使うかどうかは、ほぼ説明文で決まります。説明には「何をするか」だけでなく、「いつ使うか」「いつ使わないか」を書きます。

項目 よくない例 よい例
名前 api1 find_free_slots
説明 予約の API 予約の空き時間を探す。相手が日付や曜日を言って空きを聞いたときに使う。予約を作るときは使わない
引数の説明 date 探す日(YYYY-MM-DD)。「来週の火曜」などは日付に直して渡す

引数はできるだけ少なく、型をはっきりさせます。選べる値が決まっているもの(午前・午後など)は列挙にすると、AI が勝手な値を作りにくくなります。

ツールの数も絞ります。似たツールが並ぶと、AI がどれを使うか迷います。「空きを探す」「予約を作る」「予約を取り消す」のように、1 つのツールに 1 つの操作を割り当てます。

読み取りと書き換えの分け方

ツールは、読むだけのもの(空きを探す・顧客を探す)と、書き換えるもの(予約を作る・変える・取り消す)に分けて考えます。

  • 読み取り: 間違って呼んでも害が小さいので、AI の判断で呼ばせます。
  • 書き換え: 呼ぶ前に、内容を読み上げて相手の「はい」を得ます。聞き間違いのまま予約が入ると、取り消しの手間が大きいからです。

書き換えのツールは、同じ呼び出しが 2 回届いても 1 回分の結果になる作り(冪等)にしておきます。AI が言い直しのあとに同じツールをもう一度使うことや、時間切れのあとで処理が終わっていることがあるためです。通話の ID と引数から決まるキーで重複を見分けると、二重予約を防げます。

待ち時間の扱い

電話の相手は画面を見ていないので、無音が続くと「切れたのかな」と不安になります。ツールの応答は速いほどよく、遅くなる処理は前もって減らします。

  • 重い集計や外部への連絡は、会話のあとの Webhook で行う。
  • 応答の JSON は、AI が話すのに要る項目だけに絞る。長い一覧を返すと、AI が読むのにも時間がかかる。
  • 空き枠などは、電話で伝えられる数(2〜3 個)に絞って返す。

基盤には待つ時間の上限があります。上限を超えると失敗として扱われるので、その前に返せる作りにします。遅れの全体の考え方は音声 AI の応答の遅れの記事で扱います。

失敗の返し方

「結果が無い」と「処理に失敗した」は分けて返します。

状況 返し方 AI の振る舞い
空きが無い 2xx と { "slots": [] , "message": "その日は空きがありません" } 別の日を提案する
顧客が見つからない 2xx と { "found": false } 名前を聞き直す・新規として進める
予約システムが止まっている 5xx おわびして折り返しにする

業務として正しい「無い」を 5xx で返すと、AI は「失敗した」と受け取り、話を進められなくなります。

安全のための確かめ

ツールの URL は外から呼べる場所に置くことになるので、次の 3 つを守ります。

  1. 署名を確かめる: 基盤からの呼び出しだけを受けるため、署名を確かめます(Standard Webhooks の署名の記事)。
  2. テナントを引数から取らない: どの会社の予約を扱うかは、署名付きの本文に入っているテナントの ID から決めます。AI の作った引数にテナントを入れると、会話の内容しだいで別の会社のデータに触れてしまうおそれがあります。
  3. 返す内容を絞る: AI に渡したものは、相手に話される可能性があります。生年月日などは返さず、確かめた結果だけを返します。

voicast での会話中のツール

voicast では、エージェント設定の tools にツールを 10 個まで書けます。AI が使うと決めると、voicast が url に POST し、8 秒まで待ちます(そのあいだ AI は「お調べしますので、少々お待ちください」と言います)。2xx と JSON はそのまま AI に渡り、それ以外や時間切れは失敗として伝わって、AI はおわびして担当者からの折り返しにします。

json
{
  "tools": [
    {
      "name": "find_free_slots",
      "description": "予約の空き時間を探す。相手が日付や曜日を言って空きを聞いたときに使う。",
      "url": "https://api.example.com/voicast/find-free-slots",
      "parameters": {
        "properties": {
          "date": { "type": "string", "description": "探す日(YYYY-MM-DD)" },
          "period": { "type": "string", "enum": ["morning", "afternoon"], "description": "午前か午後" }
        },
        "required": ["date"]
      }
    }
  ]
}

受け口には { type: 'tool.call', tool, tool_call_id, arguments, call: { id, channel, provider_call_id, from, tenant: { id, external_id } } } が Standard Webhooks の署名付きで届きます。call.tenant.external_id で自社のどの顧客の通話かを決め、tool_call_id(見出しの idempotency-key と同じ)を重複の見分けに使えます。Google カレンダーや CRM なども、受け口からその API を呼べば同じ形で使えます。予約を作る・取り消すなど書き換えるツールには confirm: true を付け、読み上げて同意を得てから使わせます。

よくある質問

ツールはいくつまで渡せますか。

voicast の tools は 10 個までです。数を増やすほど AI が選び間違えやすくなるので、まずは用件に要る最小の数から始めます。

ツールの名前の付け方に決まりはありますか。

voicast では英小文字で始め、英小文字・数字・_ の 40 文字までで書きます。finish は使えず、同じ設定の中で名前が重なってもいけません。

ツールの応答が 8 秒を超えそうなときはどうしますか。

会話中には結果の要らない処理を会話のあとに回し、応答では受け付けたことだけを返します。それでも間に合わない処理は、AI が折り返しを案内し、会話のあとに Webhook で受けて人が対応する流れにします。

関連記事