建立工具整合（API）
讓你的智慧體在對話中呼叫你的 API——搜尋資料庫、建立工單、查詢訂單。
工具整合是可重複使用的 HTTP 端點，智慧體可在通話期間 呼叫它。你將工具的 JSON Schema 描述和端點 URL 提供給 ThunderPhone； 智慧體會根據對話決定何時呼叫，而 ThunderPhone 會從其伺服器發出 HTTP 請求，並將回應傳回給智慧體。
本指南將帶你端對端建立天氣查詢工具。
工具的結構
包含兩個部分：
- Schema——OpenAI 風格的函式定義
(
{type: "function", function: {name, description, parameters}})， 用於告訴 LLM 工具的用途及其接受的引數。 - 端點——當 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）。
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。
常見陷阱
智慧體從不呼叫工具
LLM 會根據工具描述決定是否呼叫工具。如果來電者的
問題不符合描述，模型便不會呼叫該工具。請強化描述（加入常見同義詞和
說法），或在智慧體提示詞中明確提及它（「當
來電者詢問天氣時，使用 get_weather。」）。
工具回傳過多資料
超過 6 kB 的回應會在逐字稿預覽中遭到截斷。請只回傳 LLM 所需的欄位——不要回傳整筆資料列。
逾時
工具端點的預設逾時時間為 10 秒。如果你需要更長時間，
請以非同步方式處理：回傳 {"status": "pending", "request_id": "..."}
並透過另一個工具呼叫呈現結果。
版本管理
每次整合 PATCH 都會建立新的修訂版本。查看
GET /v1/integrations/{id}/versions
以了解誰變更了哪些內容。如果你破壞了工具的結構描述，可以
手動將較舊的快照 PATCH 回去以復原。