Developer cookbook

Buat integrasi alat (API)

Biarkan agen Anda memanggil API Anda di tengah percakapan — mencari basis data, membuat tiket, memeriksa pesanan.

Sebuah integrasi alat adalah endpoint HTTP yang dapat digunakan kembali yang dapat dipanggil agen selama panggilan. Anda memberikan ThunderPhone deskripsi skema JSON untuk alat tersebut beserta URL endpoint; agen memutuskan kapan akan memanggilnya berdasarkan percakapan, lalu ThunderPhone membuat permintaan HTTP keluar dari servernya dan mengembalikan respons kepada agen.

Panduan ini menjelaskan pembuatan alat pencarian cuaca dari awal hingga akhir.

Anatomi alat#

Dua bagian:

1. Skema — definisi fungsi bergaya OpenAI ({type: "function", function: {name, description, parameters}}) yang memberi tahu LLM fungsi alat tersebut dan argumen yang diterimanya.
2. Endpoint — URL yang dipanggil server ThunderPhone saat LLM memutuskan untuk menggunakan alat tersebut. Permintaannya berupa JSON POST dengan argumen yang dipilih LLM sebagai isi permintaan.

1. Pilih strategi penyimpanan#

Panduan ini menggunakan jalur integrasi tersimpan.

2. Buat integrasi#

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

Simpan id yang dikembalikan (sebuah UUID).

3. Uji endpoint di sandbox#

Sebelum menautkan integrasi ke agen, kirim permintaan bertanda tangan dari server ThunderPhone untuk mengonfirmasi konektivitas:

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

Pengujian ini juga memperkuat pengaman SSRF ThunderPhone — permintaan ke localhost atau rentang IP privat mengembalikan 400 code=url_not_allowed.

4. Tautkan integrasi ke agen#

Lampirkan melalui integration_ids saat Anda membuat atau memperbarui agen:

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

Anda dapat menautkan banyak integrasi ke satu agen. Prompt agen dapat merujuknya berdasarkan nama — "gunakan get_weather saat penelepon bertanya tentang kondisi cuaca" — atau agen dapat menemukannya secara implisit dari deskripsi skema.

5. Implementasikan endpoint#

Saat agen memanggil alat, ThunderPhone mengirim POST yang ditandatangani ke endpoint_url Anda:

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

Server Anda merespons dengan JSON yang diteruskan kembali ke LLM:

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

LLM menerima respons tersebut dan menyampaikan ringkasan yang natural kepada penelepon.

6. Uji alurnya#

Jalankan sesi mikrofon terhadap agen dan ajukan pertanyaan yang ditangani alat Anda ("Bagaimana cuaca di 94110?"). Transkrip panggilan menampilkan perjalanan bolak-balik lengkap:

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

Anda dapat mengambilnya melalui GET /v1/calls/{call_id}/transcript; stream peristiwa mentah (dengan waktu per entri dan offset audio) tersedia di GET /v1/calls/{call_id}/history.

Hal yang sering terlewat#

Langkah berikutnya#