Buat integrasi alat (API)

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.

Dasbor mencakup sebagian besar kebutuhan alat tanpa API ini: Koneksi → Aplikasi menghubungkan Slack, HubSpot, Salesforce, Google Calendar, Google Sheets, dan Cal.com dalam beberapa klik OAuth; Koneksi → API mengubah API HTTP apa pun menjadi tindakan agen (tempel perintah cURL dan wizard AI akan menyusun alat, dengan Test Request bawaan); dan Koneksi → MCP menambahkan server MCP. Lihat Koneksi. Panduan ini membahas API mentah yang mendasari antarmuka API.

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

Anatomi alat

Dua bagian:

Skema — definisi fungsi bergaya OpenAI ({type: "function", function: {name, description, parameters}}) yang memberi tahu LLM fungsi alat tersebut dan argumen yang diterimanya.
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

Inline pada agen

Lampirkan alat sekali pakai ke array tools agen. Sederhana, tetapi tidak dapat digunakan kembali.

Integrasi tersimpan

Simpan alat sebagai integrasi yang dapat digunakan kembali dan tautkan dari banyak agen. Direkomendasikan untuk apa pun yang digunakan lebih dari sekali.

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).

Luangkan upaya sungguh-sungguh untuk description alat dan setiap parameter. LLM menggunakan string ini saat runtime untuk memutuskan apakah dan bagaimana memanggil alat tersebut. Deskripsi yang samar → panggilan alat yang samar.

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

Response

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

Tanda tangan dihitung berdasarkan isi permintaan mentah menggunakan secret yang sama dengan endpoint webhook Anda. Verifikasi tanda tangan tersebut — endpoint alat dapat diakses dari internet dan menghadapi risiko pemalsuan yang sama seperti webhook. Lihat Verifikasi tanda tangan webhook.

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

Agen tidak pernah memanggil alat

LLM memutuskan berdasarkan deskripsi alat. Jika pertanyaan penelepon tidak sesuai dengan deskripsi, model tidak akan memanggil alat. Perjelas deskripsinya (tambahkan sinonim dan frasa umum) atau sebutkan secara eksplisit dalam Prompt agen (“Saat penelepon bertanya tentang cuaca, gunakan get_weather.”).

Alat mengembalikan terlalu banyak data

Respons di atas 6 kB dipotong dalam pratinjau transkrip. Kembalikan hanya kolom yang dibutuhkan LLM — bukan seluruh baris data Anda.

Timeout

Endpoint alat memiliki timeout default 10 detik. Jika Anda memerlukan waktu lebih lama, tangani secara asinkron: kembalikan {"status": "pending", "request_id": "..."} dan tampilkan hasilnya melalui pemanggilan alat terpisah.

Pembuatan versi

Setiap PATCH integrasi membuat revisi baru. Periksa GET /v1/integrations/{id}/versions untuk melihat siapa yang mengubah apa. Jika Anda merusak skema sebuah alat, Anda dapat melakukan rollback secara manual dengan menerapkan kembali snapshot lama melalui PATCH.

Langkah berikutnya

Referensi integrasi

CRUD, transfer, riwayat versi.

Spesifikasi Function Tools

Tata bahasa skema JSON lengkap dan kontrak endpoint bertanda tangan.

Verifikasi tanda tangan

Terapkan pola tanda tangan webhook ke endpoint tool.

API transkrip + riwayat

Periksa seluruh alur bolak-balik panggilan tool.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Buat integrasi alat (API)

Anatomi alat

1. Pilih strategi penyimpanan

Inline pada agen

Integrasi tersimpan

2. Buat integrasi

3. Uji endpoint di sandbox

4. Tautkan integrasi ke agen

5. Implementasikan endpoint

6. Uji alurnya

Hal yang sering terlewat

Langkah berikutnya

Referensi integrasi

Spesifikasi Function Tools

Verifikasi tanda tangan

API transkrip + riwayat

​Anatomi alat

​1. Pilih strategi penyimpanan

Inline pada agen

Integrasi tersimpan

​2. Buat integrasi

​3. Uji endpoint di sandbox

​4. Tautkan integrasi ke agen

​5. Implementasikan endpoint

​6. Uji alurnya

​Hal yang sering terlewat

​Langkah berikutnya

Referensi integrasi

Spesifikasi Function Tools

Verifikasi tanda tangan

API transkrip + riwayat

Anatomi alat

1. Pilih strategi penyimpanan

2. Buat integrasi

3. Uji endpoint di sandbox

4. Tautkan integrasi ke agen

5. Implementasikan endpoint

6. Uji alurnya

Hal yang sering terlewat

Langkah berikutnya