Developer cookbook

Xây dựng tích hợp công cụ (API)

Cho phép tác nhân AI gọi API của bạn trong khi hội thoại — tìm kiếm cơ sở dữ liệu, tạo phiếu hỗ trợ, tra cứu đơn hàng.

Tích hợp công cụ là một điểm cuối HTTP có thể tái sử dụng mà tác nhân AI có thể gọi trong cuộc gọi. Bạn cung cấp cho ThunderPhone mô tả JSON-schema của công cụ cùng URL điểm cuối; tác nhân AI quyết định thời điểm gọi công cụ dựa trên cuộc trò chuyện, còn ThunderPhone gửi yêu cầu HTTP đi từ máy chủ của mình và trả phản hồi về cho tác nhân AI.

Hướng dẫn này sẽ chỉ bạn cách xây dựng công cụ tra cứu thời tiết từ đầu đến cuối.

Cấu trúc của một công cụ#

Gồm hai phần:

1. Schema — định nghĩa hàm theo kiểu OpenAI ({type: "function", function: {name, description, parameters}}) cho LLM biết công cụ làm gì và nhận những đối số nào.
2. Điểm cuối — URL mà máy chủ ThunderPhone gọi khi LLM quyết định sử dụng công cụ. Yêu cầu là JSON POST với các đối số do LLM chọn trong phần thân.

1. Chọn chiến lược lưu trữ#

Hướng dẫn này sử dụng phương án tích hợp đã lưu.

2. Tạo tích hợp#

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

Lưu id được trả về (một UUID).

3. Kiểm tra điểm cuối trong sandbox#

Trước khi liên kết tích hợp với một tác nhân AI, hãy gửi một yêu cầu đã ký từ máy chủ ThunderPhone để xác nhận kết nối:

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

Kiểm tra này cũng tăng cường các biện pháp bảo vệ SSRF của ThunderPhone — các yêu cầu đến localhost hoặc dải IP riêng tư sẽ trả về 400 code=url_not_allowed.

4. Liên kết integration với tác nhân AI#

Gắn qua integration_ids khi bạn tạo hoặc cập nhật một tác nhân AI:

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

Bạn có thể liên kết nhiều integration với một tác nhân AI. Prompt của tác nhân AI có thể tham chiếu chúng theo tên — "dùng get_weather khi người gọi hỏi về điều kiện thời tiết" — hoặc có thể ngầm nhận diện chúng từ mô tả schema.

5. Triển khai endpoint#

Khi tác nhân AI gọi công cụ, ThunderPhone gửi một POST có chữ ký đến endpoint_url của bạn:

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

Máy chủ của bạn phản hồi bằng JSON, sau đó được chuyển lại cho LLM:

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

LLM tiếp nhận phản hồi đó và nói bản tóm tắt dễ hiểu cho người gọi.

6. Kiểm thử quy trình#

Chạy một phiên micro với tác nhân AI và đặt câu hỏi mà công cụ của bạn xử lý ("Thời tiết ở 94110 thế nào?"). Bản chép lời của cuộc gọi hiển thị toàn bộ quy trình:

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

Bạn có thể truy xuất nội dung này qua GET /v1/calls/{call_id}/transcript; luồng sự kiện thô (có thời gian của từng mục và độ lệch âm thanh) nằm tại GET /v1/calls/{call_id}/history.

Các lỗi thường gặp#

Bước tiếp theo#