ツール
外部連携ツールや通話転送に関する仕様について。
エージェントが通話中や通話後に呼び出せる外部連携ツールや通話転送の仕様について説明します。
スタンダードプランでの表示
スタンダードプランをご利用の場合、サイドバーに「ツール」メニューは表示されません。
スタンダードプランのエージェントは、初期設定およびマニュアル・予約・サマリーの設定のみで必要なすべての対話・受付業務を完結できる構成となっています。現場事務の運用で本項目を設定・操作する必要はありません。
連携機能の概要（上位プラン・管理者向け）
- 通話転送: 通話中の顧客を人間の担当スタッフへ電話転送する機能です。エンタープライズプラン限定の機能であり、実電話による通話でのみ稼働します（Webコールからの転送は行われません）。
- カスタム MCP / HTTP API: 自社システムや外部APIと直接接続するための機能です。システム管理者による設定・保守が行われている場合のみ稼働します。
通話中に御社システムを呼ぶ
通話の最中に、エージェントが御社のシステム（会員、予約、チケットなど）を調べたり、書き込んだりするための設定です。つなぐ先は、御社が用意する API です。Kumion からお渡しするものではありません。御社のシステムから Kumion を呼ぶ API は、「API リファレンス」をご覧ください。
「ツール」を開き、タブの「カスタムMCP」か「HTTP API」を選びます。設定した内容は、次の通話から反映されます。
追加するときの共通事項
- 接続先は、https（ポート 443）の公開ホスト名だけです。
- 表示名は必須で、40文字までです。
- 認証の値（API キーなど）は、ヘッダーの欄に入れます。
- 1回の通話で同じツールを呼べる回数などは、下の「呼び出しの上限と一時停止」に従います。
HTTP API を追加する
「HTTP API」タブの「＋ HTTP APIを追加」をクリックし、次の項目を入力して「登録」を押します。
| 項目 | 必須 | 内容 |
|---|---|---|
| 表示名 | 必須 | 通話記録やキャンバスに出る名前です。 |
| メソッド | 必須 | GET・POST・PUT・PATCH・DELETE から選びます。初期値は GET です。 |
| URL | 必須 | 呼び出す先です。{{args.名前}} と書くと、その位置に引数の値が入ります（URL では自動で URL エンコードされます）。ホスト名の部分には使えません。 |
| いつ呼ぶか | 必須 | AI が呼び出すかどうかを判断する手がかりです。 |
| 引数（1行に1つ） | 任意 | AI が渡す値を、名前 : 説明 の形で1行に1つ書きます。名前のあとに * を付けると必須です。20個までで、値は文字列として渡されます。 |
| 認証 | 任意 | 送信するヘッダーを、名前と値で入れます。値にも {{args.名前}} を使えます。 |
| クエリ | 任意 | URL の末尾に付くパラメータを、名前と値で入れます。 |
| 詳細設定の本文（JSON） | 任意 | メソッドが POST・PUT・PATCH のときだけ出ます。JSON で書き、値の中で {{args.名前}} を使えます。Content-Type を指定しなければ application/json で送ります。 |
| 詳細設定のタイムアウト（ミリ秒） | 任意 | 1〜30000。空欄なら 8000（8秒）です。 |
引数は、先に「引数」の欄に書いてから、URL・ヘッダー・本文の「変数を挿入」で差し込むのが簡単です。
御社側の API の条件
- リクエスト：設定したメソッド・URL・ヘッダー・クエリ・本文のとおりに、1回だけ送ります。再送はしません。重複して実行されると困る処理は、御社側で防いでください。
- レスポンス：HTTP の 2xx で返してください。本文が JSON なら、改行や空白を詰めた形で、それ以外は文字列のまま AI に渡り、そのまま通話で話されることがあります。AI に読ませたい項目だけの、短い内容にしてください。先頭の2000文字までが渡ります。本文が空でも成功として扱います。
- サイズと時間：本文は1MBまで読み取ります。タイムアウトを超えると失敗として扱います。
- 失敗したとき：2xx 以外の場合、AI には「連携先がエラーを返しました（HTTP 状態）」と状態コードだけが伝わり、本文は渡りません。接続できない、時間切れの場合は、担当者へ引き継ぐ案内になります。HTTP 5xx・接続できない・時間切れが5回続くと、「呼び出しの上限と一時停止」のとおり一時停止します。
- リダイレクト：リダイレクト先も、接続を許可された公開ホスト名でなければなりません。
最小の例です。
| 項目 | 入力 |
|---|---|
| 表示名 | CRM照会 |
| メソッド | GET |
| URL | https://api.example.com/customers/{{args.customer_no}} |
| いつ呼ぶか | お客様番号を聞き取れたときに、契約状況を照会する。 |
| 引数 | customer_no* : お客様番号 |
| 認証 | 名前 Authorization、値 Bearer （御社の API キー） |
お客様が番号 12345 を伝えると、Kumion は次のリクエストを送ります。
GET https://api.example.com/customers/12345
Authorization: Bearer （御社の API キー）御社の API が次のように返すと、AI はこの内容を踏まえて話します。
HTTP/1.1 200 OK
Content-Type: application/json
{"status":"active","plan":"standard"}カスタム MCP を追加する
自社システムを MCP サーバーとして公開している場合の方法です。「カスタムMCP」タブの「＋ MCPサーバーを追加」をクリックします。
| 項目 | 必須 | 内容 |
|---|---|---|
| 表示名 | 必須 | 通話記録やキャンバスに出る名前です。 |
| 接続方式 | 必須 | 「http（HTTPS エンドポイントに接続）」を選びます。「stdio（サーバープロセスを起動）」は、運営側が許可したコマンドだけが使え、通常は使いません。 |
| URL | 必須 | MCP サーバーの https の URL です。 |
| 認証 | 任意 | 接続時に送るヘッダーを、名前と値で入れます。 |
| 公開するツール名 | 任意 | 「ツールを取得」で、サーバーが持つツールを読み込んで選びます。何も選ばなければ、すべて公開されます。ツール名の直接入力もできます。 |
| いつ使うか | 任意 | AI が使うかどうかを判断する手がかりです。 |
| 詳細設定のタイムアウト（ミリ秒） | 任意 | 1〜30000。空欄なら 15000（15秒）です。 |
御社側の MCP サーバーの条件
- MCP の Streamable HTTP で接続できること。接続の確立は3秒以内に終わる必要があります。
- ツールの名前・説明・引数の定義は、サーバーが返したものを AI がそのまま使います。説明と引数の説明は、AI が読んで使い分けられるように具体的に書いてください。
- 引数は、AI が指定した値がそのまま渡ります。値の確認は御社側でも行ってください。
- 「ツールを取得」と、一覧の「接続テスト」で、接続とツールの公開状況を確認できます。
AI が呼び出すタイミング
AI は、通話の流れの中で、ツールの「いつ呼ぶか」（MCP は「いつ使うか」）と、引数の説明だけを手がかりに、呼ぶかどうかを自分で判断します。次の点を守ると、意図した場面で、正しい引数で呼ばれます。
- 条件は、「何が聞き取れたとき」「何を依頼されたとき」のように、通話の中の出来事で書きます。
- 引数の説明には、お客様の言葉のどの部分を入れるかを書きます。必須の引数が欠けた呼び出しは受け付けられず、AI が聞き直します。
- 条件を満たさないときは呼ばれません。ツールが返した内容は、そのまま伝わります。返っていない情報を、AI が推測で補うことはありません。
通話中に呼び出しが失敗したときは、AI はその内容を推測で補わず、担当者への取次ぎや伝言を案内します。上限や一時停止の働きは、下の「呼び出しの上限と一時停止」と同じです。
キャンバスの Webhook ステップとの違い
キャンバスの「Webhook」ステップは、通話の流れがそのステップに到達したときに、必ず HTTP リクエストを送ります。AI は判断せず、引数も持ちません。これに対して「ツール」は、AI が会話の中で必要だと判断したときに、AI が決めた引数で呼び出します。
表示名
ツールには「表示名」があります。通話記録やキャンバスには、この名前が出ます。
- 変える：「ツール」の一覧で、MCP・HTTP API・コネクタの行のメニューから「表示名を編集」をクリックします。名前を入れて「保存」します。40文字までです。
- コネクタを追加するとき：「表示名（任意）」に入れます。空欄なら、コネクタの名前がそのまま表示されます。
表示名を変えても、エージェントがそのツールを呼び出す設定は変わりません。
呼び出しの上限と一時停止
外部のシステムを、通話中に呼び出しすぎたり、つながらない相手に呼び出し続けたりしないように、上限と自動の一時停止が入っています。MCP、HTTP API、外部サービスとの連携（コネクタ）のどれにも同じように働きます。設定は要りません。
上限
- 1回の通話：同じツールは5回まで、外部ツール全体で15回までです。
- 事業所全体：すべての通話を合わせて、1分あたり120回までです。
- 「接続テスト」：事業所全体で、1分あたり10回までです。通話の上限とは別に数えます。
上限に達すると、AIはそのツールをそれ以上は呼び出しません。お客様には、担当者への取次ぎか、伝言をご案内します。通話の記録には、上限で止まったことが残ります。「接続テスト」が上限に達したときは、「接続テストの回数上限に達しました。しばらく待ってから再度お試しください。」と出ます。しばらく待ってから、もう一度押してください。
一時停止
接続先につながらない状態が続くと、そのツールを自動で止めます。
- 止まる条件：接続できない、時間切れ、サーバーのエラー（HTTP 5xx）が5回続いたときです。成功すると、数え直します。相手が「リクエストの内容が違う」と返すとき（HTTP 4xx）は、数えません。
- 止まる時間：5分間です。止まっている間に始まる通話では、そのツールは使われません。AIはツールなしで応対します。
- 画面の表示：「ツール」の一覧の状態に、「一時停止中（接続エラーが続いたため）」と「復旧予定：10/2 14:35」のように出ます。時刻は日本時間です。
元に戻す
- 自動で戻る：復旧予定の時刻を過ぎると、次の通話で一度だけ接続を試します。つながれば、一時停止は解除されます。
- すぐに戻す：接続先を直したら、MCPの行で「接続テスト」をクリックします。つながると、「接続を確認したため、一時停止を解除しました。」と出ます。HTTP APIとコネクタの行には「接続テスト」がないので、復旧予定の時刻を待ってください。
何度も一時停止になるときは、接続先のシステムの状態と、ツールの設定（URLや認証）を確認してください。
入出力の記録
MCPとHTTP APIのツールは、呼び出しの内容を記録できます。コネクタにはこの設定はありません。
「ツール」の一覧で、ツールの行のメニューから編集を開き、「入出力の記録」を選びます。
- テスト通話のみ：キャンバスのテスト通話と、管理画面からのテスト通話だけを記録します。電話やWebコールの通話は記録しません。新しいツールは最初からこの設定です。
- 記録しない：どの通話も記録しません。
- すべての通話：電話やWebコールを含め、すべての通話を記録します。選ぶと「記録する期間」が出て、「24時間」か「7日間」を選びます。期間を過ぎると、設定は自動で「テスト通話のみ」に戻ります。残りの時間は「すべての通話・残りN時間」と出ます。
記録されるのは、このツールに渡した引数と、連携先からの応答です。保存期間は14日です。14日を過ぎると削除され、そのあとは通話詳細からも見られません。
見ることができるのは、事業所の管理者です。管理者以外のユーザーには、通話詳細に開く操作が出ません。内容を開くたびに、誰がいつ見たかが残ります。
開くのは、連携先のエラーを調べるときと、AIの回答と、連携先が返した内容が食い違うときです。調べ終わったら「テスト通話のみ」に戻してください。期間を過ぎれば自動でも戻ります。