Tools
Tool'lar, agent'ınızın konuşma sırasında yapabildiği işlemlerdir: sipariş sorgulamak, müşteri bulmak, randevu oluşturmak. Agent'ın Tools sayfasında iki tür ekleyebilirsiniz: HTTP isteği (API'nize tek bir çağrı, bir formla kurulur) ve Fonksiyon (birkaç çağrı yapıp hesaplama yapabilen kod). Bu sayfa HTTP tool'larını ve yerleşik tool'ları anlatır. Fonksiyonların kendi sayfası var.
Agent bir tool'u nasıl kullanır
Model her tool'un adını, açıklamasını ve girdilerini görür. Yanıt verirken bir tool'un işe yarayıp yaramayacağına karar verir, girdileri konuşmadan doldurur ve çağrıyı Peki onun yerine yapar. Model sonucu okur, gerekirse başka bir tool çağırır, sonra yanıtı yazar.
API anahtarınızı istek çıkarken Peki ekler. Model onu hiçbir zaman görmez, tarayıcı da görmez.
HTTP tool ekleme
- Agent'ı açın ve Tools sayfasına gidin.
- Listenin altındaki HTTP isteği'ne tıklayın. Yeni tool adlı bir tool açılır.
- Başlık, AI'ın gördüğü açıklama, İstek (yöntem ve URL) ve Girdiler alanlarını doldurun.
- API'niz anahtar istiyorsa Gelişmiş — API anahtarı, başlıklar, yanıt alanları, zaman aşımı bölümünü açın ve bir anahtar seçin.
- Gerçek bir çağrı yapmak ve AI'ın gördüğü sonucu kontrol etmek için Dene'yi kullanın.
- Agent'ı yayınlayın. Tool'lar taslağın parçasıdır: müşteriler yeni tool'u ancak yayınladıktan sonra kullanır. Test paneli taslağı hemen kullanır.
Sorunlu bir tool, sorunu kartında açıkça gösterir (örneğin API adresini girin (https://…)). Siz düzeltene kadar taslak kaydedilmez.
Tool'u API dokümanından Copilot'a da kurdurabilirsiniz. Dokümanı okur, tool'u oluşturur ve gerçekçi girdilerle test eder.
Tool ayarları
Temel bilgiler
| Ayar | Ne işe yarar | Sınır / varsayılan |
|---|---|---|
| Başlık | Peki panelinde insanların gördüğü ad. | Zorunlu, en fazla 80 karakter |
| AI'ın kullandığı ad | Tool'un model için adı, örneğin siparis_durumu. Siz değiştirmediğiniz sürece başlıktan doldurulur (Türkçe karakterler sadeleşir: "Sipariş durumu" → siparis_durumu). | Küçük harf, rakam ve _, harfle başlar, en fazla 64 karakter. Agent'ın tool ve fonksiyonları arasında benzersiz. |
| AI'ın gördüğü açıklama | Tool'un ne zaman kullanılacağı. Model yalnızca buna bakarak karar verir; net yazın. | Zorunlu, en fazla 1.000 karakter |
İyi bir açıklama tool'un ne yaptığını, ne zaman kullanılacağını ve neye ihtiyaç duyduğunu söyler: "Müşteri sipariş numarası verdiğinde siparişin nerede olduğunu sorgular. Sipariş numarası (5–8 hane) gerekir."
İstek
| Ayar | Ne işe yarar | Varsayılan |
|---|---|---|
| Yöntem | GET, POST, PUT, PATCH ya da DELETE. | GET |
| URL | Tam http:// ya da https:// adresi, en fazla 2.000 karakter. Girdileri yola {ad} olarak yazın, örneğin https://api.magazan.com/siparisler/{siparis_no}. | — |
Peki modelin doldurduğu girdilerden isteği şöyle kurar:
- URL'de
{ad}olarak yazılan girdiler yer tutucunun yerine URL-kodlanarak konur. GETveDELETEisteklerinde diğer girdiler sorgu parametresi olarak gönderilir:?eposta=ayse%40ornek.com.POST,PUTvePATCHisteklerinde diğer girdilercontent-type: application/jsonile JSON gövdesi olarak gönderilir. Modelin boş bıraktığı isteğe bağlı girdiler gönderilmez.- Peki
accept: application/jsonbaşlığıyla JSON ister.
URL'de henüz girdi olmayan bir {yer_tutucu} varsa kartta siparis_no girdisini ekle gibi bir düğme çıkar.
Gövde her zaman, anahtarları girdi adları olan düz bir JSON nesnesidir. API'niz başka bir yapı istiyorsa (iç içe nesneler, diziler, sabit bir alan) bunun yerine Fonksiyon kullanın.
Girdiler
Girdiler, modelin doldurduğu değerlerdir. Eklemek için Girdi ekle'ye, düzenlemek için girdinin üzerine tıklayın.
| Ayar | Ne işe yarar | Varsayılan |
|---|---|---|
| Ad | Parametre adı, API'nize olduğu gibi gönderilir. Harf, rakam ve _, en fazla 64 karakter. Tool içinde benzersiz olmalı. | input_1 |
| Tür | Metin, Sayı ya da Evet / hayır. | Metin |
| Zorunlu | Model doldurmak zorundadır. Doldurulmazsa çağrı Missing input: <ad> hatasıyla başarısız olur. | Açık |
| AI'ın gördüğü açıklama | Nasıl doldurulacağı, örneğin "sipariş numarası, 5–8 haneli". En fazla 300 karakter. | Boş |
| Gerçek kişisel veri gerekir | Aşağıya bakın. | Kapalı |
Bir tool'un en fazla 20 girdisi olabilir.
Girdilerde kişisel veri
Kişisel veri koruması açıkken (varsayılan) model TC kimlik, kart, IBAN, telefon ve e-posta gibi bilgileri hiç görmez; onların yerine [PHONE_1] gibi yer tutucular görür. Bu yüzden konuşmadan doldurulan bir girdi de varsayılan olarak yer tutucuyu alır.
API'nin gerçek değere ihtiyaç duyduğu girdilerde Gerçek kişisel veri gerekir seçeneğini açın: API müşterinin gerçek değerini alır, AI ise yalnızca [TCKN_1] gibi bir yer tutucu görür. Çağrının izi de yer tutucuyu saklar. Tool yanıtında dönen kişisel veriler de model okumadan önce yer tutucuya çevrilir.
Bkz. Guardrails ve gizlilik.
Onay
| Ayar | Ne işe yarar | Varsayılan |
|---|---|---|
| Onay gerekir | Agent çağırmadan önce ekibe sorar; onayı Inbox'ta verirsiniz. Çağrı, göndereceği değerlerin tam haliyle bekler. | Kapalı |
| Reddedilince | Müşteriye söyle (agent bunun yapılamayacağını söyler) ya da Sessiz kal. | Müşteriye söyle |
Bir şeyi değiştiren işlemler için kullanın: iade, iptal, randevu. Bkz. Onaylar.
Gelişmiş
Gelişmiş — API anahtarı, başlıklar, yanıt alanları, zaman aşımı bölümünü açın.
| Ayar | Ne işe yarar | Varsayılan |
|---|---|---|
| API anahtarı | Anahtar yok, Bearer token (Authorization: Bearer <anahtar> olarak gönderilir) ya da Başlıkta anahtar (verdiğiniz başlıkta, örneğin X-API-Key). Sonra bir anahtar seçin ya da + Yeni anahtar ekle. | Anahtar yok |
| Başlıklar | Her çağrıyla gönderilen ek başlıklar, örneğin Accept-Language: tr. Değerler sabit metindir. | Yok, en fazla 20 |
| AI'ın gördüğü yanıt alanları | Her satıra bir alan, kargo.firma gibi nokta yoluyla. Yalnızca bunlar AI'a gider. Boş bırakırsanız yanıtın tamamı gider. | Boş, en fazla 50 alan |
| Zaman aşımı | API'nizi ne kadar bekleyeceği: 3, 5, 10, 20 ya da 30 saniye. | 10 saniye |
| En fazla yanıt uzunluğu (karakter) | AI'ın okuduğu en uzun sonuç: 1.000, 2.000, 4.000, 8.000 ya da 16.000. Daha uzun sonuçlar kesilir ve …(truncated) ile biter. | 4.000 |
API anahtarını asla Başlıklar'a ya da URL'ye yazmayın. Başlık değerleri agent ayarlarında düz metin olarak saklanır ve agent'ı açabilen herkes görür. Bunun yerine API anahtarı'nı kullanın: Anahtarlar şifreli saklanır ve isteğe bizim tarafımızda eklenir. AI bunları asla görmez.
Anahtarlar
Anahtarlar (gizli anahtarlar) agent başına şifreli saklanır. Kaydettikten sonra Peki yalnızca son dört karakterini gösterir. Her anahtarın İzin verilen siteler listesi vardır: Anahtar yalnızca bu sitelere gönderilir (alan adı; tüm alt alan adları için *.magazaniz.com). Bir tool'dan anahtar eklediğinizde izin verilen site varsayılan olarak tool'un kendi adresidir.
Bir anahtar, tool'un URL'si ne derse desin yalnızca izinli sitelerine gider. Tool'u başka bir adrese yönlendirirseniz kart uyarır: Bu anahtar yalnızca api.magazan.com adresine gönderilebilir, api.baska.com adresine değil. Bir yönetici Ayarlar → Gizli anahtarlar bölümünden sitelerini değiştirebilir.
Anahtarları Ayarlar → Gizli anahtarlar altında ekleyip yönetebilirsiniz. Bkz. Değişkenler ve gizli anahtarlar.
Yanıt alanları
Yanıt alanları, modelin okuduğunu küçük ve odaklı tutar. Şu yanıt için:
{
"id": "48213",
"durum": "kargoda",
"kargo": { "firma": "Yurtiçi Kargo", "takip": "YK123456789TR" },
"urunler": [
{ "ad": "Trail Koşu 2", "numara": 42, "stok_kodu": "TK2-42" },
{ "ad": "Koşu çorabı", "numara": "M", "stok_kodu": "KC-M" }
],
"ic_not": "VIP, iki kez aradı"
}
şu yanıt alanlarıyla:
durum
kargo.firma
kargo.takip
urunler.ad
model şunu okur:
{"durum":"kargoda","kargo.firma":"Yurtiçi Kargo","kargo.takip":"YK123456789TR","urunler.ad":["Trail Koşu 2","Koşu çorabı"]}
- Bir dizinin içinden geçen yol, her öğedeki değeri toplar (yukarıdaki
urunler.ad). - Tek bir öğeyi seçmek için sayı kullanın:
urunler.0.ad,"Trail Koşu 2"olur. - Yanıtta olmayan alanlar atlanır.
- Yanıttaki kişisel veriler her durumda yer tutucuyla değiştirilir.
Dene
Her tool'da bir Dene satırı vardır. Her girdi için bir değer yazın ve Çalıştır'a tıklayın (ya da Enter'a basın). ✓ HTTP 200 ya da hatayı ve ne kadar sürdüğünü görürsünüz. Karşılaştırmak için Yanıtı gör'e tıklayın:
- AI'ın gördüğü: yanıt alanları ve uzunluk sınırı uygulandıktan sonra modelin okuyacağı sonuç.
- Ham yanıt: API'nizin döndürdüğü yanıt, çağrılan yöntem ve URL ile (en fazla 20.000 karakter).
Dene, yazdığınız değerlerle ve gerçek anahtarınızla gerçek bir çağrı yapar. Bir POST ya da DELETE gerçekten bir şey oluşturur ya da siler; Onay gerekir Dene için geçerli değildir. Yazan işlemler için test verisi ya da test ortamı kullanın. Yalnızca editör, yönetici ve sahip rolündekiler çalıştırabilir.
API'niz anahtarı geri döndürürse (hata mesajları sık yapar) Peki, model ya da Peki panelinde biri görmeden önce onu maskeler (···· ve en fazla son dört karakter).
Güvenlik sınırları
Tool'lar API'nizi Peki'nin sunucularından, bir ağ koruması üzerinden çağırır. Bu sınırlar hem sizin çalışma alanınızı hem bizimkini korur; kapatılamaz.
-
Yalnızca
httpvehttpsURL'leri. -
Özel ya da yerel adresler yok. Bunlara giden istekler Requests to … are not allowed (private or local network) hatasıyla reddedilir:
Aralık Ne olduğu 127.0.0.0/8,::1Bu makine (localhost) 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7Özel ağlar 169.254.0.0/16,fe80::/10Link-local, bulut metadata servisleri dahil 100.64.0.0/10Operatör düzeyi NAT (CGNAT) 0.0.0.0/8,192.0.0.0/24,198.18.0.0/15,240.0.0.0/4,::,64:ff9b::/96Ayrılmış ve özel amaçlı aralıklar 224.0.0.0/4,ff00::/8Multicast -
Adres DNS çözümlemesinden sonra kontrol edilir. Özel bir adrese çözümlenen herkese açık bir alan adı da reddedilir; böylece bir DNS kaydı tool'u iç bir servise yönlendiremez.
-
Yönlendirmeler izlenmez.
301ya da302hata olarak döner (HTTP 301). Tool'da son adresi kullanın. -
Yanıtlar 1 MB ile sınırlıdır. Daha büyük bir yanıt Response too large hatası verir. Daha dar bir uç nokta ya da daha az veri döndüren sorgu parametreleri kullanın.
-
Anahtarlar yalnızca izinli sitelerine gider, yukarıda anlatıldığı gibi.
API'nizin herkese açık internetten erişilebilir olması gerekir. Bir iç sistemi bağlamak için onun için herkese açık bir HTTPS uç noktası açın (örneğin bir API geçidiyle) ve bir anahtarla koruyun.
Hatalar
Kartta görünen sorunlar
| Mesaj | Ne yapmalı |
|---|---|
| Bir başlık verin | Başlık'ı doldurun. |
| AI adı yalnızca küçük harf, rakam ve _ içerebilir | AI'ın kullandığı ad'ı düzeltin. |
| Bu AI adını başka bir tool kullanıyor | Adlar HTTP tool'ları ve fonksiyonlar arasında ortaktır. Başka bir ad seçin. |
| web_search yerleşik bir araç adı | Bkz. ayrılmış adlar. |
| AI'ın bunu ne zaman kullanacağını yazın | AI'ın gördüğü açıklama'yı doldurun. |
| API adresini girin (https://…) | Alan adı olan tam bir URL kullanın. |
| URL'deki {siparis_no} henüz bir girdi değil | Girdiyi ekleyin ya da siparis_no girdisini ekle'ye tıklayın. |
| Bir API anahtarı seçin / Anahtar için başlık adını girin | API anahtarı ayarını tamamlayın ya da Anahtar yok yapın. |
Tool çalışırken çıkan hatalar
Bir çağrı başarısız olduğunda model hatayı tool'un sonucu olarak okur; müşteriye söyleyebilir, başka bir girdiyle tekrar deneyebilir ya da devredebilir. Aynı hatalar Dene'de ve konuşmanın izinde de görünür. Hata metinleri sunucudan İngilizce gelir.
| Hata | Neden | Ne yapmalı |
|---|---|---|
HTTP 404, HTTP 500, … | API'niz 2xx dışı bir durumla yanıt verdi. Model en fazla 1.000 karakterlik {"error": "HTTP 404", "body": …} okur. | URL'yi ve girdileri Dene ile kontrol edin. Geçerli girdi biçimlerini girdi açıklamalarına yazın. |
Missing input: siparis_no | Zorunlu bir girdi boştu. | Tool açıklamasında neye ihtiyaç olduğunu yazın ya da girdiyi isteğe bağlı yapın. |
Request timed out after 10000 ms | API'niz Zaman aşımı'ndan yavaştı. | Zaman aşımını artırın ya da uç noktayı hızlandırın. |
Response too large (over 1000000 bytes) | Yanıt 1 MB'ı geçti. | Daha az veri döndürün. |
Requests to … are not allowed (private or local network) | URL özel bir adresi gösteriyor. | Herkese açık bir uç nokta kullanın. |
This API key may only be sent to … | Tool'un adresi anahtarın izinli siteleri arasında değil. | Tool'u doğru adrese yönlendirin ya da bir yöneticiden anahtarın sitelerini değiştirmesini isteyin. |
This API key has no allowed sites yet… | Anahtarın sitesi yok. | Bir yönetici Ayarlar → Gizli anahtarlar'dan ekler. |
The API key for this tool was deleted | Anahtar silindi. | Başka bir anahtar seçin. |
This API key belongs to another agent | Anahtarlar tek bir agent'a aittir. | Bu agent için bir anahtar ekleyin. |
This API key is not assigned to an agent yet… | Hiçbir agent'a atanmamış eski bir anahtar. | Bir yönetici Ayarlar → Gizli anahtarlar'dan atar. |
This key is a webhook signing key… | İmzalama anahtarları yalnızca gelen webhook imzalarını kontrol eder, hiçbir yere gönderilmez. | Normal bir anahtar seçin. |
Yerleşik tool'lar
Kendi tool'larınızın yanında Peki, ayarlarınıza göre agent'a yerleşik tool'lar da verir. Bunları Tools sayfasında kurmazsınız.
| Tool | Ne yapar | Ne zaman sunulur |
|---|---|---|
request_human | Ekibinizden birini konuşmaya çağırır. | Handoff açıksa (varsayılan). Otomasyonlarda yoktur. Bkz. Ekibe devretme. |
web_search | Güncel bilgi için web'de arar, ilk 5 sonucu döndürür. | Web search açıksa (varsayılan olarak kapalı). |
read_page | Bir web sayfasını düz metin olarak okur. | Web search açıksa. |
load_skill | Bir skill'in talimatlarını yükler. | Agent'ın skill'leri varsa. Bkz. Skills. |
save_<tablo>, find_<tablo> | Kayıt kaydeder ve arar. | Agent'ın kayıt tabloları varsa. Bkz. Records. |
ask_<ad> | Çalışma alanındaki başka bir agent'tan yardım ister. | Agent'ın ekip üyeleri varsa. Bkz. Agent ekipleri. |
Knowledge bir tool değildir: Peki her mesaj için agent'ın knowledge'ında otomatik arama yapar. Bkz. Knowledge.
web_search, read_page, request_human, load_skill ve need_info gibi adlar ayrılmıştır. Tool'larınız ve fonksiyonlarınız bunları, kayıt tablolarının ve ekip üyelerinin zaten kullandığı adları kullanamaz.
Otomasyonlarda tool'lar
Bir otomasyon görev çalıştırdığında agent yalnızca o görev için izin verdiğiniz tool'ları alır. Deneme çalıştırmasında GET dışında bir şey gönderen tool'lar çağrılmaz; model çağrının atlandığını okur.
Örnekler
Sipariş durumu (GET, yol girdisi)
| Ayar | Değer |
|---|---|
| Başlık | Sipariş durumu |
| AI'ın kullandığı ad | siparis_durumu |
| Açıklama | Siparişin nerede olduğunu sorgular. Müşteri sipariş numarası verdiğinde ya da paketinin nerede olduğunu sorduğunda kullan. |
| İstek | GET https://api.magazan.com/v1/siparisler/{siparis_no} |
| Girdiler | siparis_no, Metin, zorunlu: "Sipariş numarası, 5–8 hane, # olmadan" |
| API anahtarı | Bearer token, "Mağaza API" anahtarı, izinli site api.magazan.com |
| Yanıt alanları | durum, kargo.firma, kargo.takip, tahmini_teslimat |
48213 numaralı sipariş için çağrı:
GET https://api.magazan.com/v1/siparisler/48213
accept: application/json
authorization: Bearer ••••••••
Müşteri bulma (GET, kişisel veri içeren sorgu girdisi)
| Ayar | Değer |
|---|---|
| AI'ın kullandığı ad | musteri_bul |
| Açıklama | Müşterinin hesabını telefon numarasıyla bulur. Hesabıyla ilgili soruları yanıtlamadan önce kullan. |
| İstek | GET https://api.magazan.com/v1/musteriler |
| Girdiler | telefon, Metin, zorunlu, Gerçek kişisel veri gerekir açık |
| Yanıt alanları | ad, seviye, acik_siparisler |
Model telefon girdisini [PHONE_1] gibi bir yer tutucuyla doldurur; Peki gerçek numarayı gönderir:
GET https://api.magazan.com/v1/musteriler?telefon=%2B90+532+123+45+67
Randevu talebi (POST, JSON gövdesi, onay)
| Ayar | Değer |
|---|---|
| Başlık | Randevu talebi |
| AI'ın kullandığı ad | randevu_talebi |
| Açıklama | Randevu talebi oluşturur. Yalnızca hasta tedaviyi, günü ve telefon numarasını onayladıktan sonra kullan. |
| İstek | POST https://randevu.gulumsedis.example/api/talepler |
| Girdiler | ad_soyad (Metin), telefon (Metin, Gerçek kişisel veri gerekir), tedavi (Metin), gun (Metin: "YYYY-AA-GG"), ilk_ziyaret (Evet / hayır, isteğe bağlı) |
| API anahtarı | Başlıkta anahtar: X-API-Key |
| Onay gerekir | Açık, Reddedilince: Müşteriye söyle |
Onaydan sonraki istek:
POST https://randevu.gulumsedis.example/api/talepler
content-type: application/json
x-api-key: ••••••••
{"ad_soyad":"Ayşe Yılmaz","telefon":"+90 532 123 45 67","tedavi":"Diş taşı temizliği","gun":"2026-11-04","ilk_ziyaret":true}
Sınırlar
| Sınır | Değer |
|---|---|
| Agent başına HTTP tool | 30 |
| Agent başına fonksiyon | 30 |
| Tool başına girdi | 20 |
| Tool başına başlık | 20 |
| Tool başına yanıt alanı | 50 |
| URL uzunluğu | 2.000 karakter |
| Zaman aşımı | En fazla 30 saniye (menüde 3, 5, 10, 20 ya da 30), varsayılan 10 |
| API'den okunan yanıt | 1 MB |
| AI'ın okuduğu sonuç | En fazla 20.000 karakter (menüde 1.000–16.000), varsayılan 4.000 |