Bir araç entegrasyonu oluşturun (API)

Bir araç entegrasyonu, bir ajanın görüşme sırasında çağırabileceği yeniden kullanılabilir bir HTTP uç noktasıdır. ThunderPhone’a aracın JSON şeması açıklamasını ve bir uç nokta URL’sini verirsiniz; ajan, görüşmeye göre aracı ne zaman çağıracağına karar verir ve ThunderPhone, sunucularından giden HTTP isteğini yaparak yanıtı ajana döndürür.

Kontrol paneli, bu API’ye gerek kalmadan araç ihtiyaçlarının çoğunu karşılar: Bağlantılar → Uygulamalar, Slack, HubSpot, Salesforce, Google Calendar, Google Sheets ve Cal.com’u birkaç OAuth tıklamasıyla bağlar; Bağlantılar → API’ler, herhangi bir HTTP API’sini bir ajan eylemine dönüştürür (bir cURL komutu yapıştırın; bir yapay zeka sihirbazı, yerleşik bir Test İsteği ile aracı taslak olarak oluşturur); Bağlantılar → MCP ise MCP sunucuları ekler. Bkz. Bağlantılar. Bu kılavuz, API’ler yüzeyinin altındaki ham API’yi açıklar.

Bu kılavuz, uçtan uca bir hava durumu sorgulama aracı oluşturmayı anlatır.

Bir aracın yapısı

İki bölüm vardır:

Şema — LLM’ye aracın ne yaptığını ve hangi bağımsız değişkenleri aldığını bildiren OpenAI tarzı bir işlev tanımı ({type: "function", function: {name, description, parameters}}).
Uç nokta — LLM aracı kullanmaya karar verdiğinde ThunderPhone sunucularının çağırdığı URL. İstek, gövde olarak LLM’nin seçtiği bağımsız değişkenleri içeren bir JSON POST isteğidir.

1. Depolama stratejisi seçin

Ajan üzerinde satır içi

Tek seferlik bir aracı ajanın tools dizisine ekleyin. Basittir, ancak yeniden kullanılamaz.

Kaydedilmiş entegrasyon

Aracı yeniden kullanılabilir bir entegrasyon olarak saklayın ve birçok ajana bağlayın. Birden fazla kez kullanılan her şey için önerilir.

Bu kılavuz, kaydedilmiş entegrasyon yolunu kullanır.

2. Entegrasyonu oluşturun

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

Döndürülen id değerini (bir UUID) kaydedin.

Aracın ve her parametrenin description alanına gerçekten özen gösterin. LLM, aracı çağırıp çağırmayacağına ve nasıl çağıracağına karar vermek için çalışma zamanında bu dizeleri kullanır. Belirsiz açıklamalar → belirsiz araç çağrıları.

3. Uç noktayı korumalı alanda test edin

Entegrasyonu bir ajana bağlamadan önce, bağlantıyı doğrulamak için ThunderPhone sunucularından imzalı bir istek gönderin:

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

Bu test ayrıca ThunderPhone’un SSRF korumalarını güçlendirir — localhost’a veya özel IP aralıklarına yönelik istekler 400 code=url_not_allowed döndürür.

4. Entegrasyonu bir ajana bağlayın

Bir ajan oluştururken veya güncellerken integration_ids aracılığıyla ekleyin:

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

Bir ajana birden çok entegrasyon bağlayabilirsiniz. Ajanın istemi bunlara adlarıyla başvurabilir — “arayan kişi hava koşullarını sorduğunda get_weather kullanın” — veya şema açıklamalarından bunları örtük olarak keşfedebilir.

5. Uç noktayı uygulayın

Ajan aracı çağırdığında ThunderPhone, endpoint_url adresinize imzalı bir POST gönderir:

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

Sunucunuz, LLM’ye geri iletilen JSON ile yanıt verir:

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

LLM bu yanıtı alır ve arayan kişiye anlaşılır bir özet sunar.

İmza, webhook uç noktanızla aynı secret kullanılarak ham istek gövdesi üzerinden hesaplanır. Doğrulayın — araç uç noktaları internete açıktır ve webhook’larla aynı sahtecilik risklerine tabidir. Bkz. Webhook imzalarını doğrulama.

6. Akışı test edin

Ajana karşı bir mikrofon oturumu çalıştırın ve aracınızın işlediği soruyu sorun (“94110’da hava nasıl?”). Aramanın transkripti tam gidiş dönüşü gösterir:

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

Bunu GET /v1/calls/{call_id}/transcript aracılığıyla alabilirsiniz; giriş başına zamanlama ve ses kaydırmaları içeren ham olay akışı GET /v1/calls/{call_id}/history adresindedir.

Sık karşılaşılan sorunlar

Ajan aracı hiç çağırmıyor

LLM, aracın açıklamasına göre karar verir. Arayan kişinin sorusu açıklamayla eşleşmiyorsa model aracı çağırmaz. Açıklamayı netleştirin (yaygın eş anlamlılar ve ifadeler ekleyin) veya ajan isteminde açıkça belirtin (“Arayan kişi hava durumunu sorduğunda get_weather kullanın.”).

Araç çok fazla veri döndürüyor

6 kB üzerindeki yanıtlar transkript önizlemesinde kesilir. Tüm satırınızı değil, yalnızca LLM’nin ihtiyaç duyduğu alanları döndürün.

Zaman aşımları

Araç uç noktalarının varsayılan zaman aşımı 10 saniyedir. Daha uzun bir süreye ihtiyacınız varsa bunu eşzamansız işleyin: {"status": "pending", "request_id": "..."} döndürün ve sonucu ayrı bir araç çağrısı aracılığıyla sunun.

Sürüm oluşturma

Her entegrasyon PATCH işlemi yeni bir revizyon oluşturur. Kimin neyi değiştirdiğini görmek için GET /v1/integrations/{id}/versions inceleyin. Bir aracın şemasını bozarsanız, eski bir anlık görüntüyü PATCH ile geri uygulayarak manuel olarak geri alabilirsiniz.

Sonraki adımlar

Entegrasyonlar referansı

CRUD, aktarım, sürüm geçmişi.

Function Tools spesifikasyonu

Tam JSON şeması dil bilgisi ve imzalı uç nokta sözleşmesi.

İmzaları doğrulama

Webhook imza modelini araç uç noktalarına uygulayın.

Transkript + geçmiş API'si

Bir araç çağrısının tam gidiş dönüşünü inceleyin.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Bir araç entegrasyonu oluşturun (API)

Bir aracın yapısı

1. Depolama stratejisi seçin

Ajan üzerinde satır içi

Kaydedilmiş entegrasyon

2. Entegrasyonu oluşturun

3. Uç noktayı korumalı alanda test edin

4. Entegrasyonu bir ajana bağlayın

5. Uç noktayı uygulayın

6. Akışı test edin

Sık karşılaşılan sorunlar

Sonraki adımlar

Entegrasyonlar referansı

Function Tools spesifikasyonu

İmzaları doğrulama

Transkript + geçmiş API'si

​Bir aracın yapısı

​1. Depolama stratejisi seçin

Ajan üzerinde satır içi

Kaydedilmiş entegrasyon

​2. Entegrasyonu oluşturun

​3. Uç noktayı korumalı alanda test edin

​4. Entegrasyonu bir ajana bağlayın

​5. Uç noktayı uygulayın

​6. Akışı test edin

​Sık karşılaşılan sorunlar

​Sonraki adımlar

Entegrasyonlar referansı

Function Tools spesifikasyonu

İmzaları doğrulama

Transkript + geçmiş API'si

Bir aracın yapısı

1. Depolama stratejisi seçin

2. Entegrasyonu oluşturun

3. Uç noktayı korumalı alanda test edin

4. Entegrasyonu bir ajana bağlayın

5. Uç noktayı uygulayın

6. Akışı test edin

Sık karşılaşılan sorunlar

Sonraki adımlar