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

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

公開日: 2026-11-07
Source: https://voicast.jp/blog/voice-ai-function-calling

## 要点

- 会話中のツールは、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 の応答の遅れの記事](https://voicast.jp/blog/voice-ai-latency)で扱います。

## 失敗の返し方

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

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

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

## 安全のための確かめ

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

1. **署名を確かめる**: 基盤からの呼び出しだけを受けるため、署名を確かめます（[Standard Webhooks の署名の記事](https://voicast.jp/blog/standard-webhooks-signature-verification)）。
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 で受けて人が対応する流れにします。
