ツール連携を構築する（API）

ツール統合は、エージェントが通話中に呼び出せる再利用可能な HTTP エンドポイントです。ツールの JSON スキーマ記述とエンドポイント URL を ThunderPhone に渡すと、エージェントは会話に基づいて呼び出すタイミングを判断し、ThunderPhone がそのサーバーからアウトバウンド HTTP リクエストを送信して、応答をエージェントに返します。

この API を使わなくても、ダッシュボードでほとんどのツール要件に対応できます。接続 → アプリでは、数回の OAuth クリックで Slack、HubSpot、Salesforce、Google Calendar、 Google Sheets、Cal.com を接続できます。接続 → APIでは、任意の HTTP API をエージェントアクションに変換できます（cURL コマンドを貼り付けると、AI ウィザードがツールを作成し、組み込みのリクエストテストも利用できます）。 接続 → MCPでは、MCP サーバーを追加できます。詳細は接続を参照してください。このガイドでは、API 画面の基盤となる生の API を扱います。

このガイドでは、天気を検索するツールをエンドツーエンドで作成します。

ツールの構成

構成要素は 2 つです。

スキーマ — ツールの機能と受け取る引数を LLM に伝える OpenAI 形式の関数定義 ({type: "function", function: {name, description, parameters}})。
エンドポイント — LLM がツールを使用すると判断した際に、ThunderPhone のサーバーが呼び出す URL。リクエストは JSON POST で、本文には LLM が選択した引数が含まれます。

1. 保存方法を選択する

エージェントにインラインで追加

単発のツールをエージェントの tools 配列に追加します。シンプルですが、再利用はできません。

保存済み統合

ツールを再利用可能な統合として保存し、複数のエージェントからリンクします。複数回使用するものにはこちらを推奨します。

このガイドでは、保存済み統合の方法を使用します。

2. 統合を作成する

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'

返された id（UUID）を保存します。

ツールと各パラメータの description は十分に検討して記述してください。 LLM は実行時にこれらの文字列を使用して、ツールを呼び出すかどうかと呼び出し方を判断します。曖昧な説明は、曖昧なツール呼び出しにつながります。

3. エンドポイントをサンドボックスでテストする

統合をエージェントにリンクする前に、ThunderPhone のサーバーから署名付きリクエストを送信し、接続を確認します。

curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'

Response

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

このテストでは ThunderPhone の SSRF 防御も強化されます。localhost またはプライベート IP 範囲へのリクエストは、400 code=url_not_allowed を返します。

4. 統合をエージェントにリンクする

エージェントを作成または更新する際に、integration_ids を使用して紐付けます。

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'

1つのエージェントに複数の統合をリンクできます。エージェントのプロンプトから名前で参照できます。たとえば、発信者が気象状況について質問した場合は get_weather を使用するよう指定できます。また、スキーマの説明から暗黙的に検出することもできます。

5. エンドポイントを実装する

エージェントがツールを呼び出すと、ThunderPhone は署名付き POST リクエストを endpoint_url に送信します。

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

サーバーは、LLM に返される JSON で応答します。

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM はその応答を取り込み、発信者に自然な要約を音声で伝えます。

署名は、webhook エンドポイントと同じ secret を使用して生のリクエスト本文から計算されます。必ず検証してください。ツールエンドポイントはインターネットに公開され、webhook と同様のなりすましリスクがあります。詳細は webhook 署名を検証するを参照してください。

6. ループをテストする

エージェントに対してマイクセッションを実行し、ツールが処理する質問（「94110 の天気は？」）をします。通話の文字起こしには、往復のすべての処理が表示されます。

{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}

これはGET /v1/calls/{call_id}/transcriptで取得できます。エントリごとのタイミングと音声オフセットを含む生イベントストリームは、GET /v1/calls/{call_id}/historyで取得できます。

よくある注意点

エージェントがツールを呼び出さない

LLM はツールの説明に基づいて判断します。発信者の質問が説明と一致しない場合、モデルはツールを呼び出しません。説明を具体化し（よく使われる同義語や表現を追加）、またはエージェントのプロンプトで明示します（「発信者が天気について質問した場合は get_weather を使用する。」）。

ツールが返すデータ量が多すぎる

6 kB を超える応答は、文字起こしのプレビューで切り詰められます。行全体ではなく、LLM が必要とするフィールドのみを返してください。

タイムアウト

ツールエンドポイントのデフォルトタイムアウトは 10 秒です。より長い時間が必要な場合は、非同期で処理してください。{"status": "pending", "request_id": "..."} を返し、別のツール呼び出しで結果を提示します。

バージョニング

統合に対する PATCH は、すべて新しいリビジョンを作成します。GET /v1/integrations/{id}/versionsを確認して、誰が何を変更したかを把握できます。ツールのスキーマを壊してしまった場合は、古いスナップショットを PATCH で戻すことで手動でロールバックできます。

次のステップ

連携リファレンス

CRUD、転送、バージョン履歴。

Function Tools仕様

完全なJSONスキーマ文法と署名付きエンドポイントの契約。

署名を検証

Webhook署名パターンをツールエンドポイントに適用。

文字起こし + 履歴API

ツール呼び出しの完全な往復を確認。

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

ツール連携を構築する（API）

ツールの構成

1. 保存方法を選択する

エージェントにインラインで追加

保存済み統合

2. 統合を作成する

3. エンドポイントをサンドボックスでテストする

4. 統合をエージェントにリンクする

5. エンドポイントを実装する

6. ループをテストする

よくある注意点

次のステップ

連携リファレンス

Function Tools仕様

署名を検証

文字起こし + 履歴API

​ツールの構成

​1. 保存方法を選択する

エージェントにインラインで追加

保存済み統合

​2. 統合を作成する

​3. エンドポイントをサンドボックスでテストする

​4. 統合をエージェントにリンクする

​5. エンドポイントを実装する

​6. ループをテストする

​よくある注意点

​次のステップ

連携リファレンス

Function Tools仕様

署名を検証

文字起こし + 履歴API

ツールの構成

1. 保存方法を選択する

2. 統合を作成する

3. エンドポイントをサンドボックスでテストする

4. 統合をエージェントにリンクする

5. エンドポイントを実装する

6. ループをテストする

よくある注意点

次のステップ