Agent Araçları — Handoff, Webhook ve Entegrasyon 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:

Handoff (Aktarma)

Çağrıyı başka bir AI Agent’a bağlam mühendisliği ile aktarma

Özel Fonksiyon

HTTP webhook üzerinden özel iş mantığı çalıştırma

Çağrı Yönlendirme

Çağrıyı telefon numarası veya SIP adresine aktarma

Bilgi Sorgulama

Bilgi bankasından veri sorgulama

Çağrı Sonlandırma

Görüşmeyi programatik olarak sonlandırma

Sesli Mesaj

Sesli mesaj algılama ve yönetimi

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ğidir. Çağrı aktarılırken hedef agent’a iletilecek konuşma bağlamını kontrol edebilirsiniz:

Tüm Mesajlar
Bağlam Yok
Kullanıcı ve Asistan Mesajları
Son N Mesaj

Tip: allGö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

Tip: noneHedef 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

Tip: userAndAssistantMessagesSadece 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

Tip: lastNMessagesGö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üzdeYapılandırma: Mesaj sayısını belirtin (örn: son 10 mesaj)

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:

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

Agent Karar Verir

Agent, konuşma bağlamına göre özel fonksiyonu çağırmaya karar verir

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

Webhook Çağrılır

Platform, yapılandırılmış webhook URL’sine HTTP isteği gönderir

Yanıt İşlenir

Webhook’tan gelen yanıt agent’a iletilir ve agent müşteriye bilgi verir

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

Ö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ı

Randevu Yönetimi

Action: checkAvailability, createAppointment

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

Sipariş Takibi

Action: checkOrderStatus, getTrackingInfo

Müşteri sipariş durumu sorar
Agent sipariş numarası ile webhook’a istek atar
Kargo takip bilgisini müşteriye iletir

Ödeme İşlemleri

Action: createPaymentLink, checkBalance

Sipariş tutarı hesaplanır
Ödeme linki oluşturulur
Müşteriye SMS ile gönderilir

CRM Entegrasyonu

Action: getCRMData, createTicket

Müşteri bilgisi CRM’den çekilir
Kişiselleştirilmiş hizmet verilir
Destek talebi oluşturulur

Dahili Araçlar

Platform ile birlikte gelen hazır araçlar:

Çağrı Yönlendirme (Transfer Call)
Bilgi Sorgulama (Query)
Çağrı Sonlandırma (End Call)
Sesli Mesaj (Voicemail)

Ç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

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

Katalog Sayfası

Ayarlar > Kataloglar veya Araçlar > Kataloglar

Yeni Katalog

Yeni Katalog Oluştur
Katalog Adı: Örn: “Ürün Kataloğu”
Açıklama: “Satış ürünleri listesi”
Oluştur

Ürün Ekleme

Manuel Ekleme:

Ürün Ekle butonu
Ürün Adı, SKU/ID, Fiyat, Açıklama, Stok Durumu
Kaydet

Toplu Ekleme:

Toplu İçe Aktar
CSV template indir
Excel’de doldurun
Upload edin

Agent İlişkilendirme

Agent Düzenleme:

Araçlar sekmesi
Katalog Ayarları
Kullanılacak kataloğu seçin
Kaydet

CSV Format

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

AI Agent oluşturma formu — araç bağlantıları ve fonksiyon ayarları

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

Müşteri Sorusu

Müşteri: "iPhone 15 Pro stokta var mı?"

Agent Karar

Agent, sistem talimatlarına göre uygun aracı çağırmaya karar verir

Araç Çağrısı

{
  "action": "checkStock",
  "input01": "IP15P"
}

Webhook Yanıtı

{
  "success": true,
  "inStock": true,
  "availableQuantity": 15
}

Agent Cevabı

Agent: "Evet, iPhone 15 Pro stoklarımızda mevcut.
15 adet bulunuyor."

Araç Güvenliği

API Key Yönetimi

API key’leri güvenli saklayın
Environment variables kullanın
Hard-code etmeyin

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ı

✅ 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

Özel Fonksiyon Aracı

✅ 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

Araç Tasarımı

✅ 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

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

Araç Çağrılmıyor

Sebep: Agent ne zaman kullanacağını bilmiyorÇözüm:

Sistem talimatını güncelleyin
Araç kullanımını açık bir şekilde belirtin
Test görüşmesi yapın

Handoff Aktarma Başarısız

Sebep: Hedef agent yapılandırması hatalıÇözüm:

Hedef agent’ın aktif olduğunu kontrol edin
Agent ID ve platform referans ID’sinin doğru olduğunu doğrulayın
Bağlam mühendisliği tipinin geçerli olduğunu kontrol edin
“Son N Mesaj” tipinde mesaj sayısının en az 1 olduğunu doğrulayın

Özel Fonksiyon Hata Veriyor

Sebep: Webhook endpoint çalışmıyor veya hatalıÇözüm:

Webhook URL’sinin erişilebilir olduğunu kontrol edin
HTTP yanıt kodunu kontrol edin (200 OK beklenir)
Yanıt formatının JSON olduğunu doğrulayın
Authentication bilgilerini kontrol edin

Katalog Boş

Sebep: Ürünler eklenmemiş veya agent ile ilişkilendirilmemişÇözüm:

Katalog’a ürün ekleyin
Agent ayarlarından katalog seçin
Kaydedin ve test edin

Yanlış Bilgi Veriyor

Sebep: Katalog güncel değilÇözüm:

Katalog’u güncelleyin
Fiyat ve stok durumlarını kontrol edin
Agent’ı yeniden test edin

Sık Sorulan Sorular

Kaç araç ekleyebilirim?

Teknik limit yok, ancak 5-10 arası ideal. Çok fazla araç agent’ı karıştırabilir.

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.

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

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.

Bir agent birden fazla katalog kullanabilir mi?

Şu anda bir agent bir katalog kullanabilir.

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.

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

İlgili Makaleler

AI Agent Oluşturma

Yeni AI Agent oluşturma ve yapılandırma

Gelişmiş Yapılandırma

Eskalasyon, performans ve davranış optimizasyonu

Yapılandırılmış Çıktılar

JSON formatında veri toplama

Bilgi Bankası Yönetimi

Agent bilgi kaynaklarını yönetme

​Genel Bakış

​Araç Tipleri

Handoff (Aktarma)

Özel Fonksiyon

Çağrı Yönlendirme

Bilgi Sorgulama

Çağrı Sonlandırma

Sesli Mesaj

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

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

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

​Handoff Hedef Tipleri

​Handoff Mesaj Kontrolleri

​Özel Fonksiyon Aracı (Custom Function)

​Çalışma Prensibi

​Özel Fonksiyon Mesaj Kontrolleri

​Kullanım Senaryoları

​Dahili Araçlar

​Katalog Yönetimi

​Katalog Nedir?

​Katalog Oluşturma

​CSV Format

​Kategori ve Alt Kategori

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

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

​Araç Güvenliği

​API Key Yönetimi

​Yetkilendirme

​Rate Limiting

​İpuçları ve En İyi Uygulamalar

​Handoff Aracı

​Özel Fonksiyon Aracı

​Araç Tasarımı

​Sistem Talimatı Uyumu

​Sorun Giderme

​Sık Sorulan Sorular

​İlgili Makaleler

AI Agent Oluşturma

Gelişmiş Yapılandırma

Yapılandırılmış Çıktılar

Bilgi Bankası Yönetimi

Genel Bakış

Araç Tipleri

Handoff Aracı (Çağrı Aktarma)

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

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

Handoff Hedef Tipleri

Handoff Mesaj Kontrolleri

Özel Fonksiyon Aracı (Custom Function)

Çalışma Prensibi

Özel Fonksiyon Mesaj Kontrolleri

Kullanım Senaryoları

Dahili Araçlar

Katalog Yönetimi

Katalog Nedir?

Katalog Oluşturma

CSV Format

Kategori ve Alt Kategori

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

Agent Araç Çağırma Süreci

Araç Güvenliği

API Key Yönetimi

Yetkilendirme

Rate Limiting

İpuçları ve En İyi Uygulamalar

Handoff Aracı

Özel Fonksiyon Aracı

Araç Tasarımı

Sistem Talimatı Uyumu

Sorun Giderme

Sık Sorulan Sorular

İlgili Makaleler