AgentMesh Gateway tam olarak nedir?

1. Tek cümlede temel fikir

AgentMesh bir AI istemcisi ile bir veya daha fazla model sağlayıcısı arasında durur. İstemci isteği AgentMesh'e gönderir; AgentMesh önce hangi sağlayıcının isteği anlam kaybı olmadan işleyebileceğini belirler, sonra uygun protokol adapteri üzerinden upstream çağrıyı yapar.

2. Hangi sorunu çözüyor?

Yerel ve uzak AI sağlayıcıları API biçimi, model desteği, tool calling, reasoning özellikleri, fiyat, gecikme, güvenilirlik ve kota bakımından farklıdır. Bir istemci doğrudan tek sağlayıcıya bağlanırsa değiştirmek zorlaşır. Bir router yalnızca “en ucuz” veya “en hızlı” seçimi yaparsa, isteğin anlamını koruyamayan bir sağlayıcıyı seçebilir.

AgentMesh protokol dönüşümünü, sağlayıcıya özel ağ kodunu ve yönlendirme politikasını birbirinden ayırır. İstemci tek bir gateway'e konuşabilir; provider ayrıntıları adapter katmanında kalır.

Tipik kullanım alanları

• Kodlama ajanına tek bir yerel endpoint verip upstream sağlayıcıları sonradan değiştirmek.
• Normal metin için yerel modeli tercih etmek, ancak kayıpsız çevrilemeyen Responses semantiği için native provider kullanmak.
• İlk sağlayıcı başarısız olursa, streaming başlamadan önce ikinci sağlayıcıya geçmek.
• Gerçek token kullanımı ve gecikme ölçümlerini routing ipuçlarından ayrı tutmak.
• Canlı API maliyeti olmadan politikaları çevrimdışı araştırmak.

3. Bir istek geldiğinde ne oluyor?

4. Ana bileşenler

Protokol adapterleri

İstemci tarafındaki wire formatlarını anlar. Projede OpenAI Chat Completions, OpenAI Responses ve Anthropic Messages biçimli girişler vardır.

Protokolden bağımsız domain modeli

Normalize mesajlar, request/response ve stream parçaları router ve service katmanının vendor ayrıntılarına bağlanmasını engeller.

Provider adapterleri

Outbound HTTP davranışını sahiplenir. v0.3.0'da generic OpenAI-compatible, Anthropic-compatible ve native Responses-compatible adapter bulunur.

Provider registry

Konfigürasyonu gerçek adapter örneklerine dönüştürür.

Router

Önce uygun sağlayıcı kümesini çıkarır, sonra seçilen üretim politikasına göre sıralar.

Runtime state store

Hatalar, ardışık hatalar, EWMA gecikmesi, son başarılı gecikme penceresi, p50/p95, token/cost, circuit ve yerel kota kullanımını tutar.

Gateway service

Provider attempt'lerini ve failover'ı koordine eder; streaming başladıktan sonra sessiz provider değişimine izin vermez.

Çevrimdışı araştırma katmanı

Gerçek provider URL'lerine dokunmadan deterministik trace'leri tekrar oynatır. Uyarlanabilir politikalar v0.3.0'da burada yaşar.

5. Hangi API'leri sunuyor?

Responses yüzeyi bilinçli olarak “tam OpenAI uyumluluğu” diye sunulmaz. Metin, custom function loop'ları, test edilen native reasoning koruması ve tanınan native tool semantiği için destek vardır; ancak upstream Responses platformunun tamamı çok daha geniştir.

6. Yönlendirme mantığı nasıl çalışır?

AgentMesh uygunluk ile tercihi ayırır.

Sert uygunluk kapıları

• İstenen model destekleniyor mu?
• Provider circuit'i açık mı kapalı mı?
• İstek semantiği kayıpsız çevrilebilir mi?
• Gerekli capability'ler var mı?
• Yerel request quota tükenmiş mi?

Üretim politikaları

• ordered: konfigüre edilen sıraya/ağırlığa göre.
• latency: canlı gecikme sinyaline göre.
• cost: konfigüre cost_hint değerine göre.
• quality: konfigüre quality_hint değerine göre.
• balanced: gecikme, maliyet ve kaliteyi birleştiren sabit politika.

v0.3.0'da gözlenen USD maliyeti otomatik olarak production cost score'unun yerine geçmez; p50/p95 de EWMA'yı sessizce değiştirmez. Ölçüm ile canlı politika bilinçli olarak ayrı tutulur.

7. Bir provider nasıl tanımlanır?

Provider tanımı ad, adapter tipi, base URL, model listesi, secret environment variable adı, ağırlık, cost/latency/quality hint, capability listesi, token fiyatı ve isteğe bağlı yerel quota içerebilir.

Mevcut capability boyutları text, tools, reasoning ve native_responses_tools'dur. Açıkça capability verilirse otoriter kabul edilir; verilmezse adapter tabanlı varsayılanlar kullanılır.

Gerçek secret hiçbir zaman provider JSON içine yazılmak zorunda değildir; yalnızca environment variable adı referans edilir.

8. Provider başarısız olursa ne olur?

Network ve HTTP hataları ortak bir hata modeline çevrilir. Ağ hataları, timeout, conflict, too-early, rate limit ve server error gibi bazı durumlar retryable kabul edilebilir; çoğu diğer 4xx hata terminaldir.

Runtime ardışık hataları izler ve circuit breaker ile bir provider'ı geçici süreyle uygun kümeden çıkarabilir. Sonraki başarılı çağrı failure state'i sıfırlar.

Streaming için kritik kural şudur: ilk çıktı parçası istemciye gönderildikten sonra AgentMesh başka provider'ın stream'ini aynı cevaba eklemez.

9. Hangi ölçümler tutuluyor?

Gecikme

Başarılı attempt'ler EWMA'yı ve sınırlı bir son-başarı penceresini günceller. p50/p95 nearest-rank ile deterministik hesaplanır.

Token ve maliyet

Upstream exact input/output token sayısını verirse ve her iki token fiyatı konfigüre edilmişse gözlenen maliyet hesaplanır. Eksik kullanım veya fiyat “sıfır” yapılmaz ve metin uzunluğundan tahmin edilmez.

Failure/circuit

Başarı, hata, ardışık hata ve güvenli son hata özeti tutulur.

Yerel quota

İsteğe bağlı fixed request-attempt window başarısız denemeler dahil outbound attempt sayar. Bu vendor'ın özel RPM/TPM veya billing sayacı değildir.

10. Araştırma simülatörü ne yapıyor?

Simülatör provider konfigürasyonu ve JSONL counterfactual outcome trace'i okur. Provider URL'lerine hiçbir network çağrısı yapmaz. Her politika fresh state ile tekrar oynatılır.

Çıktı JSON veya CSV olabilir; böylece istatistiksel analiz ve grafik üretimine uygundur.

Statik baselines

ordered, latency, cost, quality, balanced.

Uyarlanabilir araştırma baselines

adaptive_balanced gelişen evidence ile constrained multi-objective score kullanır. constrained_ucb seçilen-provider feedback'i kullanan contextual UCB tarzı deneysel bir baseline'dır.

11. Araştırmacı bununla ne inceleyebilir?

• Maliyet kısıtı altında gecikme minimizasyonu.
• Kalite kısıtı altında maliyet minimizasyonu.
• Burst workload altında quota-aware routing.
• Capability kısıtlarının “en iyi provider” sonucunu nasıl değiştirdiği.
• Statik ve contextual/adaptive politika karşılaştırması.
• Exploration–exploitation dengesi.
• Circuit failure'ların feasible set'i zaman içinde nasıl değiştirdiği.
• Fiyat, quality profile ve latency distribution hassasiyeti.
• Eksik ölçümlerin yanlışlıkla sıfır kabul edilmesinin etkisi.

Quality profile şeması benchmark ID, sürüm, kaynak, metric ve sample count gibi provenance alanlarını zorunlu kılar. Bu yapı tekrar üretilebilirliği destekler; bir benchmark'ın bilimsel kalitesini otomatik garanti etmez.

12. Güvenlik modeli

• Gerçek API key repo içine commit edilmez.
• Provider secret'ları environment variable'lardan okunur.
• İsteğe bağlı bearer token gateway ve admin endpoint'lerini korur.
• Request ID'ler izlenebilirlik sağlar.
• Upstream hata içerikleri secret sızıntısını önlemek için normalize edilir.
• Varsayılan olarak harici telemetry gönderilmez.

13. Tekrar üretilebilirlik ve araştırma bütünlüğü

Varsayılan test ve simülasyon yolu ücretli API key gerektirmez. CI Python 3.11, 3.12 ve 3.13 üzerinde Ruff ve pytest çalıştırır. Mimari kararlar ADR olarak kaydedilir. PROVENANCE kuralları başka gateway'lerden source, test, dokümantasyon, asset veya internal structure kopyalanmasını yasaklar.

v0.3.0 Zenodo'da 10.5281/zenodo.22069468 DOI ile arşivlenmiştir.

14. Gelecekte neler eklenebilir?

15. v0.3.0 neyi iddia etmiyor?

• Tüm OpenAI Responses özellikleriyle tam uyumluluk iddiası yoktur.
• Tam Codex, Claude Code, Cline veya OpenCode implementasyonu değildir.
• Tüm native reasoning/tool semantiğini vendorlar arasında çevirmez.
• Image/audio cross-protocol normalization henüz yoktur.
• Context-window-aware routing henüz yoktur.
• Yerel quota vendor billing/rate-limit state ile eşdeğer değildir.
• Upstream usage yoksa observed cost eksik kalabilir.
• Adaptive/UCB politikaları production'da aktif değildir.
• Sentetik örnek trace'lerden performans üstünlüğü iddia edilmez.