Yapay Zeka Ajanı API Rehberi: Ajan Mimarisi, Tool-Calling Şeması ve Döngü Maliyeti

Yapay zeka ajanı, bir dil modelini araç çağırma, bellek ve planlama katmanlarıyla döngüye alan yazılım desenidir; API tarafında her adım ayrı bir chat/completions isteğidir. Üretimdeki asıl sınav mimari değil maliyettir: geçmiş her adımda yeniden gönderildiği için token tüketimi katlanır. Bu rehber, katman katman mimariyi ve adım başı maliyet kontrolünü gerçek verilerle anlatıyor.

Türkçe kaynakların çoğu ajan kavramını tanımlayıp araç listeliyor; bir ajanı üretime taşıyan ekibin çarptığı ilk duvar ise tanım değil, fatura ve gecikmedir. Altı adımlık masum bir görev, tek soruluk bir sohbetin on katından fazla token yakabilir — ve bunu fark ettiğinizde ay sonu olmuş olur.

Bu yazıda ajan mimarisinin dört katmanını ve araç tanıtma şemasını, ayrıca — bu sorguda başka yerde bulamayacağınız — gerçek üretim trafiğinden gecikme ölçümlerini, TL karşılıklı adım başı maliyet hesabını ve bütçe kesicili çalışan bir Python ajan döngüsünü bulacaksınız.

Yapay Zeka Ajanı Mimarisi: Planlayıcı, Araçlar, Bellek ve Döngü

Bir yapay zeka ajanı dört katmandan oluşur: hedefi adımlara bölen planlayıcı, dış dünyayla konuşan araçlar, adımlar arasında bağlamı taşıyan bellek ve hepsini yöneten döngü (orkestrasyon) katmanı. Sohbet botundan farkı da budur: bot tek soruya tek yanıt üretir; ajan bir hedef alır ve hedefe ulaşana kadar araç çağırıp sonuç değerlendirmeyi sürdürür.

• Planlayıcı: Görevi alt adımlara bölen ve her turda "şimdi ne yapmalı?" kararını veren model çağrısıdır. Ajanın kalitesini büyük oranda bu katman belirlediği için genelde amiral sınıfı bir modelle çalıştırılır.
• Araçlar: Web araması, veritabanı sorgusu, kod çalıştırma gibi fonksiyonlardır. Kritik nokta: aracı model değil, sizin kodunuz çalıştırır — model yalnızca hangi aracın hangi parametreyle çağrılacağını söyler.
• Bellek: Kısa vadeli bellek zaten elinizdedir: messages dizisi. Uzun vadeli bellek için yaygın desen embedding + vektör veritabanıdır; burada dürüst olalım: Onysoft'ta ayrı bir /v1/embeddings ucu yoktur. İki mimari çözüm çalışır: geçmiş adımları ekonomik bir modelle özetleyip tek mesaja indirgeyen özet belleği (yine chat/completions ile) veya embedding üretimini harici ya da yerel bir servise bırakıp gateway'i yalnızca üretim katmanında kullanmak.
• Döngü: Model çıktısını yorumlar, aracı çalıştırır, sonucu geçmişe ekler ve tekrar modele döner. Durdurma koşulları — bitir kararı, adım sınırı, bütçe tavanı — bu katmanın sorumluluğudur ve üretimde en çok ihmal edilen kısım budur.

Katalogdaki 739+ modelin tamamı aynı şemayla çağrıldığı için katmanlar arasında model değiştirmek tek parametrelik iştir — bu, birazdan göreceğimiz maliyet stratejisinin de temelidir.

Tool-Calling Şeması: Araçları Modele Nasıl Tanıtırsınız?

Araçlar modele, fiili standart hâline gelmiş OpenAI fonksiyon şemasıyla tanıtılır: her araç bir ad, ne işe yaradığını anlatan açıklama ve parametreleri tanımlayan bir JSON Schema bloğundan oluşur. Model uygun gördüğünde düz metin yerine "şu aracı şu argümanlarla çağır" içeren yapılandırılmış bir yanıt döndürür.

{
  "type": "function",
  "function": {
    "name": "siparis_durumu",
    "description": "Siparis numarasina gore kargo durumunu dondurur.",
    "parameters": {
      "type": "object",
      "properties": {
        "siparis_no": {"type": "string", "description": "ORD- ile baslayan siparis numarasi"}
      },
      "required": ["siparis_no"]
    }
  }
}

Akış üç adımdır: (1) istekle birlikte tools listesini gönderirsiniz, (2) model yanıtında tool_calls alanı dönerse aracı kendi kodunuzda çalıştırırsınız, (3) sonucu konuşmaya ekleyip modele geri dönersiniz. Şemadaki description alanları prompt kadar önemlidir: model aracı bu metinlere bakarak seçer; belirsiz açıklama, yanlış araç seçiminin bir numaralı nedenidir.

Önemli uyarı: araç çağırma desteği modele ve sağlayıcıya göre değişir — her model tools parametresini aynı olgunlukta desteklemez. Bu yüzden aşağıdaki örnek döngüyü, araç kararını modelin düz JSON çıktısıyla verdiği ve her sohbet modeliyle çalışan protokol yaklaşımıyla kurduk; tools destekleyen modellerde aynı iskelet tool_calls ile birebir kurulabilir.

Ajan Döngüsünde Maliyet Neden Patlar? Adım Başı Hesap ve Katmanlı Model Seçimi

Çünkü her döngü adımı, o ana kadar biriken tüm geçmişi girdi olarak yeniden gönderir: 6 adımlık bir görevde ilk istem 6 kez, ikinci adımın araç çıktısı 5 kez faturalandırılır. Somutlaştıralım: sistem istemi + görev 1.500 token olsun; her adım geçmişe yaklaşık 800 token araç çıktısı ve 400 token model yanıtı eklesin. Altı adımın sonunda toplam 27.000 girdi + 2.400 çıktı tokeni ödersiniz. Aynı görevin farklı modellerdeki faturası:

Model	Girdi ($/1M)	Çıktı ($/1M)	1 görev (6 adım)	Günde 1.000 görev
anthropic/claude-opus-5	$7.50	$37.50	$0.2925 (13,91 TL)	13.910 TL
anthropic/claude-sonnet-5	$3.00	$15.00	$0.1170 (5,56 TL)	5.564 TL
google/gemini-3.6-flash	$2.25	$11.25	$0.0878 (4,17 TL)	4.173 TL
openai/gpt-5.6-terra	$1.50	$9.00	$0.0621 (2,95 TL)	2.953 TL
deepseek/deepseek-v4-flash	$0.21	$0.42	$0.0067 (0,32 TL)	318 TL
openai/gpt-5.6-luna	$0.15	$0.90	$0.0062 (0,30 TL)	295 TL

Ölçüm: 5 Ağustos 2026 — api.onysoft.com canlı katalog. TL karşılıkları 5 Ağustos 2026 TCMB kuru (1 USD = 47,555 TL) ile hesaplanmıştır. Senaryo: 6 adım, toplam 27.000 girdi + 2.400 çıktı tokeni.

Asıl kazanç katmanlı seçimde: planlama ve final sentezini anthropic/claude-sonnet-5'e (1. ve 6. adım), ara adımları openai/gpt-5.6-luna'ya verirseniz görev maliyeti $0.0431'e (2,05 TL) iner — her adımı Sonnet'e vermeye göre %63, Opus'a göre %85 tasarruf, planlama kalitesinden ödün vermeden. Günde 1.000 görevde fark: 13.910 TL yerine 2.051 TL. İkinci kaldıraç geçmiş hijyenidir: uzun araç çıktılarını olduğu gibi taşımak yerine döngü içinde kırpmak veya özetletmek, girdi tokenini doğrudan küçültür.

Adım tipini bilmediğiniz genel uçlarda seçimi onysoft/auto (OnyRouter) gateway'e devredebilir; ajan döngüsünde ise adımın planlama mı, araç yorumlama mı olduğunu zaten siz bildiğiniz için modeli adım tipine göre elle sabitlemek genelde daha isabetlidir. Toplu hesap için maliyet hesaplayıcıyı kullanabilirsiniz.

Onysoft'ta Nasıl Çalışıyor: cost Alanı ile Bütçeli Ajan Döngüsü (Python)

Onysoft AI Gateway OpenAI şemasını birebir izlediği için ajan döngüsü resmî openai paketiyle kurulur; tek fark base_url'dür. Aşağıdaki iskelet üç üretim önlemini içerir: adım sınırı, görev bütçesi ve her yanıt zarfında dönen cost alanıyla adım başı gerçek maliyet takibi:

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.onysoft.com/v1",
    api_key="sk-ony-AJAN-ANAHTARINIZ",  # ajana ozel, limitli anahtar
)

def web_ara(sorgu): ...   # kendi arama fonksiyonunuz
def hesapla(ifade): ...   # kendi hesap fonksiyonunuz
ARACLAR = {"web_ara": web_ara, "hesapla": hesapla}

SISTEM = ("Bir gorev ajanisin. Her adimda YALNIZ su JSON ile yanit ver: "
          "{\"dusunce\": \"...\", \"eylem\": \"web_ara | hesapla | bitir\", \"girdi\": \"...\"}")

mesajlar = [
    {"role": "system", "content": SISTEM},
    {"role": "user", "content": "Gorev: 3 rakip urunun fiyatini bul, TL ortalamasini hesapla."},
]

GOREV_BUTCESI_USD = 0.05
harcanan = 0.0

for adim in range(8):  # sonsuz dongu sigortasi
    yanit = client.chat.completions.create(
        model="openai/gpt-5.6-luna",  # ara adimlar: hiz sinifi
        response_format={"type": "json_object"},
        messages=mesajlar,
    )
    harcanan += (yanit.model_extra or {}).get("cost", 0.0)  # yanit zarfindaki gercek maliyet (USD)
    if harcanan > GOREV_BUTCESI_USD:
        raise RuntimeError(f"Gorev butcesi asildi: ${harcanan:.4f}")

    karar = json.loads(yanit.choices[0].message.content)
    if karar["eylem"] == "bitir":
        print(karar["girdi"])
        break

    sonuc = ARACLAR[karar["eylem"]](karar["girdi"])
    mesajlar.append({"role": "assistant", "content": yanit.choices[0].message.content})
    mesajlar.append({"role": "user", "content": f"Arac sonucu: {sonuc}"})

Döngüdeki cost alanı tahmin değil, o isteğin gateway tarafından kesilen gerçek USD maliyetidir; ayrı bir ölçüm aracı kurmadan adım başı harcamayı loglayıp görev bütçesini kod içinde kesebilirsiniz. Planlama adımında model parametresini amiral sınıfına çekmek tek satırlık iştir; kullanıcıya dönen final yanıtı da SSE akışıyla (stream=True) token token basabilirsiniz.

Bütçe kesiciniz hata yapsa bile ikinci bir emniyet vardır: Onysoft her isteği göndermeden önce tahmini maliyetin 1,2 katını bakiyenizle karşılaştırır; karşılanmıyorsa istek sağlayıcıya hiç gitmeden HTTP 402 döner — kaçak bir döngü bakiyeyi eksiye süremez. Üçüncü katman anahtar bazlıdır: ajana panelden ayrı bir sk-ony anahtarı üretip kendi harcama limitini tanımlarsanız, en kötü senaryoda zarar o anahtarın limitiyle sınırlı kalır; ana uygulamanızın anahtarına dokunulmaz. Şema ayrıntıları API dokümantasyonunda.

Adım Bütçesi: Gerçek Gecikme Verisiyle Ajan Süresini Planlama

Ajanın toplam süresi kabaca adım sayısı × adım gecikmesidir ve bunu tahminle değil ölçümle planlamak gerekir. Kendi üretim trafiğimizden rakamlar: son 14 günde gateway üzerinden geçen 6.959 istekte ortalama uçtan uca yanıt süresi 3,8 saniye, en hızlısı 0,3 saniye ölçüldü. Ortalama profille 6 adımlık bir ajan yaklaşık 23 saniye sürer — arka plan işi için sorun değil, canlı kullanıcı karşısında kabul edilemez.

Süre bütçesi pratikte üç kararla kurulur:

• Adım sayısını küçültün: En büyük kazanç buradadır; iyi bir planlayıcı üç araç çağrısını tek turda toplayabilir, birbirinden bağımsız araç adımları paralel de çalıştırılabilir.
• Ara adımları hız sınıfına verin: 0,3 saniyelik taban hafif modellerle ölçüldü; luna/flash sınıfı ara adımlar döngü turunu saniyenin altına çekebilir.
• Final yanıtı akıtın: Son adımda SSE ile ilk token birkaç saniyede ekrana düşer; kullanıcının algıladığı bekleme, toplam sürenin çok altına iner.

Üretime çıkmadan önce beş maddelik kontrol listesi: adım sınırı, cost alanıyla görev bütçesi, ajana özel anahtar ve limiti, gecikme hedefi, adım başı loglama. Genel çerçeve için Yapay Zeka API rehberine, maliyet mekanizmalarının tamamı için maliyet kontrolü yazısına bakın; ücretsiz hesap açıp ilk ajan istemlerinizi Playground'da deneyebilirsiniz.

Son güncelleme: 5 Ağustos 2026 · Veriler: api.onysoft.com canlı katalog