建立工具整合（API）

工具整合係一個可重複使用嘅 HTTP 端點，智能體可以 喺通話期間調用。你向 ThunderPhone 提供工具嘅 JSON 綱要描述 及端點 URL；智能體會根據對話決定何時調用，ThunderPhone 則會從其伺服器發出 HTTP 請求，並將回應傳回智能體。

本指南會逐步說明如何建立完整嘅天氣查詢工具。

工具結構

包括兩部分：

1. 綱要——OpenAI 風格嘅函數定義 （{type: "function", function: {name, description, parameters}}）， 用於告知 LLM 工具嘅功能及所需參數。
2. 端點——當 LLM 決定使用工具時，ThunderPhone 伺服器會調用嘅 URL。 請求為 JSON POST，正文包含由 LLM 選取嘅參數。

1. 選擇儲存策略

本指南使用已儲存整合嘅方式。

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）。

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" }
  }'

{
  "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-..."]
  }'

你可將多個整合連結至同一個智能體。智能體的提示可 按名稱引用整合——「當來電者查詢天氣狀況時，使用 get_weather」——或根據綱要說明自動識別整合。

5. 實作端點

當智能體呼叫工具時，ThunderPhone 會向你的 endpoint_url 發送已簽署的 POST 請求：

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

你的伺服器會回傳 JSON，並交回至 LLM：

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

LLM 會讀取該回應，並向來電者說出自然語言摘要。

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。

常見注意事項

後續步驟