函数工具

函数工具允许您的 AI 智能体在通话期间调用外部 API。您可以使用它们查询客户数据、检查可用性、预约，或执行您的后端支持的任何操作。

工作原理

使用架构定义工具（工具接受哪些参数）
提供 endpoint 配置（ThunderPhone 在哪里调用您的 API）——或者省略该配置，以便通过您的组织 webhook 接收工具调用
通话期间，AI 会根据对话决定何时使用工具
ThunderPhone 使用工具参数调用您的端点
您的 API 响应会反馈给 AI，以继续对话

函数工具支持自带 API。ThunderPhone 还提供无需端点的平台托管工具：应用连接（HubSpot、Salesforce、Slack、 Google Calendar、Google Sheets、Cal.com）、 API 连接和 MCP 服务器。

工具架构

每个工具都遵循以下结构：

{
  "type": "function",
  "function": {
    "name": "search_appointments",
    "description": "Find available appointment slots for a given date",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "service": {
          "type": "string",
          "description": "Type of service (e.g., 'consultation', 'follow-up')"
        }
      },
      "required": ["date"]
    }
  },
  "endpoint": {
    "url": "https://api.example.com/appointments/search",
    "method": "POST",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  }
}

函数定义

字段	类型	必填	说明
`name`	string	是	工具的唯一标识符
`description`	string	是	向 AI 说明何时使用此工具
`parameters`	object	是	工具参数的 JSON Schema

端点配置

字段	类型	必填	说明
`url`	string	是	您的 API 端点 URL
`method`	string	否	HTTP 方法（默认值：`POST`）
`headers`	object	否	要包含的自定义标头

endpoint 配置不会发送给 AI 模型——它仅供 ThunderPhone 用于执行工具调用。

两种调用路径

您的服务器收到哪种请求取决于工具是否具有 endpoint：

	具有 `endpoint` 的工具	不具有 `endpoint` 的工具
请求发送位置	直接发送至 `endpoint.url`	您组织的旧版 webhook URL
请求正文	纯工具参数	`telephony.tool` / `web.tool` 封装
标头	您的 `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
签名密钥	组织 webhook 密钥	组织 webhook 密钥

两种路径都是阻塞式的——AI 会在句子说到一半时等待结果——超时时间为 20 秒。请确保处理程序快速响应。可以混合使用：对于组织具有 webhook URL 的通话，具有 endpoint 的工具会被直接调用，其余工具则回退到 webhook。

直接端点调用

当 AI 调用具有 endpoint 的工具时，ThunderPhone 会向您的 URL 发送请求：

请求头

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-Api-Key: your-api-key

会始终原样包含来自您的 endpoint.headers 的自定义请求头，以及两个带有 ThunderPhone 命名空间的请求头：

X-ThunderPhone-Signature —— 使用您的组织 webhook 密钥作为密钥，对精确的请求正文字节进行 HMAC-SHA256 计算所得的签名
X-ThunderPhone-Call-ID —— 当前通话 ID

除非您的 endpoint.headers 覆盖它，否则会设置 Content-Type: application/json ——自定义 Content-Type 优先。

该签名使用来自 GET /v1/webhook 的组织级 webhook 密钥作为密钥。如果您的组织从未配置过旧版 webhook，则不存在密钥，工具调用将仅携带 X-ThunderPhone-Call-ID ——对缺少签名直接失败的处理程序会拒绝这些调用。您可以配置旧版 webhook 以获取密钥，或者将您自己的共享密钥放入 endpoint.headers。

请求正文

对于 POST / PUT / PATCH，正文仅包含工具参数（无包装对象），并以规范方式序列化（键排序、紧凑分隔符）：

{"date":"2025-01-02","service":"consultation"}

对于 GET / DELETE，参数会作为查询参数发送，正文为空——此时会基于空字节字符串计算签名。请参阅验证 webhook 签名。

响应

返回包含工具结果的 JSON 响应：

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

响应会被格式化并提供给 AI 以继续对话。非 JSON 响应会包装为 {"data": "<text>"}；超时和连接失败会作为错误报告给 AI，因此智能体可以致歉并继续，而不会停滞。

Webhook 模式分发

不带 endpoint 的工具会作为已签名的 telephony.tool（电话通话）或 web.tool （网页通话）请求，分发到您组织的旧版 webhook URL。与执行后发送到 webhook 端点的审计通知不同，此请求就是执行本身——您的 HTTP 响应即为工具结果。

{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}

web.tool 使用 origin_domain 替代 from_number / to_number。请以 JSON 形式返回工具结果——响应约定与直接端点调用相同。与其他所有 webhook 一样，请求会使用组织 webhook 密钥对原始正文进行签名。

已订阅的 webhook 端点还会在每个工具执行后额外收到一条非阻塞的 telephony.tool / web.tool 通知（无论通过哪种路径执行），其中包含工具的响应——适用于审计跟踪。请参阅事件目录。

签名验证

直接工具调用的签名方式与 webhook 相同：

对精确的请求正文字节计算 HMAC-SHA256（规范化 JSON —— 键已排序，无额外空白字符）
使用您组织的 webhook 密钥作为密钥
GET / DELETE 工具对空字节字符串签名

import hmac
import hashlib

def verify_tool_call(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    signature = request.headers.get("X-ThunderPhone-Signature", "")

    if not verify_tool_call(body, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401)

    data = json.loads(body)
    date = data["date"]

    # Look up availability
    slots = await get_available_slots(date)

    return {"available_slots": slots}

app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-thunderphone-signature'] || '';
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!signature ||
      signature.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send('Invalid signature');
  }

  const { date, service } = JSON.parse(req.body);

  // Look up availability
  const slots = getAvailableSlots(date, service);

  res.json({ available_slots: slots });
});

完整示例——包括空正文情况和未设置密钥时的注意事项——请参阅验证 webhook 签名。

示例：完整预约流程

以下是一组用于完整预约系统的工具：

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "book_appointment",
        "description": "Book an appointment at a specific time",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "time": { "type": "string", "description": "HH:MM format" },
            "customer_name": { "type": "string" },
            "customer_phone": { "type": "string" }
          },
          "required": ["date", "time", "customer_name"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/book",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "cancel_appointment",
        "description": "Cancel an existing appointment",
        "parameters": {
          "type": "object",
          "properties": {
            "confirmation_number": { "type": "string" }
          },
          "required": ["confirmation_number"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/cancel",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    }
  ]
}

最佳实践

编写清晰的描述

description 字段可帮助 AI 理解何时使用该工具。请具体说明其功能及适用场景。

妥善处理错误

返回 AI 能够理解的错误消息：{"error": "No slots available for that date"}，而非通用的 500 错误。

保持响应简洁

仅返回 AI 继续对话所需的信息。大型负载会降低响应速度。

合理使用必填字段

仅在确有必要时才将字段标记为 required。AI 会在调用工具前向用户询问必填信息。

应用连接

由平台管理的 HubSpot、Salesforce、Slack、Google Calendar、Google Sheets 和 Cal.com 工具，无需端点。

MCP 服务器

连接 MCP 服务器，让智能体调用其工具。

API 连接

可附加到智能体的可复用 REST 集成。

验证 Webhook 签名

用于 Webhook 和工具调用的验证辅助工具。

Webhooks

Function Tools

工作原理

工具架构

函数定义

端点配置

两种调用路径

直接端点调用

请求头

请求正文

响应

Webhook 模式分发

签名验证

示例：完整预约流程

最佳实践

相关内容

应用连接

MCP 服务器

API 连接

验证 Webhook 签名

​工作原理

​工具架构

​函数定义

​端点配置

​两种调用路径

​直接端点调用

​请求头

​请求正文

​响应

​Webhook 模式分发

​签名验证

​示例：完整预约流程

​最佳实践

​相关内容

应用连接

MCP 服务器

API 连接

验证 Webhook 签名

工作原理

工具架构

函数定义

端点配置

两种调用路径

直接端点调用

请求头

请求正文

响应

Webhook 模式分发

签名验证

示例：完整预约流程

最佳实践

相关内容