构建工具集成（API）
让您的智能体在对话过程中调用您的 API——搜索数据库、创建工单、查询订单。
工具集成是一个可复用的 HTTP 端点，智能体可以在通话期间调用它。您向 ThunderPhone 提供该工具的 JSON Schema 描述和端点 URL；智能体会根据对话决定何时调用它，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 回去来手动回滚。