> ## Documentation Index
> Fetch the complete documentation index at: https://aiagenttr.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Araçları — Handoff, Webhook ve Entegrasyon Rehberi

> AI Agent için Handoff ve özel fonksiyon araçları tanımlayın. Çağrı aktarma, HTTP webhook entegrasyonu ve otomatik araç talimatı oluşturma rehberi.

## Genel Bakış

Agent araçları, AI Agent'ınızın görüşme sırasında dış sistemlerle etkileşim kurmasını, çağrıları aktarmasını ve işlemler yapmasını sağlar. Araçlar sayesinde agent, sadece konuşmakla kalmaz, aynı zamanda aksiyonlar da alabilir.

## Araç Tipleri

Platform şu araç tiplerini destekler:

<CardGroup cols={3}>
  <Card title="Handoff (Aktarma)" icon="arrow-right-arrow-left">
    Çağrıyı başka bir AI Agent'a bağlam mühendisliği ile aktarma
  </Card>

  <Card title="Özel Fonksiyon" icon="code">
    HTTP webhook üzerinden özel iş mantığı çalıştırma
  </Card>

  <Card title="Çağrı Yönlendirme" icon="phone-arrow-right">
    Çağrıyı telefon numarası veya SIP adresine aktarma
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="Bilgi Sorgulama" icon="database">
    Bilgi bankasından veri sorgulama
  </Card>

  <Card title="Çağrı Sonlandırma" icon="phone-slash">
    Görüşmeyi programatik olarak sonlandırma
  </Card>

  <Card title="Sesli Mesaj" icon="voicemail">
    Sesli mesaj algılama ve yönetimi
  </Card>
</CardGroup>

## Handoff Aracı (Çağrı Aktarma)

Handoff aracı, bir AI Agent'ın görüşmeyi **başka bir AI Agent'a** aktarmasını sağlar. Aktarma sırasında konuşma bağlamının ne kadarının hedef agent'a iletileceği yapılandırılabilir.

### Bağlam Mühendisliği (Context Engineering)

Handoff aracının en güçlü özelliği **bağlam mühendisliği**dir. Çağrı aktarılırken hedef agent'a iletilecek konuşma bağlamını kontrol edebilirsiniz:

<Tabs>
  <Tab title="Tüm Mesajlar">
    **Tip:** `all`

    Görüşmedeki tüm mesajlar hedef agent'a iletilir.

    ✅ **Kullanım:** Hedef agent'ın konuşmanın tamamını bilmesi gerektiğinde

    ❌ **Dikkat:** Uzun görüşmelerde bağlam penceresi dolabilir
  </Tab>

  <Tab title="Bağlam Yok">
    **Tip:** `none`

    Hedef agent'a hiçbir konuşma bağlamı iletilmez. Hedef agent sıfırdan başlar.

    ✅ **Kullanım:** Tamamen farklı bir konuda hizmet verecek agent'a aktarırken

    ❌ **Dikkat:** Müşteri bilgilerini tekrar sormak gerekebilir
  </Tab>

  <Tab title="Kullanıcı ve Asistan Mesajları">
    **Tip:** `userAndAssistantMessages`

    Sadece kullanıcı (müşteri) ve asistan (agent) mesajları iletilir. Sistem mesajları ve araç çağrıları hariç tutulur.

    ✅ **Kullanım:** Temiz bir konuşma bağlamı iletmek istediğinizde
  </Tab>

  <Tab title="Son N Mesaj">
    **Tip:** `lastNMessages`

    Görüşmenin yalnızca son N mesajı hedef agent'a iletilir. Mesaj sayısı yapılandırılabilir (en az 1).

    ✅ **Kullanım:** Son konuşma bağlamını yeterli gördüğünüzde

    **Yapılandırma:** Mesaj sayısını belirtin (örn: son 10 mesaj)
  </Tab>
</Tabs>

### Değişken Çıkarma (Variable Extraction)

Handoff aracı, aktarma öncesinde görüşmeden belirli bilgileri **şema bazlı** olarak çıkarabilir. Bu bilgiler hedef agent'a değişken olarak iletilir.

**Örnek Şema:**

```json theme={null}
{
  "type": "object",
  "properties": {
    "musteriAdi": {
      "type": "string",
      "description": "Müşterinin tam adı"
    },
    "siparisNumarasi": {
      "type": "string",
      "description": "Sipariş numarası"
    },
    "sorunOzeti": {
      "type": "string",
      "description": "Müşterinin yaşadığı sorunun kısa özeti"
    }
  }
}
```

Bu şema sayesinde aktarma öncesinde agent, konuşmadan ilgili bilgileri otomatik olarak çıkarır ve hedef agent'a yapılandırılmış veri olarak iletir.

### Handoff Hedef Tipleri

| Hedef Tipi               | Açıklama                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| **Assistant (AI Agent)** | Platformdaki başka bir AI Agent'a aktarma. Agent ID ve platform referans ID'si gereklidir. |
| **Dynamic (Dinamik)**    | Çalışma zamanında belirlenen bir hedefe aktarma.                                           |

### Handoff Mesaj Kontrolleri

Handoff aracı için aşağıdaki mesaj alanları yapılandırılabilir:

| Alan                             | Açıklama                                             |
| -------------------------------- | ---------------------------------------------------- |
| `messageToCustomer`              | Aktarma başlatılırken müşteriye söylenecek mesaj     |
| `waitForMessageToBeSpoken`       | Mesajın tamamen söylenmesi beklensin mi              |
| `messageToCustomerOnDelayed`     | Aktarma geciktiğinde söylenecek mesaj                |
| `delayInMsOnDelayed`             | Gecikme mesajının tetikleneceği süre (100-12.000 ms) |
| `messageToCustomerOnFailed`      | Aktarma başarısız olduğunda söylenecek mesaj         |
| `endTheCallAfterMessageIsSpoken` | Başarısız mesajından sonra arama sonlandırılsın mı   |

## Özel Fonksiyon Aracı (Custom Function)

Özel fonksiyon aracı, AI Agent'ın görüşme sırasında **HTTP webhook** üzerinden özel iş mantığı çalıştırmasını sağlar. Platform, tanımlanan webhook URL'sine istek göndererek dış sistemlerle entegrasyon kurar.

### Çalışma Prensibi

<Steps>
  <Step title="Agent Karar Verir">
    Agent, konuşma bağlamına göre özel fonksiyonu çağırmaya karar verir
  </Step>

  <Step title="Parametreler Hazırlanır">
    Agent, aşağıdaki sabit parametre yapısını doldurur:

    | Parametre          | Tip    | Zorunlu | Açıklama                     |
    | ------------------ | ------ | ------- | ---------------------------- |
    | `action`           | string | ✅ Evet  | Çalıştırılacak aksiyonun adı |
    | `input01`          | string | Hayır   | Birinci girdi                |
    | `input02`          | string | Hayır   | İkinci girdi                 |
    | `input03`          | string | Hayır   | Üçüncü girdi                 |
    | `sensitiveInput01` | string | Hayır   | Birinci hassas girdi         |
    | `sensitiveInput02` | string | Hayır   | İkinci hassas girdi          |
    | `sensitiveInput03` | string | Hayır   | Üçüncü hassas girdi          |
  </Step>

  <Step title="Webhook Çağrılır">
    Platform, yapılandırılmış webhook URL'sine HTTP isteği gönderir
  </Step>

  <Step title="Yanıt İşlenir">
    Webhook'tan gelen yanıt agent'a iletilir ve agent müşteriye bilgi verir
  </Step>
</Steps>

<Info>
  **Hassas Girdiler:** `sensitiveInput01-03` alanları, kredi kartı numarası, TC kimlik numarası gibi hassas bilgiler için kullanılır. Bu alanlar loglamada maskelenir.
</Info>

### Özel Fonksiyon Mesaj Kontrolleri

Özel fonksiyon aracı için de handoff aracıyla aynı mesaj kontrolleri yapılandırılabilir:

| Alan                             | Açıklama                                             |
| -------------------------------- | ---------------------------------------------------- |
| `messageToCustomer`              | Fonksiyon çağrılırken müşteriye söylenecek mesaj     |
| `waitForMessageToBeSpoken`       | Mesajın tamamen söylenmesi beklensin mi              |
| `messageToCustomerOnDelayed`     | İşlem geciktiğinde söylenecek mesaj                  |
| `delayInMsOnDelayed`             | Gecikme mesajının tetikleneceği süre (100-12.000 ms) |
| `messageToCustomerOnFailed`      | İşlem başarısız olduğunda söylenecek mesaj           |
| `endTheCallAfterMessageIsSpoken` | Başarısız mesajından sonra arama sonlandırılsın mı   |

### Kullanım Senaryoları

<AccordionGroup>
  <Accordion title="Randevu Yönetimi">
    **Action:** `checkAvailability`, `createAppointment`

    * Müşteri randevu tarihi sorar
    * Agent takvimden müsait saatleri kontrol eder
    * Randevu oluşturur ve onay verir
  </Accordion>

  <Accordion title="Sipariş Takibi">
    **Action:** `checkOrderStatus`, `getTrackingInfo`

    * Müşteri sipariş durumu sorar
    * Agent sipariş numarası ile webhook'a istek atar
    * Kargo takip bilgisini müşteriye iletir
  </Accordion>

  <Accordion title="Ödeme İşlemleri">
    **Action:** `createPaymentLink`, `checkBalance`

    * Sipariş tutarı hesaplanır
    * Ödeme linki oluşturulur
    * Müşteriye SMS ile gönderilir
  </Accordion>

  <Accordion title="CRM Entegrasyonu">
    **Action:** `getCRMData`, `createTicket`

    * Müşteri bilgisi CRM'den çekilir
    * Kişiselleştirilmiş hizmet verilir
    * Destek talebi oluşturulur
  </Accordion>
</AccordionGroup>

## Dahili Araçlar

Platform ile birlikte gelen hazır araçlar:

<Tabs>
  <Tab title="Çağrı Yönlendirme (Transfer Call)">
    Çağrıyı bir telefon numarasına veya SIP adresine yönlendirir.

    * Birden fazla hedef yapılandırılabilir
    * Her hedef için koşul tanımlanabilir
    * Mesaj kontrolleri ile müşteri bilgilendirilir
  </Tab>

  <Tab title="Bilgi Sorgulama (Query)">
    Bilgi bankasından veri sorgular.

    * Bilgi bankası dokümanlarından cevap arar
    * Birden fazla bilgi bankası bağlanabilir
    * Sonuçları müşteriye doğal dilde iletir
  </Tab>

  <Tab title="Çağrı Sonlandırma (End Call)">
    Görüşmeyi programatik olarak sonlandırır.

    * Agent karar verdiğinde aramayı bitirir
    * Sonlandırma mesajı yapılandırılabilir
  </Tab>

  <Tab title="Sesli Mesaj (Voicemail)">
    Sesli mesaj algılama ve yönetimi.

    * Otomatik sesli mesaj kutusu algılama
    * Sesli mesaj bırakma
  </Tab>
</Tabs>

## Katalog Yönetimi

### Katalog Nedir?

**Catalog:** Agent'a önceden yüklenmiş ürün/hizmet listesi.

**Kullanım:**

* Agent, katalogdaki ürünleri bilir
* Fiyat sorularına cevap verebilir
* Stok durumunu kontrol edebilir
* Sipariş alabilir

### Katalog Oluşturma

<Steps>
  <Step title="Katalog Sayfası">
    **Ayarlar** > **Kataloglar** veya **Araçlar** > **Kataloglar**
  </Step>

  <Step title="Yeni Katalog">
    1. **Yeni Katalog Oluştur**
    2. **Katalog Adı:** Örn: "Ürün Kataloğu"
    3. **Açıklama:** "Satış ürünleri listesi"
    4. **Oluştur**
  </Step>

  <Step title="Ürün Ekleme">
    **Manuel Ekleme:**

    1. **Ürün Ekle** butonu
    2. Ürün Adı, SKU/ID, Fiyat, Açıklama, Stok Durumu
    3. **Kaydet**

    **Toplu Ekleme:**

    1. **Toplu İçe Aktar**
    2. CSV template indir
    3. Excel'de doldurun
    4. Upload edin
  </Step>

  <Step title="Agent İlişkilendirme">
    **Agent Düzenleme:**

    1. **Araçlar** sekmesi
    2. **Katalog Ayarları**
    3. Kullanılacak kataloğu seçin
    4. **Kaydet**
  </Step>
</Steps>

### CSV Format

```csv theme={null}
name,sku,price,description,inStock
iPhone 15 Pro,IP15P,45000,256GB Model,true
MacBook Air M2,MBA-M2,35000,8GB RAM 256GB SSD,true
AirPods Pro,APP2,9000,2. Nesil,false
```

<Frame>
  <img src="https://mintcdn.com/aiagenttr/DXCGeoE5pY0ImAYy/images/agent-create-form.png?fit=max&auto=format&n=DXCGeoE5pY0ImAYy&q=85&s=2435686823a84f587ab539b90ff15a10" alt="AI Agent oluşturma formu — araç bağlantıları ve fonksiyon ayarları" width="1528" height="943" data-path="images/agent-create-form.png" />
</Frame>

### Kategori ve Alt Kategori

**Hiyerarşi:**

```
Elektronik
  ├─ Telefonlar
  │   ├─ iPhone
  │   └─ Samsung
  └─ Bilgisayarlar
      ├─ Laptop
      └─ Masaüstü
```

## Araç Çağrısı ve Yanıt

### Agent Araç Çağırma Süreci

<Steps>
  <Step title="Müşteri Sorusu">
    ```
    Müşteri: "iPhone 15 Pro stokta var mı?"
    ```
  </Step>

  <Step title="Agent Karar">
    Agent, sistem talimatlarına göre uygun aracı çağırmaya karar verir
  </Step>

  <Step title="Araç Çağrısı">
    ```json theme={null}
    {
      "action": "checkStock",
      "input01": "IP15P"
    }
    ```
  </Step>

  <Step title="Webhook Yanıtı">
    ```json theme={null}
    {
      "success": true,
      "inStock": true,
      "availableQuantity": 15
    }
    ```
  </Step>

  <Step title="Agent Cevabı">
    ```
    Agent: "Evet, iPhone 15 Pro stoklarımızda mevcut.
    15 adet bulunuyor."
    ```
  </Step>
</Steps>

## Araç Güvenliği

<Warning>
  ### API Key Yönetimi

  * API key'leri güvenli saklayın
  * Environment variables kullanın
  * Hard-code etmeyin
</Warning>

### Yetkilendirme

* Agent sadece yetkili işlemleri yapabilmeli
* Ödeme işlemleri için ek doğrulama
* Kritik işlemler için onay mekanizması

### Rate Limiting

* API'nize rate limit koyun
* Agent çok fazla istek atarsa engelleyin
* Abuse koruması

## İpuçları ve En İyi Uygulamalar

### Handoff Aracı

<Tip>
  * ✅ Bağlam mühendisliği tipini kullanım senaryosuna göre seçin
  * ✅ Uzun görüşmelerde "Son N Mesaj" tercih edin
  * ✅ Değişken çıkarma ile kritik bilgileri aktarın
  * ✅ Aktarma mesajını her zaman yapılandırın
  * ❌ "Tüm Mesajlar" seçeneğini çok uzun görüşmelerde kullanmayın
  * ❌ "Bağlam Yok" seçeneğini müşteri bilgisi gerektiğinde kullanmayın
</Tip>

### Özel Fonksiyon Aracı

<Tip>
  * ✅ `action` parametresini açıklayıcı isimlendirin (örn: `checkStock`, `createOrder`)
  * ✅ Hassas bilgiler için `sensitiveInput` alanlarını kullanın
  * ✅ Webhook yanıtınızda açıklayıcı hata mesajları döndürün
  * ✅ Gecikme mesajını yapılandırarak müşteriyi bilgilendirin
  * ❌ Webhook'ta uzun süren işlemler yapmayın (timeout riski)
  * ❌ Hassas verileri normal input alanlarında göndermeyin
</Tip>

### Araç Tasarımı

<Tip>
  * ✅ Tek bir işe odaklanın (Single Responsibility)
  * ✅ Açıklayıcı isim kullanın
  * ✅ Parametreleri minimumda tutun
  * ✅ Hata durumlarını iyi yönetin
  * ❌ Çok karmaşık araçlar yapmayın
  * ❌ Çok fazla parametre eklemeyin
</Tip>

### Sistem Talimatı Uyumu

Agent'ın araçları doğru zamanda kullanması için sistem talimatlarında açık yönergeler verin:

**Kötü Örnek:**

```
Araç ekledim ama sistem talimatında belirtmedim.
Agent ne zaman kullanacağını bilmiyor.
```

**İyi Örnek:**

```
Müşteri ürün stoku sorarsa checkStock aksiyonunu kullan.
Müşteri sipariş vermek isterse createOrder aksiyonunu kullan.
Müşteri teknik destek istiyorsa çağrıyı Teknik Destek Agent'ına aktar.
```

## Sorun Giderme

<AccordionGroup>
  <Accordion title="Araç Çağrılmıyor">
    **Sebep:** Agent ne zaman kullanacağını bilmiyor

    **Çözüm:**

    1. Sistem talimatını güncelleyin
    2. Araç kullanımını açık bir şekilde belirtin
    3. Test görüşmesi yapın
  </Accordion>

  <Accordion title="Handoff Aktarma Başarısız">
    **Sebep:** Hedef agent yapılandırması hatalı

    **Çözüm:**

    1. Hedef agent'ın aktif olduğunu kontrol edin
    2. Agent ID ve platform referans ID'sinin doğru olduğunu doğrulayın
    3. Bağlam mühendisliği tipinin geçerli olduğunu kontrol edin
    4. "Son N Mesaj" tipinde mesaj sayısının en az 1 olduğunu doğrulayın
  </Accordion>

  <Accordion title="Özel Fonksiyon Hata Veriyor">
    **Sebep:** Webhook endpoint çalışmıyor veya hatalı

    **Çözüm:**

    1. Webhook URL'sinin erişilebilir olduğunu kontrol edin
    2. HTTP yanıt kodunu kontrol edin (200 OK beklenir)
    3. Yanıt formatının JSON olduğunu doğrulayın
    4. Authentication bilgilerini kontrol edin
  </Accordion>

  <Accordion title="Katalog Boş">
    **Sebep:** Ürünler eklenmemiş veya agent ile ilişkilendirilmemiş

    **Çözüm:**

    1. Katalog'a ürün ekleyin
    2. Agent ayarlarından katalog seçin
    3. Kaydedin ve test edin
  </Accordion>

  <Accordion title="Yanlış Bilgi Veriyor">
    **Sebep:** Katalog güncel değil

    **Çözüm:**

    1. Katalog'u güncelleyin
    2. Fiyat ve stok durumlarını kontrol edin
    3. Agent'ı yeniden test edin
  </Accordion>
</AccordionGroup>

## Sık Sorulan Sorular

<AccordionGroup>
  <Accordion title="Kaç araç ekleyebilirim?">
    Teknik limit yok, ancak 5-10 arası ideal. Çok fazla araç agent'ı karıştırabilir.
  </Accordion>

  <Accordion title="Handoff ile Transfer Call arasındaki fark nedir?">
    **Handoff**: Çağrıyı başka bir **AI Agent'a** aktarır. Bağlam mühendisliği ve değişken çıkarma ile zenginleştirilmiş aktarma sağlar.

    **Transfer Call**: Çağrıyı bir **telefon numarasına veya SIP adresine** aktarır. İnsan temsilcilere yönlendirme için kullanılır.
  </Accordion>

  <Accordion title="Özel fonksiyon aracında kaç girdi parametresi var?">
    Sabit olarak 7 parametre: 1 zorunlu `action` + 3 normal girdi (`input01-03`) + 3 hassas girdi (`sensitiveInput01-03`).
  </Accordion>

  <Accordion title="Araç çağrısı transkriptte görünür mü?">
    Evet, transkript detayında araç çağrıları ve yanıtları görünür.
  </Accordion>

  <Accordion title="Bir agent birden fazla katalog kullanabilir mi?">
    Şu anda bir agent bir katalog kullanabilir.
  </Accordion>

  <Accordion title="Handoff aracında bağlam yok seçersem ne olur?">
    Hedef agent hiçbir konuşma geçmişi almaz ve sıfırdan başlar. Müşteri bilgilerini tekrar sorması gerekebilir.
  </Accordion>

  <Accordion title="Özel fonksiyon aracı için kod yazmam gerekir mi?">
    Evet, webhook endpoint'inizi kendiniz oluşturmanız gerekir. Platform, tanımlanan URL'ye HTTP isteği gönderir. Endpoint'iniz JSON yanıt döndürmelidir.
  </Accordion>
</AccordionGroup>

## İlgili Makaleler

<CardGroup cols={2}>
  <Card title="AI Agent Oluşturma" icon="robot" href="/docs/voice-ai-agents/create-agent">
    Yeni AI Agent oluşturma ve yapılandırma
  </Card>

  <Card title="Gelişmiş Yapılandırma" icon="sliders" href="/docs/voice-ai-agents/advanced-configuration">
    Eskalasyon, performans ve davranış optimizasyonu
  </Card>

  <Card title="Yapılandırılmış Çıktılar" icon="table" href="/docs/voice-ai-agents/structured-outputs">
    JSON formatında veri toplama
  </Card>

  <Card title="Bilgi Bankası Yönetimi" icon="database" href="/docs/voice-ai-agents/knowledge-base-management">
    Agent bilgi kaynaklarını yönetme
  </Card>
</CardGroup>