构建工具集成（API）

工具集成是一个可复用的 HTTP 端点，智能体可以在通话期间调用它。您向 ThunderPhone 提供该工具的 JSON Schema 描述和端点 URL；智能体会根据对话决定何时调用它，ThunderPhone 则会从其服务器发出出站 HTTP 请求，并将响应返回给智能体。

控制台无需使用此 API 即可满足大多数工具需求：连接 → 应用 可通过几次 OAuth 点击连接 Slack、HubSpot、Salesforce、Google Calendar、 Google Sheets 和 Cal.com；连接 → API 可将任何 HTTP API 转换为智能体操作（粘贴一条 cURL 命令后，AI 向导会起草工具，并提供内置的测试请求功能）；连接 → MCP 可添加 MCP 服务器。请参阅连接。本指南介绍的是 API 界面底层的原始 API。

本指南将端到端演示如何构建天气查询工具。

工具的组成

包含两部分：

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

请认真编写工具及每个参数的 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-..."]
  }'

您可以将多个集成关联到一个智能体。智能体的提示词可以按名称引用它们——“当来电者询问天气状况时，使用 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 会读取该响应，并向来电者口述自然语言摘要。

签名使用与您的 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、转接、版本历史。

函数工具规范

完整的 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. 测试完整流程

常见问题

后续步骤

集成参考

函数工具规范

验证签名

通话记录 + 历史记录 API

​工具的组成

​1. 选择存储策略

在智能体中内联配置

已保存的集成

​2. 创建集成

​3. 在沙盒中测试端点

​4. 将集成关联到智能体

​5. 实现端点

​6. 测试完整流程

​常见问题

​后续步骤

集成参考

函数工具规范

验证签名

通话记录 + 历史记录 API

工具的组成

1. 选择存储策略

2. 创建集成

3. 在沙盒中测试端点

4. 将集成关联到智能体

5. 实现端点

6. 测试完整流程

常见问题

后续步骤