Agent-Öncelikli API Tasarımı: AI Agent'larının Gerçekten Anlayabileceği API'lar Nasıl İnşa Edilir?
Ç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 insanlar değil — 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 prensip etrafında nasıl yeniden tasarladığımızın hikayesidir: akıllı olma, bilgilendirici ol. Sonuç, agent-öncelikli API tasarımı dediğimiz şeydir — ve bu, 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 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ında Neden Başarısız Olur?
Bir AI agent'ı tipik bir API toplayıcısına (aggregator) ilk kez ulaştığında neler olduğuna bakın:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
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 olumlu senaryo (happy path) — agent doğru dokümantasyon URL'sini tahmin etti.
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 Prensip: 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 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: statik alias eşleme (tahmin değil, üretim verilerinden), normalize edilmiş dize eşleştirme ve sınırlı düzenleme mesafesi (edit distance). Tüm adaylar canlı model listesine göre doğrulanır — şu anda çevrimdışı olan bir modeli asla önermeyiz.
Desen 2: Yetersiz Bakiye → Bütçe Duyarlı 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öyleriz. Agent, insan müdahalesi olmadan 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 yönelik canlı bir sorgudur. Agent, şu anda gerçekte neyin çalıştığına dair gerçek zamanlı bilgi alır.
Desen 4: Rate Limit'e Takıldı → Kesin Yeniden 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 (exponential backoff) yok. Agent tam bekleme süresini bilir. Rate limit'leri etkili bir şekilde yönetmek hakkında daha fazlası 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 modeliyle `/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 diyoruz: "bu çalıştı, ancak daha iyi bir yol var." Agent, bir sonraki çağrıda yerel (native) endpoint'e geçebilir — OpenAI uyumlu formatta bulunmayan genişletilmiş düşünme (extended thinking) ve prompt caching gibi özelliklere erişim sağlayabilir.
Bunu yanıt gövdesine değil, header'lara koyuyoruz çünkü gövde OpenAI/Anthropic spesifikasyonunu takip eder. 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 mi, görsel oluşturucu mu, video modeli mi yoksa ses mi? Artık isimden tahmin yürütmek yok.pricing_unit— token başına, görsel başına, saniye başına, 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ı
api.lemondata.cc/llms.txt adresinde dinamik bir llms.txt sunuyoruz — tüm API'ın makine tarafından okunabilir bir özeti. Şunları içerir:
- Çalışan kod içeren bir ilk çağrı şablonu
- Yaygın model adları (kullanım verilerinden otomatik oluşturulmuş, kodlanmış değil)
- Parametrelerle 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 başarılı olacaktı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ı
Bir kural koyduk: yeni endpoint yok, yeni SDK yok, bozucu değişiklik (breaking change) yok. Her şey mevcut OpenAI uyumlu hata formatı içinde çalışmalıydı. Yeni alanlar isteğe bağlıdır — onları görmezden gelen herhangi bir istemci (client), eskisiyle aynı deneyimi yaşar.
Bu kısıtlama, kimsenin benimsemeyeceği karmaşık yeni API'lar inşa etmek yerine, hangi bilgilerin bir agent'ın kendi kendini düzeltmesine gerçekten yardımcı olduğu konusunda hassas 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ı — 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_mean` ayrıştırılabilir, bir dize içindeki "Şunu mu demek istediniz..." değildir
- Önerileri gerçek verilere dayandırın — üretim kullanım modelleri, sabit listelerden daha iyidir
- Makine tarafından okunabilir keşif imkanı sunun —
llms.txt, OpenAPI spesifikasyonları veya yapılandırılmış model listeleri - Geriye dönük uyumluluğu koruyun — yeni ipucu alanları eklemeli olmalı, asla bozucu olmamalıdır
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 tasarımdan farkı nedir?
Geliştirici-öncelikli API'lar insan tarafından okunabilirliği optimize eder: 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 — JSON yanıtındaki ekstra alanlar. Onları bilmeyen istemciler sadece görmezden gelir. Mevcut entegrasyonlar değişmeden çalışmaya devam eder.
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'ı lemondata.cc adresinde deneyin.
