Developer cookbook

Bir araç entegrasyonu oluşturun (API)

Ajanınızın görüşme sırasında 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.

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:

1. Ş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}}).
2. 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#

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.

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

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

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#

Sonraki adımlar#