Ajan bir müşteri kaydı ister. API'niz müşteriyi, artı son 200 siparişini, artı bu siparişlerdeki her bir satır öğesini, artı üç farklı formattaki zaman damgalarını ve her biri için bir _links bloğunu döndürür. Kırk bin jeton bağlam penceresine düşer. Ajanın e-posta adresine ihtiyacı vardı.
Bunu bir çalıştırmada dört kez yapın ve ajan bütçesinin çoğunu istemediği JSON'ı okuyarak harcamış olur. Ardından ilginç hatalar başlar: orijinal talimatı unutur, görevi bitirmek yerine özetler ve kalite düşerken çalıştırma başına maliyet artar.
Bu, bir istem (prompt) sorunu değil, API katmanındaki bir tasarım sorunudur. Ajanlar yanıtları sabit bir pencere üzerinden tüketir ve döndürdüğünüz her alan talimatlar, konuşma ve plan ile rekabet eder. Bu kılavuz, şişkinliğin nereden kaynaklandığını, bunu düzelten alan seçimi ve sayfalama modellerini, API'yi kontrol etmediğinizde araç katmanında nasıl kırpma yapılacağını ve farkı nasıl ölçeceğinizi kapsar. Yapay zeka ajanlarının üretimde neden bozulduğuna dair yazımız, bağlam tükenmesini temel hata modlarından biri olarak ele alır ve bu da konunun pratik yarısıdır.
Apidog ölçüm tarafında yardımcı olur: bir ajan onu çağırmadan önce her uç noktanın gerçek yanıt boyutunu görebilir ve API ekibi göndermeden önce istediğiniz kırpılmış şekli taklit edebilirsiniz.
Jetonlar nereye gidiyor?
Tarayıcılar ve panolar için tasarlanmış yanıtlar, bir ajana gerçek maliyet yükleyen çok fazla yük taşır.
Ayrıntılı zarflar. Beş alanlı bir nesnenin etrafındaki bir data, meta, links, included sarmalayıcı, yükü ikiye katlayabilir. Hipermedya bağlantıları, onları takip eden bir istemci için faydalıdır. Ajanlar bunu neredeyse hiç yapmaz ve her URL bir jeton demektir.
Tekrarlanan anahtarlar. JSON, her dizi öğesindeki her alan adını tekrarlar. Öğe başına 15 alan içeren 200 öğelik bir liste, 3.000 anahtar dizgisi için ödeme yapar. Liste uç noktalarının bağlam kullanımına neden hakim olduğu budur.
Varsayılan olarak iç içe genişletme. İlgili kaynakları satır içi yapan uç noktalar, bir ajan onlara ulaşana kadar kullanışlıdır. Bir müşteri artı siparişleri artı öğeler bir ağaçtır ve ağaçlar hızla büyür.
Gereksiz formatlar. Aynı nesne üzerinde created_at, created_at_unix ve created_at_human bir değer için üç kat maliyet demektir.
Null'lar ve boş değerler. Birçok seri hale getirici, ayarlanmamış olsa bile her alanı çıkarır. Kayıt başına yirmi null saf israftır.
Bunu görmenin faydalı bir yolu: jeton maliyeti, kayıt sayısını değil, serileştirilmiş metnin boyutunu takip eder. Her biri beş alana sahip iki yüz kayıt, bir derinlemesine iç içe nesneden daha ucuz olabilir.
Kural bir: kaynakları değil, alanları döndürün
En yüksek değerli tek değişiklik, çağırıcıya neye ihtiyacı olduğunu sormasına izin vermektir.
GET /v1/customers/8812?fields=id,email,plan,status
{ "id": "8812", "email": "dana@example.com", "plan": "pro", "status": "active" }
Bu, çoğu API'de tam bir kayda göre %90'lık bir kesinti demektir ve eklemesi bir öğleden sonra sürer. Google’ın API tasarım kılavuzu, arkasında emsal olan bir sürüm istiyorsanız alan maskesi desenini belgeler ve GraphQL aynı sorunu seçimi zorunlu kılarak çözer.
İki uygulama notu. Alan listesini şemaya karşı doğrulayın ve bilinmeyen adları reddedin, böylece hayali bir alan sessizce kırpılmış bir nesne yerine net bir hata üretir. Ve hiçbir şey göndermeyen çağırıcılar için her şeyi varsaymak yerine küçük bir varsayılan küme tutun.
Ardından, parametreyi araç açıklamasında, alanlar açıkça belirtilmiş şekilde modele sunun:
{
"name": "getCustomer",
"description": "Bir müşteriyi ID'ye göre getir. Her zaman sadece ihtiyacın olan `fields` ilet. Mevcut: id, email, name, plan, status, created_at, billing_address, order_count.",
"input_schema": {
"type": "object",
"required": ["customerId", "fields"],
"properties": {
"customerId": { "type": "string" },
"fields": {
"type": "array",
"items": { "type": "string" },
"description": "Döndürülecek alan adları. Bu listeyi minimal tutun."
}
}
}
}
Açıklamalar, modelin bu kuralları öğrendiği tek yerdir ve hem OpenAI işlev çağırma kılavuzu hem de Anthropic araç kullanım belgeleri bunlara aynı önemi verir. fields parametresini zorunlu kılmak işin püf noktasıdır. İsteğe bağlı bir parametre atlanır; zorunlu bir parametre ise modeli gerçekten neye ihtiyacı olduğunu düşünmeye zorlar.
Kural iki: listeyi her zaman sınırlayın
Sınırsız liste uç noktaları, ikinci büyük şişme kaynağıdır. Bir ajan "son siparişleri" ister ve 2019'dan beri her şeyi alır.
Sadece bir varsayılan değil, sunucu tarafında sabit bir maksimum belirleyin. Eğer ajan limit=5000 gönderirse, 100 döndürün ve bunu belirtin. REST API sayfalama ve milyonlarca kayıt için sayfalama tasarlama konusundaki kılavuzlarımız mekaniği kapsar; ajana özel kurallar daha dardır:
- Sayfayı, tipik kayıtlar için 20 ila 50 öğe aralığında, bir modelin okuyabileceği bir şeyle sınırlayın.
- Toplam sayıyı döndürün, böylece ajan, her şeyi görüp görmediğini sayfalama yapmadan anlayabilir.
- İmleç sayfalama kullanın. Veriler çalışma sırasında değiştiğinde ofsetler kayabilir ve yavaş sayfalayan bir ajan bununla karşılaşacaktır.
- Yanıt içinde
"truncated": truegibi basit bir ifade ekleyin, böylece model daha fazlası olduğunu bilir. Modeller, yalnızca dizi uzunluğundan tamlığı yanlış değerlendirme eğilimindedir.
Ayrıca ajana hiç sayfalama yapmaktan kaçınmanın bir yolunu verin. Bir count uç noktası, dar bir pencereye sahip filtrelenmiş bir arama veya bir özet nesnesi, genellikle hiçbir kayıt döndürmeden soruyu yanıtlayacaktır. En ucuz yanıt, veriyi içermeyen yanıttır.
Kural üç: API sizin değilse araç katmanında kırpma yapın
Üçüncü taraf API'leri, siz istediğiniz için alan seçimi eklemeyecektir. Bunun yerine kırpmayı HTTP yanıtı ile model arasına, kendi yürütücünüze yerleştirin.
KEEP = {
"getCustomer": ["id", "email", "plan", "status"],
"listOrders": ["id", "total", "status", "created_at"],
}
def project(tool_name, payload):
keep = KEEP.get(tool_name)
if keep is None:
return payload
if isinstance(payload, list):
return [{k: item.get(k) for k in keep if k in item} for item in payload]
return {k: payload.get(k) for k in keep if k in payload}
Üç iyileştirme, bunun pratikte geçerli olmasını sağlar.
Tam yanıtı saklayın ve modele projeksiyonu verin. Kırpılmamış yükü çalışma günlüğünüzde tutun, böylece hata ayıklama hala mümkün olur. Ajan araç çağrılarını izleme hakkındaki yazımız neyin kaydedileceğini kapsar.
Modele neyi kaldırdığınızı söyleyin. "_omitted": ["billing_address", "notes", "metadata"] gibi bir satır, verinin mevcut olmadığı sonucuna varmak yerine, gerçekten ihtiyaç duyduğunda tam kaydı istemesini sağlar.
Listeleri kompakt bir formata dönüştürün. Tablosal sonuçlar için, CSV veya bir markdown tablosu, alan adları satır başına yerine bir kez göründüğü için JSON'dan çok daha az jeton maliyetine sahiptir. Modeller ikisini de iyi okur.
id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22
Kural dört: ağır durumlar için sunucuda özetleyin
Bazı soruların hiç kayda ihtiyacı yoktur. "Bu müşteri bu ay herhangi bir başarısız ödeme yaptı mı?" bir boolean sorusudur. Modelin bunu anlaması için 40 ödeme nesnesi döndürmek, yanıtlamanın pahalı yoludur.
Bir soru tekrarlandığında, onu doğrudan yanıtlayan uç noktayı ekleyin. Bir hesap sağlığı özeti, bir durum toplama, küçük bir toplama. Bu, sıradan bir API tasarım işi gibi görünür çünkü öyledir ve yukarıdaki her şeyin en değerli versiyonudur: büyük bir yanıtı kırpmak yerine, hiç üretmekten kaçınırsınız.
İki güvenlik önlemi. Özetleri şekil olarak stabil tutun, böylece ajanlar onlara güvenebilir, ve onları versiyonlayın, çünkü bir ajanın istemi bir şekle göre yazılmıştır ve sessiz bir değişiklik onu bozar. API bir ajanın altından değiştiğinde ne olduğu hakkındaki yazımız bu riski kapsar ve en iyi API sürümleme stratejisi mekaniği kapsar.
Önce ve sonra ölçüm yapın
Bunların hiçbiri körü körüne yapmaya değmez. Üç sayı size sorunun nerede olduğunu söyler.
Yanıt başına, uç nokta başına bayt. Ajanınızın çağırabileceği her araca gerçekçi bir istek gönderin ve yük boyutunu kaydedin. Birkaç kilobaytı aşan her şey bir adaydır. Apidog'da her uç noktayı bir kez çalıştırabilir ve boyutu doğrudan yanıttan okuyabilir, ardından isteği kaydederek API değiştiğinde kontrolün tekrarlanmasını sağlayabilirsiniz.
Araç çağrısı başına jeton. Baytlar bir vekildir; jetonlar faturadır. Yükleri sağlayıcınızın jetonlayıcısından, örneğin OpenAI modelleri için tiktoken gibi, geçirin ve uç noktaları sıralayın. Sıralama genellikle dengesizdir, maliyetin çoğundan bir veya iki uç nokta sorumludur.
Çalıştırma başına kullanılan bağlam. Tüm ajan görevi boyunca çalışan toplamı günlüğe kaydedin. Eğer bir görev limite yakın biterse, kırpma size sadece daha ucuz değil, tamamlanmış çalıştırmalar kazandırır.
Ardından, istediğiniz şekli tasarlayın ve API ekibi inşa etmeden önce onu taklit edin. Kırpılmış yanıtı döndüren bir taklit sunucu, iyileşmeyi ölçmenize ve ajanın daha az veriyle hala başarılı olduğunu doğrulamanıza olanak tanır, ki bu asıl önemli olan sorudur. Ajanları üretim yerine taklitlere karşı çalıştırma hakkındaki yazımız iş akışını kapsar.
İyi olan neye benzer?
Ajana uygun bir yanıt küçük, düz ve neyi dışarıda bıraktığı konusunda dürüsttür:
{
"customer": { "id": "8812", "email": "dana@example.com", "plan": "pro" },
"recent_orders": [
{ "id": "ord_91", "total_cents": 4900, "status": "paid" },
{ "id": "ord_92", "total_cents": 1200, "status": "refunded" }
],
"recent_orders_total": 47,
"truncated": true,
"_omitted": ["billing_address", "metadata", "order_line_items"]
}
200 jetonun altında. Yaygın soruyu yanıtlar, iki yerine 47 sipariş olduğunu belirtir ve modele bir sonraki ne isteyebileceğini söyler.
En gürültülü uç noktanızla başlayın. Ölçün, alan seçimi ekleyin, listeyi sınırlayın ve ajanı tekrar çalıştırın. İki sayı arasındaki fark genellikle işin geri kalanını haklı çıkarmak için yeterince büyüktür. Ölçümü ve taklidi aynı projede istiyorsanız Apidog'u indirin.
Bunun ortaya çıktığı üç yer
Destek triyajı. Bir ajan bir bileti okur, müşteriyi çeker ve durumu tırmandırıp tırmandırmayacağına karar verir. Saf sürüm, gerçek şikayeti okumadan önce tam müşteri nesnesini ve son 50 bileti getirir, 30.000 jeton harcar. Düzeltilmiş sürüm, plan, durum, açık bilet sayısı ve son iletişim tarihini döndüren bir özet uç noktasını çağırır. Yaklaşık 80 jeton, ve ilgili gerçekler gömülü olmadığı için tırmandırma kararı daha iyi hale gelir.
Dahili operasyon ajanları. Bir dağıtım ajanı 40 hizmette hizmet sağlığını kontrol eder. Tam durum nesneleri 12. hizmette pencereyi doldurur. Hizmet başına bir satır, ad artı durum artı hata oranı döndüren bir toplama, 40 hizmetin hepsini birkaç yüz jetona sığdırır ve ajanın ilk yarısını unutmak yerine tüm filo üzerinde akıl yürütmesine olanak tanır.
Veri girişi ve mutabakat. Bir ajan faturaları ödemelerle eşleştirir. Tam fatura belgelerini döndürmek, birkaç düzine kayıttan sonra başarısız olmasına neden olur. id, amount_cents, date ve reference değerlerini CSV olarak döndürmek, karşılaştırma yalnızca dört alanı kullandığı için birkaç yüz kaydı tek bir geçişte işlemesini sağlar.
Üçünde de ortak desen: ajan bir karar yüzeyine ihtiyaç duydu ve API ona bir belge verdi.
Deseni görmek için çalıştırma geçmişine ihtiyacınız var
Tek bir çalıştırma, bir yanıtın büyük olduğunu size söyler. Hangi uç noktanın bütçeyi aştığı ve ne sıklıkta olduğu deseni, ancak çalıştırmalar arasında ortaya çıkar.
Bu, sayıların oturumdan sonra da kalması gerektiği anlamına gelir. Dağıttığınız bir hizmet için bu, kendi telemetrinizdir. Atanan işi yürüten kodlama ajanları için, onları çalıştıran platformdur: Sharkly, her çalıştırmanın yürütme izini ve sonucunu geldiği görevde saklar, böylece çalıştırmadan çalıştırmaya karşılaştırma, terminal oturumlarını yeniden oluşturmak yerine görev geçmişini okuma meselesidir. Her iki durumda da, geçmiş olmadan bütçe zorlaması size bir şeyin çok büyük olduğunu söyler, ancak önce neyi düzelteceğinizi söylemez.
Sadece çalıştırma başına değil, araç başına bütçe belirleyin
Çoğu ekip toplam bağlamı sınırlar ve orada durur. Araç başına bütçe daha kullanışlıdır, çünkü belirsiz bir sorunu belirli bir soruna dönüştürür.
Her araca bir tavan belirleyin, örneğin 1.500 jeton. Bir yanıt bunu aştığında, yürütücü projeksiyona kırpar, atlanan alan işaretçisini ekler ve taşmayı günlüğe kaydeder. Şimdi düzenli olarak bütçeyi aşan uç noktaların, ajanın onları ne sıklıkta çağırdığına göre sıralanmış bir listesi var, ki bu sizin iş kuyruğunuzdur.
Bütçe ayrıca sizi testlerde küçük olan ancak gerçek bir müşteri için muazzam olan uç noktalardan korur. Dağılımların kuyrukları vardır ve 4.000 siparişli hesap, bir çalıştırmayı sabah 2'de bozan hesap olacaktır. Sert bir sınır, başarısız bir görev yerine bunu kırpılmış bir yanıta dönüştürür.
Sıkça sorulan sorular
Yanıtları kırpmak, ajanın eksik verilere ihtiyacı varsa riskli midir? Sadece kırpmayı gizlerseniz. Açık bir işaretleyici ve atlanan alanların bir listesini ekleyin, böylece model bunları talep edebilir. Yanlış cevaplara neden olan şey sessiz kırpmadır, kırpmanın kendisi değil.
Ajanlar için bunun yerine GraphQL kullanmalı mıyım? GraphQL, alan seçimini zorunlu kılarak bu sorunu temiz bir şekilde çözer, ancak karmaşıklığı sorgu oluşturmaya taşır ve modeller geçersiz sorgular yazma eğilimindedir. REST uç noktalarına fields eklemek genellikle daha küçük bir değişikliktir.
Bir araç yanıtı ne kadar küçük olmalı? Tek bir kayıt okuması için 1.000 jetonun altını ve bir liste için 2.000 jetonun altını hedefleyin. Bunun ötesinde, ajanın kayıtlara mı yoksa bir cevaba mı ihtiyacı olduğunu sorun.
İstem önbellekleme bunu çözer mi? Tekrarlanan bağlamın maliyetini azaltır, kapladığı alanı değil. Önbelleğe alınmış 40.000 jetonluk bir yanıt hala pencereyi doldurur, bu nedenle önbellekleme faturayı düşürmeye yardımcı olurken güvenilirlik sorununu sağlam bırakır.
İkili ve dosya yanıtları ne olacak? Onları asla bağlama koymayın. Dosyayı saklayın, ajana bir referans ve kısa bir açıklama verin ve sadece ihtiyacı olanı çıkarması için ayrı bir araç sağlayın.
Kırpma nerede olmalı, API'de mi yoksa araç sarmalayıcısında mı? Sahibi sizseniz API'de olmalı, çünkü her çağırıcı faydalanır ve baytlar asla ağı geçmez. Sahibi siz değilseniz sarmalayıcıda. Her ikisini de yapmak sorun değil.