Çoğu API, dokümantasyon okuyan, örneklere göz atan ve stack trace'ler ile hata ayıklayan insan geliştiriciler için tasarlanmıştır. Ancak 2026'da, en hızlı büyüyen API tüketicileri AI agent'larıdır ve onlar API'larla çok daha farklı etkileşim kurarlar.
Bu, LemonData'nın birleşik AI API'ını basit bir ilke etrafında nasıl yeniden tasarladığımızın hikayesidir: akıllı olmayın, bilgilendirici olun. Sonuç, agent-öncelikli API tasarımı dediğimiz şeydir ve kullanıcılarımızın boşa harcanan token miktarını %60'tan fazla azalttı.
Agent-Öncelikli API Tasarımı Nedir?
Agent-öncelikli API tasarımı, API yanıtlarınızı, özellikle de hata yanıtlarını, bir AI agent'ının neyin yanlış gittiğini anlayabileceği ve dışarıdan yardım almadan düzeltebileceği şekilde yapılandırmak anlamına gelir.
Geleneksel API hatası:
{"error": {"message": "Model not found"}}
Agent-öncelikli API hatası:
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
Fark mı? Geleneksel bir API ile agent'ın web'de arama yapması, dokümantasyon bulması, HTML ayrıştırması ve tahminde bulunması gerekir. Agent-öncelikli bir API ile tek adımda kendi kendini düzeltir.
Geleneksel API'lar AI Agent'ları İçin Neden Başarısız Olur?
Bir AI agent'ı tipik bir API aggregator'a ilk kez istek attığında ne olduğuna bakın:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (web'de "lemondata models list" araması yapar)
Agent: (bir dokümantasyon sayfası çeker, belki de yanlış olanı)
Agent: (HTML ayrıştırır, bir model adı bulur)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Altı adım. Birden fazla ağ isteği. Yüzlerce boşa harcanan token. Ve bu, agent'ın doğru dokümantasyon URL'sini tahmin ettiği en iyi senaryodur.
Agent-öncelikli tasarım ile:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
İki adım. Sıfır web araması. Agent, yalnızca hata yanıtından yola çıkarak kendi kendini düzeltti.
Temel İlke: Zeka Model Tarafında Kalır
Cazip olan "akıllı" API'lar oluşturmaktır: model adını otomatik düzeltmek, sessizce benzer bir modele yönlendirmek, bir öneri motoru eklemek. Biz bunların hepsini reddettik.
Bir agent model: "gpt5" gönderdiğinde, niyetini bilemezsiniz. Belki GPT-5'in var olup olmadığını test ediyordur. Belki bir bütçe kısıtlaması vardır. Belki de belirli bir yeteneğe ihtiyacı vardır. gpt-4o'ya otomatik yönlendirme yapmak; maliyeti, çıktı kalitesini ve yetenekleri agent'ın haberi olmadan sessizce değiştirecektir.
Doğru hamle, hızlı hata vermek ve bilgilendirici bir şekilde hata vermektir. Agent'a tüm verileri verin. Kararı o versin.
Dört Agent-Öncelikli API Tasarım Deseni
Desen 1: Model Bulunamadı → Bulanık Öneriler
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
did_you_mean alanı üç katmanlı bir çözümleme kullanır: üretim verilerinden statik alias eşlemesi, normalize edilmiş dize eşleştirme ve sınırlı düzenleme mesafesi. Tüm adaylar canlı model listesine göre doğrulanır, böylece asla o an çevrimdışı olan bir modeli önermeyiz.
Desen 2: Yetersiz Bakiye → Bütçe Odaklı Alternatifler
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
Sadece "yeterli para yok" demek yerine, agent'a tam olarak ne kadar parası olduğunu, ne kadara ihtiyacı olduğunu ve hangi modelleri karşılayabileceğini söylüyoruz. Agent, insan müdahalesine gerek kalmadan otonom olarak daha ucuz bir AI modeline geçiş yapabilir.
Desen 3: Tüm Kanallar Başarısız Oldu → Canlı Alternatifler
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
alternatives listesi statik değildir. Kanal sağlığı verilerimize karşı yapılan canlı bir sorgudur, bu nedenle agent şu anda gerçekte neyin çalıştığına dair gerçek zamanlı bilgi alır.
Desen 4: Rate Limited → Kesin Tekrar Deneme Zamanlaması
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
Tahmin yok. Rastgele değerlerden başlayan üstel geri çekilme yok. Agent tam bekleme süresini bilir. Rate limit'leri etkili bir şekilde yönetmek hakkında daha fazla bilgi için AI API rate limiting kılavuzumuza göz atın.
Başarılı Yanıtlar da İpuçları Taşır
Bir agent bir Claude modeli ile /v1/chat/completions çağrısı yaptığında, yanıt şunları içerir:
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
Agent'a şunu söylüyoruz: "bu çalıştı, ancak daha iyi bir yol var." Agent bir sonraki çağrıda yerel endpoint'e geçebilir; böylece OpenAI uyumlu format üzerinden sunulmayan extended thinking ve prompt caching gibi özelliklere erişebilir.
Bunu yanıt gövdesine değil, header'lara koyuyoruz çünkü gövde OpenAI/Anthropic spesifikasyonunu takip ediyor. Header'lar güvenli genişletme noktalarıdır.
Agent Kopya Kağıdı Olarak /v1/models Yanıtı
/v1/models yanıtındaki her modele üç alan ekledik:
category: chat modeli, görsel oluşturucu, video modeli veya ses. Artık isimden tahmin yürütmek yok.pricing_unit: token başına, görsel başına, saniye başına veya istek başına. Maliyet tahmini için gereklidir.cache_pricing: üst akış prompt cache fiyatları artı platform semantik cache indirimi.
Mevcut alanlarla (fiyatlandırma, yetenekler, alias'lar, maksimum token'lar) birleştiğinde, bir agent tek bir API çağrısından tam donanımlı model seçimi kararları verebilir.
llms.txt: Agent'ın İlk Okuması
Biz api.lemondata.cc/llms.txt adresinde, tüm API'ın makine tarafından okunabilir bir özetini sunan dinamik bir llms.txt sunuyoruz. Şunları içerir:
- Çalışan kod içeren bir ilk çağrı şablonu
- Yaygın model adları (sabit kodlanmış değil, kullanım verilerinden otomatik oluşturulmuş)
- Parametreleri ile birlikte tüm 12 endpoint
- Model keşfi için filtre parametreleri
İlk API çağrısından önce bu dosyayı okuyan bir agent, muhtemelen ilk denemede doğru sonuca ulaşacaktır.
Bilgi Odaklı Değil, Veri Odaklı
Sistemimizdeki her öneri üretim verilerinden gelir. did_you_mean alias haritası, istek loglarımızdaki 30 günlük gerçek model_not_found hatalarından beslendi. Model önerileri gerçek kullanım modellerine göre sıralanır. llms.txt içindeki "yaygın model adları" veritabanımızdan oluşturulur.
Her model hatasını bir Redis sorted set içinde takip ediyoruz. Bir yanlış yazım yeterli hit sayısına ulaştığında, alias haritasına terfi ettirilir. Bir model çevrimdışı olduğunda, tüm önerilerden otomatik olarak kaybolur. Sistem kendi kendini geliştirir.
İşe Yaramasını Sağlayan Tasarım Kısıtlaması
Tek bir kural koyduk: yeni endpoint yok, yeni SDK yok, breaking change yok. Her şey mevcut OpenAI uyumlu hata formatı içinde çalışmalıydı. Yeni alanlar isteğe bağlıdır, bu nedenle onları görmezden gelen herhangi bir istemci eskisiyle aynı deneyimi yaşar.
Bu kısıtlama, kimsenin benimsemeyeceği karmaşık yeni API'lar inşa etmek yerine, bir agent'ın kendi kendini düzeltmesine gerçekte hangi bilgilerin yardımcı olacağı konusunda kesin olmamızı sağladı.
Kendi API'ınıza Agent-Öncelikli Tasarımı Nasıl Uygularsınız?
Eğer AI agent'larının tüketeceği API'lar inşa ediyorsanız:
- Her hata aksiyon alınabilir olmalıdır. Neyin yanlış gittiğini, nedenini ve bir sonraki adımda ne yapılacağını ekleyin.
- Alternatifler önerin, otomatik düzeltmeyin. Agent'ın bilinçli kararlar vermesine izin verin.
- Düz metin değil, yapılandırılmış alanlar kullanın.
did_you_meanayrıştırılabilir; bir dize içindeki "Şunu mu demek istediniz..." ayrıştırılamaz. - Önerileri gerçek verilere dayandırın. Üretim kullanım modelleri, sabit kodlanmış listelerden daha iyidir.
llms.txt, OpenAPI spesifikasyonları veya yapılandırılmış model listeleri aracılığıyla makine tarafından okunabilir keşif imkanı sunun.- Geriye dönük uyumluluğu koruyun. Yeni ipucu alanları eklemeli olmalı, asla bozucu olmamalıdır.
Her Şeyi Yeniden Yazmadan Nereden Başlamalı?
Çoğu ekibin tüm API'larını bir hafta içinde yeniden tasarlamasına gerek yoktur.
Pratik başlangıç noktası daha küçüktür:
- en yüksek hacimli hatalarınıza bir veya iki makine tarafından okunabilir ipucu alanı ekleyin
/v1/modelsveya eşdeğeri model keşif endpoint'ini daha zengin ve daha açık hale getirinllms.txtgibi makine tarafından okunabilir bir genel bakış yayınlayın- tüm döngüyü sadece curl ile değil, bir agent istemcisi ile test edin
Zaten bir gateway katmanı üzerinden çalışıyorsanız, birleşik AI gateway kılavuzu bu kontrol düzleminin neden önemli olduğunu gösterir. Hala doğrudan bir OpenAI uyumlu entegrasyondaysanız, migrasyon kılavuzu, daha agent dostu davranışlar eklemeden önce başlamak için en kolay yerdir.
SSS
Agent-öncelikli API tasarımı nedir?
Agent-öncelikli API tasarımı, hata yanıtlarının AI agent'larının insan müdahalesi veya harici dokümantasyon araması olmadan kendi kendilerini düzeltmelerine olanak tanıyan yapılandırılmış, makine tarafından okunabilir ipuçları içerdiği bir yaklaşımdır.
Agent-öncelikli tasarımın geliştirici-öncelikli API tasarımından farkı nedir?
Geliştirici-öncelikli API'lar insan tarafından okunabilirlik için optimize edilir: net hata mesajları, iyi dokümantasyon, yardımcı örnekler. Agent-öncelikli API'lar, makinelerin programatik olarak ayrıştırabileceği ve üzerinde işlem yapabileceği yapılandırılmış alanlar (did_you_mean, suggestions, hint) ekler.
Agent-öncelikli tasarım mevcut istemcileri bozar mı?
Hayır. Agent-öncelikli alanlar eklemelidir, yani mevcut istemciler bunları görmezden gelebilir ve değişmeden çalışmaya devam edebilir.
LemonData agent-öncelikli tasarımı nasıl uyguluyor?
LemonData'nın birleşik AI API gateway'i, 300'den fazla modelin tamamına yapılandırılmış hata ipuçları ekler. Her hata yanıtı aksiyon alınabilir öneriler içerir ve llms.txt endpoint'i makine tarafından okunabilir API keşfi sağlar.
LemonData, tek bir API üzerinden 300'den fazla AI modeline birleşik erişim sağlar. Agent-öncelikli API'ı 1$ başlangıç kredisi ile test etmek için ücretsiz deneyin.
