Custom Tools

Kullanım Senaryoları

Kurulum

Alanlar

• Ad — işlev için bir tanımlayıcı (harfler, rakamlar, alt çizgiler), ör. get_order_status. Yapay zeka bu adı görür.
• Açıklama — en önemli alan. Yapay zekaya aracı ne zaman çağıracağını söyler. Açık olun: “Müşteri bir sipariş numarasından bahsettiğinde bunu çağır. Doğrulama isteme.”
• Uç nokta URL'si — Asyntai'nin çağıracağı herkese açık HTTPS URL'si.
• HTTP yöntemi — GET (salt okunur, önerilir) veya POST (verileri değiştirebilir — aşağıdaki Güvenlik bölümüne bakın).
• Parametreler — yapay zekanın görüşmeden çıkardığı ve gönderdiği girdiler. Her birinin bir adı, türü, açıklaması ve zorunluluk işareti vardır. GET için sorgu dizesi parametreleri olarak; POST için ise bir JSON gövdesi olarak gönderilirler.
• Kimlik doğrulama başlığı (isteğe bağlı) — her çağrıda gönderilen bir başlık adı + değeri, ör. X-API-Key. Uç noktanız bir anahtar gerektiriyorsa bunu kullanın.

Çözümlü örnek: sipariş durumu araması

Mağazanızın şu uç noktayı sunduğunu varsayalım:

GET https://yourstore.com/api/order-status?order_number=10294

…ki bu şuna benzer bir JSON döndürür:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

Bir aracı şu şekilde yapılandırırsınız:

• Ad: get_order_status
• Açıklama: “Bir müşteri siparişinin durumunu ara. Müşteri bir sipariş numarası verdiğinde bunu hemen çağır — ek doğrulama isteme. Yanıtında döndürülen customer_message değerini kullan.”
• Uç nokta URL'si: https://yourstore.com/api/order-status
• Yöntem: GET
• Parametre: order_number (string, zorunlu) — “Müşterinin sipariş numarası, genellikle 8+ basamaklı.”

Bir müşteri “#10294 numaralı siparişim ne durumda?” yazdığında, yapay zeka get_order_status(order_number=10294)'i çağırır, Asyntai URL'nize ?order_number=10294 ile istek gönderir ve yapay zeka yanıtı kullanarak cevap verir.

Uç noktanızın ne aldığı ve ne döndürmesi gerektiği

• İstek: parametreleriniz sorgu dizesinde olacak şekilde bir GET veya bir JSON gövdesi içeren bir POST. Yapılandırdığınız her kimlik doğrulama başlığı dahil edilir.
• Yanıt: JSON (tercih edilen) veya düz metin döndürün. Asyntai gövdeyi yapay zekaya geri iletir. Yapay zekanın doğrudan alıntılayabileceği bir alan — customer_message gibi — iyi işe yarar.
• Bulunamadı / hatalar: yapay zekanın tahmin yürütmek yerine doğru bir şekilde yanıt verebilmesi için açık bir veri yükü döndürün (örneğin found: false ve bir customer_message içeren bir JSON nesnesi).

Aracınızı test etme

Her aracın yapılandırma sayfasında yerleşik bir Bu aracı test et paneli vardır, böylece herhangi bir müşteri kullanmadan önce — ve bot üzerinden mesaj göndermeden — çalıştığını doğrulayabilirsiniz.

1. Aracın parametreleri için örnek değerler girin (ör. gerçek bir sipariş numarası).
2. Testi çalıştır'a tıklayın. Asyntai uç noktanızı tam olarak yapay zekanın yapacağı gibi çağırır — aynı sorgu dizesi veya JSON gövdesi, aynı kimlik doğrulama başlığı, aynı 5 saniyelik zaman aşımı ve güvenlik kontrolleri.
3. Sonucu anında görürsünüz: bir başarı/başarısızlık rozeti, HTTP durumu, yanıt süresi, çağırdığımız tam URL ve uç noktanızın ham yanıtı (JSON ise düzenli biçimlendirilmiş olarak).

Bu, kaydedilmemiş düzenlemelerde de çalışır, böylece URL'yi, parametreleri veya kimlik doğrulama başlığını ayarlayabilir ve beklediğiniz sonucu döndürene kadar yeniden test edebilirsiniz.

Güvenlik — bunu okuyun

• GET / salt okunuru tercih edin. Aramalar (sipariş durumu, stok, takip) açığa çıkarılması güvenli işlemlerdir. GET bu nedenle varsayılandır.
• POST onay gerektirir. POST verileri değiştirebildiğinden, bir POST aracı yalnızca kendi uç noktanızdaki istekleri güvenli hale getirmekten ve yetkilendirmekten tek başınıza sorumlu olduğunuzu onaylayan bir kutucuğu işaretledikten sonra kaydedilebilir. Uç noktanız isteği bağımsız olarak doğrulamadığı sürece iadeleri, iptalleri, parola değişikliklerini veya para hareketlerini asla bağlamayın.
• Sayım saldırılarına karşı koruyun. Bir arama anahtarı tahmin edilebilirse (ardışık sipariş numaraları gibi), ikinci bir faktör isteyin — ör. sipariş numarası ve siparişteki e-posta — ve bunların eşleştiğini doğrulayın; böylece bir ziyaretçi numaraları deneyerek başka müşterilerin verilerini okuyamaz.
• Yapay zekanın argümanlarına asla güvenmeyin. Her isteği, anonim bir saldırgandan geliyormuş gibi sunucu tarafında doğrulayın ve yetkilendirin — çünkü fiilen öyle olabilir.

Canlı çağrıları doğrulama

Aracınız yayına alındıktan sonra, bir görüşmedeki her gerçek çağrı kaydedilir. Her çağrı için araç adını, yapay zekanın gönderdiği argümanları, istediğimiz tam URL'yi, HTTP durumunu, yanıtı ve süreyi kaydederiz. Bu, kendi sunucu günlüklerinizi karıştırmadan bir aracın gerçek bir sohbette tetiklendiğini doğrulamanızı ve uç noktanızın ne döndürdüğünü görmenizi sağlar. (Yukarıdaki Bu aracı test et paneli, kurulumu kendiniz kontrol etmek içindir; bu günlük ise gerçek müşteri görüşmeleri sırasında olanları yakalar.)

Sınırlar & güvenlik önlemleri

• Web sitesi başına en fazla 10 araç.
• Çağrı başına 5 saniyelik zaman aşımı; yanıtlar 10 KB ile sınırlandırılmıştır.
• Uç noktalar herkese açık http(s) URL'leri olmalıdır. Özel, geri döngü (loopback) ve iç ağ adresleri engellenir.
• Standard ve Pro planlarında kullanılabilir.
• Faturalandırma: her araç çağrısı planınızda bir ek mesaj olarak sayılır. Normal bir yanıt 1 mesaj kullanır; yapay zekânın bir araç çağırdığı bir yanıt 2 mesaj kullanır (yanıt artı araç çağrısı), çünkü bir araç çağrısı ek bir yapay zekâ isteği gerektirir.
• Bir araç çağrısı başarısız olursa (zaman aşımı, hata, engelleme), yapay zekaya bu bilgi verilir ve nazikçe yanıt verir — görüşmeyi çökertmez.