> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Bir araç entegrasyonu oluşturun (API) > Ajanınızın görüşme sırasında API'lerinizi çağırmasını sağlayın — veritabanında arama yapın, talep oluşturun, sipariş sorgulayın. 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](/tr/guides/concepts). 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: 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 Tek seferlik bir aracı ajanın `tools` dizisine ekleyin. Basittir, ancak yeniden kullanılamaz. Aracı yeniden kullanılabilir bir [entegrasyon](/api-reference/integrations) 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 ```bash theme={null} 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: ```bash theme={null} 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" } }' ``` ```json Response theme={null} { "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: ```bash theme={null} 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: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Sunucunuz, LLM'ye geri iletilen JSON ile yanıt verir: ```json theme={null} {"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](/tr/guides/verify-webhook-signatures). ## 6. Akışı test edin Ajana karşı bir [mikrofon oturumu](/api-reference/mic-sessions) ç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: ```json theme={null} { "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`](/api-reference/calls#get-transcript) aracılığıyla alabilirsiniz; giriş başına zamanlama ve ses kaydırmaları içeren ham olay akışı [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history) adresindedir. ## Sık karşılaşılan sorunlar 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."). 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. 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. 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`](/api-reference/integrations#version-history) 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 CRUD, aktarım, sürüm geçmişi. Tam JSON şeması dil bilgisi ve imzalı uç nokta sözleşmesi. Webhook imza modelini araç uç noktalarına uygulayın. Bir araç çağrısının tam gidiş dönüşünü inceleyin.