Agent-First API Tasarımı: AI Agent'ların Gerçekten Anlayabileceği API'lar Nasıl İnşa Edilir

Çoğu API; dokümantasyon okuyan, örnekleri inceleyen ve stack trace'ler ile hata ayıklayan insan geliştiriciler için tasarlanmıştır. 2026 yılı itibarıyla API trafiğinin giderek artan bir kısmı AI ajanlarından gelmektedir ve bu ajanlar API'larla insanlar gibi etkileşime girmezler.

İşte TokenLab'in birleşik AI API'sini tek bir prensip etrafında nasıl yeniden tasarladığımız: "Akıllı olmaya çalışma, bilgilendirici ol." Bu yaklaşıma agent-first (ajan öncelikli) API tasarımı diyoruz ve bu sayede kullanıcılarımızın boşa harcadığı token miktarını %60'tan fazla azalttık.

Önemli Çıkarımlar

• Agent-first API tasarımı, hata yanıtlarına yapılandırılmış ve makine tarafından okunabilir ipuçları ekler; böylece AI ajanları web araması yapmadan veya insan yardımı almadan kendi hatalarını düzeltebilirler.
• Otomatik düzeltme yapmak yerine alternatifler önerin. did_you_mean, suggestions ve retryable gibi alanlar, ajanların kararların onlar adına verilmesi yerine bilinçli kararlar almasını sağlar.
• Her öneri üretim verilerine dayalıdır; bu sayede çevrimdışı veya desteği kesilmiş modeller asla aday listesinde görünmez.
• İpucu alanları eklemeli ve geriye dönük uyumludur; bu nedenle mevcut OpenAI uyumlu istemciler hiçbir değişiklik yapmadan çalışmaya devam eder.

Agent-First API Tasarımı Nedir?

Agent-first API tasarımı, yanıtlarınızı (özellikle hata yanıtlarını) bir AI ajanının neyin yanlış gittiğini anlayabileceği ve konuşmadan ayrılmadan bunu düzeltebileceği şekilde yapılandırmak anlamına gelir.

Geleneksel API hatası:

{"error": {"message": "Model not found"}}

Agent-first API hatası:

{
  "error": {
    "code": "model_not_found",
    "message": "Model 'gpt5.5' not found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
    "hint": "Use GET /v1/models to list all available models."
  }
}

Geleneksel bir API ile ajan web'de arama yapmak, dokümantasyonu bulmak, HTML'i ayrıştırmak ve tahmin yürütmek zorundadır. Agent-first bir API ile ise tek bir adımda kendi hatasını düzeltir.

Geleneksel API'lar Neden AI Ajanlarında Başarısız Olur?

Bir ajanın tipik bir API toplayıcısına ilk kez bağlandığında neler olduğuna bakın:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (tokenlab modeller listesi için web'de arama yapar)
Agent: (bir dokümantasyon sayfası getirir, belki de yanlış olanı)
Agent: (HTML'i ayrıştırır, bir model adı bulur)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

Altı adım, birden fazla ağ isteği, yüzlerce boşa harcanan token. Üstelik bu, ajanın şans eseri doğru dokümantasyon URL'sini tahmin ettiği "başarılı" senaryodur.

Agent-first tasarım ile:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

İki adım, sıfır web araması. Ajan, sadece hata yanıtından yola çıkarak kendi hatasını düzeltti.

Temel Prensip: Zeka Model Tarafında Kalır

Model adını otomatik düzelten, sessizce benzer bir şeye yönlendiren veya bir öneri motoru ekleyen "akıllı" API'lar oluşturma cazibesi vardır. Biz bunların hepsini reddettik.

Bir ajan model: "gpt5.5" gönderdiğinde, aslında niyetini bilemezsiniz. Belki daha yeni bir GPT sürümünün olup olmadığını kontrol ediyordur. Belki katı bir bütçe kısıtlaması vardır. Belki sadece tek bir modelin desteklediği belirli bir yeteneğe ihtiyacı vardır. gpt-5.5'e otomatik yönlendirme yapmak, maliyeti, kaliteyi ve yetenekleri sessizce değiştirir ve ajan bunun gerçekleştiğini asla bilemez.

Daha iyi bir hamle, hızlı ve bilgilendirici bir şekilde hata vermektir. Ajana tüm verileri verin ve kararı onun vermesine izin verin.

Dört Agent-First API Tasarım Deseni

Desen 1: Model Bulunamadı → Bulanık Öneriler

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [
      {"id": "gpt-5.5"},
      {"id": "gemini-3.5-flash"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
  }
}

did_you_mean, üç katmanlı bir çözümleme kullanır: üretim verilerinden gelen statik takma ad eşlemesi, normalleştirilmiş dize eşleştirme ve sınırlı düzenleme mesafesi. Her aday canlı model listesine göre kontrol edilir, bu nedenle şu anda çevrimdışı olan bir modeli asla önermeyiz.

Desen 2: Yetersiz Bakiye → Bütçe Farkındalıklı Alternatifler

{
  "error": {
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
      {"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

Sadece "yetersiz bakiye" demek yerine, ajana tam olarak ne kadar parası olduğunu, ne kadar gerektiğini ve şu anda hangi modelleri karşılayabileceğini söylüyoruz. Ajan, insan müdahalesi olmadan daha ucuz bir AI modeline otonom olarak geçiş yapabilir. Maliyet eşiklerini kodlamadan önce TokenLab model dizinindeki güncel model bazlı fiyatlandırmayı doğrulayın.

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-5", "status": "available"},
      {"id": "gpt-5.5", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-8' temporarily unavailable. Retry in 30s or try an alternative."
  }
}

alternatives listesi statik değildir. Kanal sağlık verilerimize karşı yapılan canlı bir sorgudur, bu nedenle ajan, güncelliğini yitirmiş olabilecek sabit bir yedek liste yerine şu anda neyin gerçekten çalıştığına dair gerçek zamanlı bilgi alır.

Desen 4: Hız Sınırı Aşı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 bir değerden başlayan üstel geri çekilme (exponential backoff) yok. Ajan tam bekleme süresini bilir. Hız sınırlarını yönetme hakkında daha fazla bilgi için AI API hız sınırlama rehberimize göz atın.

Başarılı Yanıtlar da İpuçları Taşır

Bir ajan bir Claude modeliyle /v1/chat/completions çağrısı yaptığında, yanıt şunları içerir:

X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

Ajana şunu söylüyoruz: "Bu çalıştı, ancak daha iyi bir yol var." Bir sonraki çağrıda yerel uç noktaya geçebilir ve OpenAI uyumlu formatta sunulmayan genişletilmiş düşünme (extended thinking) ve prompt önbelleğe alma gibi özelliklerden yararlanabilir.

Bu ipuçları yanıt gövdesinde değil, başlıklarda (headers) bulunur çünkü gövde, OpenAI veya Anthropic spesifikasyonuna tam olarak uymak zorundadır. Başlıklar, mevcut ayrıştırma mantığını bozmayacak güvenli genişletme noktalarıdır.

Bir Ajan Kopya Kağıdı Olarak /v1/models Yanıtı

/v1/models yanıtındaki her model girdisine üç alan ekledik:

• category: sohbet modeli, görsel oluşturucu, video modeli veya ses. İsimden tahmin yürütmeye son.
• pricing_unit: token başına, görsel başına, saniye başına veya istek başına. Her türlü gerçek maliyet tahmini için gereklidir.
• cache_pricing: yukarı yönlü prompt önbellek fiyatları artı platformun anlamsal önbellek indirimi.

Mevcut alanlarla (fiyatlandırma, yetenekler, takma adlar, maksimum token) birleştirildiğinde, bir ajan tek bir API çağrısından tamamen bilinçli bir model seçimi yapabilir. Tüm canlı kataloğu TokenLab model dizininde (2026-07-07 itibarıyla gözlemlenmiştir) görebilirsiniz; bu dizin şu anda Claude Sonnet 5, GPT-5.5 ve Gemini 3.5 Flash gibi güncel öncü seçenekler dahil olmak üzere sohbet, görsel, video ve ses kategorilerinde 300'den fazla modeli listelemektedir. Bu makaledeki rakamların güncel olduğunu varsaymak yerine, o sayfadaki güncel fiyatlandırmayı ve kullanılabilirliği doğrulayın.

llms.txt: Ajanın İlk Okuması

api.tokenlab.sh/llms.txt adresinde, tüm API'nin makine tarafından okunabilir bir özeti olan dinamik bir llms.txt sunuyoruz. Şunları içerir:

• Çalışan kod içeren bir ilk çağrı şablonu
• Sabit kodlanmış yerine kullanım verilerinden otomatik oluşturulan yaygın model adları
• Parametreleriyle birlikte 12 uç noktanın tamamı
• Model keşfi için filtre parametreleri

İlk API çağrısından önce bu dosyayı okuyan bir ajanın, isteği ilk denemede doğru yapma olasılığı çok daha yüksektir.

Bilgi Odaklı Değil, Veri Odaklı

Sistemdeki her öneri üretim verilerinden gelir. did_you_mean takma ad haritası, istek günlüklerimizdeki 30 günlük gerçek model_not_found hatalarından oluşturulmuştur. Model önerileri gerçek kullanıma göre sıralanır. llms.txt içindeki "yaygın model adları" listesi elle tutulmaz, veritabanımızdan oluşturulur.

Her model hatasını bir Redis sıralı kümesinde takip ediyoruz. Bir yazım hatası yeterince hit topladığında, takma ad haritasına terfi eder. Bir model çevrimdışı olduğunda, tüm öneri listelerinden otomatik olarak düşer. Sistem, GPT-5.5, Claude Sonnet 5 ve Gemini 3.5 Flash gibi yeni model sürümleri çakışan zaman çizelgelerinde yayınlandığında önemli olan güncelliğini yitirme sorunu yerine zamanla kendini ayarlar.

İşe Yarayan Tasarım Kısıtlaması

Tek bir kural koyduk: yeni uç nokta yok, yeni SDK yok, bozucu değişiklik yok. Her şey mevcut OpenAI uyumlu hata formatına sığmak zorundaydı. Yeni alanlar isteğe bağlıdır, bu nedenle onları görmezden gelen herhangi bir istemci, eskisinden tam olarak aynı deneyimi alır.

Bu kısıtlama, kimsenin benimsemeyeceği karmaşık yeni API'lar oluşturmak yerine, bir ajanın kendi hatasını düzeltmesine gerçekten neyin yardımcı olduğu konusunda hassasiyet gerektirdi.

Agent-First Tasarımını Kendi API'nize Nasıl Uygularsınız?

Eğer AI ajanlarının tüketeceği API'lar oluşturuyorsanız:

1. Her hatayı eyleme dönüştürülebilir kılın. Neyin yanlış gittiğini, nedenini ve bir sonraki adımda ne yapılması gerektiğini belirtin.
2. Otomatik düzeltme yerine alternatifler önerin. Ajanın bilinçli kararı vermesine izin verin.
3. Düz metin yerine yapılandırılmış alanlar kullanın. did_you_mean ayrıştırılabilir; bir cümlenin içine gömülmüş "bunu mu demek istediniz..." ifadesi ayrıştırılamaz.
4. Önerileri gerçek verilere dayandırın. Üretim kullanım kalıpları, güncelliğini yitiren sabit kodlanmış bir listeden daha iyidir.
5. llms.txt, bir OpenAPI spesifikasyonu veya yapılandırılmış bir model listesi aracılığıyla makine tarafından okunabilir keşif imkanı sunun.
6. 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 ekip tüm API'larını bir haftada yeniden tasarlamak zorunda değildir. Daha küçük bir başlangıç noktası gayet iyi çalışır:

1. En yüksek hacimli hatalarınıza bir veya iki makine tarafından okunabilir ipucu alanı ekleyin.
2. /v1/models veya eşdeğer keşif uç noktanızı daha zengin ve daha belirgin hale getirin.
3. llms.txt gibi makine tarafından okunabilir bir genel bakış yayınlayın.
4. Tüm döngüyü sadece curl ile değil, gerçek bir ajan istemcisiyle test edin.

Eğer zaten bir ağ geçidi katmanı üzerinden çalışıyorsanız, birleşik AI ağ geçidi rehberi bu kontrol düzleminin neden önemli olduğunu açıklar. Hala doğrudan OpenAI uyumlu bir entegrasyonda iseniz, ajan dostu davranışları katmanlamadan önce geçiş rehberi başlamak için en kolay yerdir.

SSS

Agent-first API tasarımı nedir?

Hata yanıtlarının yapılandırılmış, makine tarafından okunabilir ipuçları (did_you_mean, suggestions ve hint gibi alanlar) içerdiği bir yaklaşımdır; böylece AI ajanları insan müdahalesi veya dokümantasyon araması olmadan kendi hatalarını düzeltebilirler.

Agent-first, developer-first API tasarımından nasıl farklıdır?

Developer-first API'lar insan okunabilirliğini optimize eder: net mesajlar, iyi dokümanlar, yararlı örnekler. Agent-first API'lar, makinelerin hatayı ayrıştırıp programatik olarak harekete geçebilmesi için bunun üzerine yapılandırılmış alanlar ekler.

Agent-first tasarımı mevcut istemcileri bozar mı?

Hayır. Alanlar eklemelidir. did_you_mean veya suggestions alanlarını aramayan mevcut istemciler bunları basitçe görmezden gelir ve eskisi gibi çalışmaya devam eder.

---

TokenLab, model dizininde listelenen tek bir API aracılığıyla GPT-5.5, Claude Sonnet 5 ve Gemini 3.5 Flash gibi güncel öncü modeller dahil olmak üzere 300'den fazla AI modeline birleşik erişim sağlar. Agent-first API'yi 1 dolarlık başlangıç kredisiyle test etmek için ücretsiz başlayın.