AI agent maliyet kontrolü nasıl yapılır?

Sürekli çalışan bir AI agent'ın maliyetini artırmasını nasıl önlenir

Bir VPS (virtual private server) üzerinde AI agent maliyet kontrolü, agent çalışmaya başlamadan önce belirlenen üst limitlerle ilgilidir; çünkü çalışma sırasında kullanım miktarını takip eden biri yoktur. Her yanıtı max_tokens ile sınırlandırın, döngü yinelemelerini kendi kodunuzda kısıtlayın, prompt'un değişmeyen kısımlarını önbelleğe alın ve hangi işin ne kadar harcadığını görmek için her yanıtın kullanım verilerini kaydedin. Sunucu kirası sabit aylık bir fiyattır. Model API'si ise token başına ücretlendirilir ve denetimsiz bir döngü, token kullanımını sessizce artırmak konusunda oldukça başarılıdır.

Bu durum, halihazırda var olan ve size ait bir cihazdan Messages API'sini çağıran bir agent için geçerlidir. VPS üzerinde Claude ile bir AI agent oluşturma içeriği mekanizmanın kendisini kapsamaktadır.

Unattended bir agent neden farklı bir maliyet yapısına sahiptir

Etkileşimli bir oturumda bir insan bulunur. Model yanlış bir yola girdiğinde veya 40,000 satırlık bir log dosyasını okuduğunda, izleyen kişi işlemi durdurur. Unattended bir agent'ın böyle bir fren mekanizması yoktur: döngü sona erene kadar çalışır, ardından bir zamanlayıcı işlemi tekrar başlatır.

İnsanların gözden kaçırdığı çarpan faktörü frekanstır. Beş dakikalık bir programla çalışan bir iş, günde 288 kez ve ayda yaklaşık 8,640 kez çalışır. Tek bir çalıştırmanın maliyeti ne olursa olsun, çarpan uygulanacak tutar budur. Birçok "her zaman açık" agent'ın sürekli açık kalmasına gerek yoktur. Belirli bir dakika içinde yanıt vermeleri gerekir, bu da bir programdır.

Bir agent ayrıca bir sohbet penceresinin ödemediği kalemler için de maliyet oluşturur.

• Tool tanımları her istekte gönderilir. Tool-use system prompt maliyeti, Claude Opus 4.8 ile tool_choice auto veya none durumunda 290 token, any veya tool durumunda ise 410 tokendir. Bash tool kullanımı 325 token daha ekler. Eklediğiniz her MCP server, MCP (model context protocol) şemalarını bu yüke dahil eder.
• Tool sonuçları input token'larıdır. 8,000 satır yazdıran bir komut, bir sonraki isteğe ve o turdaki sonraki tüm isteklere 8,000 satır ekler.
• Getirilen sayfalar input token'larıdır. Ortalama 10 kB bir web sayfası yaklaşık 2,500 token, 500 kB bir araştırma PDF'i ise yaklaşık 125,000 tokendir. max_content_tokens sadece metin içeriklerini kırpar, çünkü bu "PDF'ler gibi binary içerikler için değil, metin içerikleri için geçerlidir". Bunun yerine PDF'leri max_uses ve allowed_domains ile sınırlandırın.
• Web araması arama başına fiyatlandırılır. Kaç sonuç dönerse dönsün, 1,000 arama başına 10$ olarak ücretlendirilir. Hata veren bir arama faturalandırılmaz.

Bunların hiçbiri tek seferde pahalı değildir. Hepsi 8,640 kez çalıştırıldığında pahalıdır.

Hard ceilings ve soft ceilings farklı sorunları çözer

max_tokens uygulanır. Bu, düşünme ve yanıt metni toplamı olan tek bir isteğin toplam çıktısı için belirlenmiş katı bir üst sınırdır. Claude bu sınırı asla geçmez ve model bu sayıyı göremez. Sınıra ulaşıldığında stop_reason: "max_tokens" hatası alınır ve yanıt kesilir. Agent'lar için kritik nokta: araç kullanımı döngüsündeki her istek kendi max_tokens değerini taşır; bu nedenle sınır tek bir yanıtı değil, görevi kapsar. 4,000 tokenlık on araç çağrısı, o tur için 40,000 tokenlık bir üst sınır oluşturur.

Görev bütçesi tavsiyeidir. task_budget, output_config içerisinde yer alır; modele düşünme, araç çağrıları, araç sonuçları ve çıktı dahil olmak üzere tüm agent döngüsü için kaç tokeni olduğunu bildirir.

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["task-budgets-2026-03-13"],
    output_config={"task_budget": {"type": "tokens", "total": 64000}},
    messages=messages,
)

"Görev bütçeleri katı bir sınır değil, yumuşak bir ipucudur." Claude, işlem sırasında bir sınırı aşabilir ve çıktı üzerindeki zorunlu limit hala max_tokens olarak kalır. "Geri sayım sadece model tarafından görülebilir" ve yanıtlar kalan bütçe alanı içermez. Kabul edilen minimum task_budget.total 20,000 tokendır; daha düşük değerler 400 hatası döndürür. İş için çok küçük bir bütçe, reddetme benzeri davranışlara yol açar; bu durumda model görevi küçültür veya işlemi erken durdurur.

Bir detay, tasarruf sağlamak yerine maliyeti artırır. Eğer istemciniz her takip eden istekte task_budget.remaining değerini azaltıyorsa, değişen değer bu değeri içeren tüm önbelleğe alınmış (cached) prefix'leri geçersiz kılar. Değeri ilk istekte bir kez ayarlayın.

Görev bütçeleri Claude Fable 5, Claude Opus 4.8 ve Claude Opus 4.7 modellerinde beta aşamasındadır. Claude Sonnet 5 ve Claude Haiku 4.5 modelleri Not supported olarak listelenmiştir; görev bütçeleri Claude Code için geçerli değildir, bu nedenle tmux içinde ayrılmış bir Claude Code oturumu oturum düzenine bağlıdır.

Üçüncü sınır Claude Console içerisinde bulunur: agent'a kendi çalışma alanını (workspace) tanımlayın, ardından ona aylık harcama limiti ve dakika başına hız limiti atayın. "Default Workspace üzerinde limit ayarlanamaz" ve "Workspace limitlerinin toplamı daha yüksek olsa bile organizasyon genelindeki limitler her zaman geçerlidir". Üst sınıra ulaşılmadan önce sizi uyarması için harcama bildirimlerini ekleyin.

İş başına model seçimi ve asıl maliyeti değiştiren unsur

Model seçimi iş başına verilen bir karardır. Temmuz 2026 itibarıyla, her bir milyon token başına giriş ve çıkış maliyetleri şöyledir: Claude Fable 5 için 10$ ve 50$, Claude Opus 4.8 ve Opus 4.7 için 5$ ve 25$, Claude Sonnet 5 için 3$ ve 15$, Claude Haiku 4.5 için 1$ ve 5$. Sonnet 5 şu an etiket fiyatının altındadır; çünkü "1 milyon giriş/çıkış tokenı için 2$/10$ tutarındaki tanıtım fiyatı 31 Ağustos 2026 tarihine kadar geçerlidir". Sadece log satırlarını sınıflandıran bir adım için Opus modeline ihtiyaç yoktur.

İkinci değişken ise effort parametresidir. output_config.effort; low, medium, high, xhigh ve max değerlerini kabul eder. Varsayılan değer high olduğundan, high değerini açıkça belirtmek parametreyi atlamakla aynı sonucu verir. Düşük effort kullanımı, akıl yürütme uzunluğundan daha fazla tasarruf sağlar: dokümantasyon, bu ayarın Claude'un daha az tool call yapmasını ve operasyonları tek bir işlemde birleştirmesini sağladığını belirtmektedir. Bir agent yapısında bu durum daha büyük tasarruf sağlar; çünkü kaçınılan her tool call, gerçekleşmeyen tam bir request demektir.

Buradaki risk, effort ayarının cache mekanizmasıyla çelişmesidir. İstekler arasında değer değiştirmek prompt caching özelliğini geçersiz kılar. Dokümante edilen örnekte, 2. istek cache_read_input_tokens: 3546 raporlamıştır; effort değeri yüksekten orta seviyeye değiştirilen 3. istek ise 3546 cache_creation_input_tokens ve 0 cache_read_input_tokens raporlamıştır. Bu nedenle, effort değerini iş yükleri arasında değiştirin, önbelleğe alınmış tek bir konuşma içinde asla değiştirmeyin. Cache yapısını bozmadan derinliği yönlendirmek için bunu prompt içinde yapın: en yeni kullanıcı mesajına "Deliberate etmeden doğrudan cevap ver." gibi bir satır eklemek, önceki breakpoint noktalarını sağlam tutar.

Thinking tokenları çıkış (output) oranları üzerinden ücretlendirilir ve max_tokens limitine dahil edilir; bu nedenle yarıda kesilen cevaplar genellikle düşünme sürecinin bütçeyi tükettiği anlamına gelir. Sayısal değer için usage.output_tokens_details.thinking_tokens kısmını okuyun. Claude faturalarını asıl ne doldurur bağlantısı konuyu detaylıca incelemektedir.

Stabil prefixi önbelleğe alın ve kazara bozulmasını engelleyin

Beş dakikalık önbellekte bir yazma işlemi, temel girdi fiyatının 1.25 katına mal olur; bir saatlik önbellekte ise bu oran 2 katıdır. Bir okuma işlemi 0.1 katına mal olur. Bu nedenle "5 dakikalık süre için sadece bir okumadan sonra (1.25x yazma), veya 1 saatlik süre için iki okumadan sonra (2x yazma) önbellekleme kârlı hale gelir".

Bu durumun sürekli çalışan bir ajan için neden uygun olduğu şu şekilde açıklanır: "Önbelleğe alınan içerik her kullanıldığında, ek bir maliyet olmaksızın önbellek yenilenir." Beş dakikalık önbelleğe karşı her iki dakikada bir çalışan bir iş, tek bir yazma işlemiyle prefixi gün boyunca sıcak tutar.

Fark edilmeden önbelleğin kaybedilmesinin üç yolu.

Değişen bir prefix. "Önbellek prefixleri şu sırayla oluşturulur: tools, system, ardından messages." Bu sıralamadaki herhangi bir erken byte değişikliği, kendisinden sonra gelen her şeyi geçersiz kılar; araç tanımlamalarını düzenlemek ise tüm önbelleği geçersiz kılar. Klasik bir hata, sistem istemindeki (system prompt) bir zaman damgası veya bir çalışma kimliğidir (run id): bu durumda her istek farklı bir prefix taşır, 1.25x maliyetle yeni bir kayıt yazar ve hiçbir veri okuyamaz. Belirtisi, birbirine benzeyen çağrılarda usage.cache_read_input_tokens değerinin 0 olmasıdır. Değişken metni en yeni kullanıcı mesajına taşıyın.

Çok kısa bir prefix. Her modelin minimum önbelleklenebilir uzunluğu vardır; bu değerin altındaki istekler önbellekleme yapılmadan işlenir ve "hata döndürülmez". Rakamlar Claude Opus 4.8 ve Claude Sonnet 5 için 1,024 token, Claude Haiku 4.5 için ise 4,096 token'ı içerir; bu nedenle bir işi Sonnet'ten Haiku'ya taşımak, önbellekleme özelliğini sessizce kapatabilir.

Bakış penceresini aşan bir konuşma. "Bakış penceresi 20 bloktur." Sistem, her kesme noktasında (breakpoint) en fazla 20 konumu kontrol eder ve durur. Belgelenen örnekte, 35. blokta kesme noktası olan ve 35 blok içeren bir tur, 35'ten 16'ya kadar olan blokları kontrol eder; bir önceki turun 15. bloktaki kaydı pencerenin dışında kaldığı için bir eşleşme (hit) sağlanmaz. Her turda birkaç araç kullanımı (tool-use) ve araç sonucu (tool-result) bloğu ekleyen bir ajan, iki veya üç turda 20 bloğu geçer. İstek başına dört kesme noktası elde edilir, bu nedenle birini son mesajlara ayırın.

Bekleyebilecek tüm verileri Batches API'ye gönderin

Hem girdi hem de çıktı için "tüm kullanımlar standart API fiyatlarının %50'si oranında ücretlendirilir". Toplu işlem (batch processing) asenkrondur; "çoğu toplu işlem 1 saatten kısa sürede tamamlanır". Sonuçlar, tüm istekler bittiğinde veya en geç 24 saat sonra iletilir. Bu süre tipik bir süredir, garanti edilmez.

processing_status değeri ended olana kadar sorgulama (poll) yapın. errored, canceled veya expired döndüren istekler için ücretlendirme yapılmaz. Harcama limiti kullanıyorsanız şu hususa dikkat edilmelidir: "toplu işlemler, Workspace için yapılandırılan harcama limitini biraz aşabilir."

İndirimler birikerek uygulanır. Bir toplu işlemin beş dakikadan uzun sürebilmesi nedeniyle, dokümantasyon aynı bağlamı paylaşan toplu işlemler için bir saatlik önbelleği (cache) önermektedir. İş yükünü şu şekilde bölün: bir kişinin veya bir webhook'un beklediği her şey canlı (live) yolda kalsın; gece özeti veya dünkü log sınıflandırması gibi işlemler ise yarı fiyatına toplu işleme (batch) dahil edilsin.

Her yanıtın kullanım alanlarını kendi veri depolama alanınıza kaydedin

Kaydedilmeyen harcamalar takip edilemez. Her yanıt maliyet bilgilerini içerir.

u = resp.usage
row = {
    "job": job_name,
    "model": resp.model,
    "uncached_input": u.input_tokens,
    "cache_write": u.cache_creation_input_tokens,
    "cache_read": u.cache_read_input_tokens,
    "output": u.output_tokens,
    "stop_reason": resp.stop_reason,
}

Her API çağrısı için iş adıyla etiketlenmiş bir satırı JSON-lines dosyasına ekleyin. Bir hafta sonra hangi işin harcama yaptığını, hangisinin sadece yoğun göründüğünü tespit edebilirsiniz. cache_read değerini kontrol edin: sıfırlardan oluşan bir sütun, self-hosted bir agent için en yaygın maliyet hatasıdır.

Bir alanın yanlış okunması kolaydır. input_tokens sadece son cache kesme noktasından sonraki tokenları sayar, bu nedenle gerçek prompt boyutu total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens değeridir. Büyük bir prompt için input_tokens: 400 raporlayan bir agent ucuz değildir; geri kalan kısım cache'den gelmiştir.

Göndermeden önce sayım yapın. Token sayımı ücretsizdir ve hız limitleri mesaj oluşturmadan ayrıdır; bu nedenle, aşırı boyutlu bir eki keşfetmek için ödeme yapmak yerine count_tokens kullanarak reddedin. Sonuç bir tahmindir, bu nedenle her model için yeniden ölçüm yapın ve başka bir sağlayıcının tokenizer değerini asla tekrar kullanmayın. Claude Opus 4.7 ve sonraki Opus modelleri, Claude Fable 5 ve Claude Sonnet 5, "aynı metin için yaklaşık %30 daha fazla token üreten" yeni bir tokenizer kullanır. Claude Sonnet 4.6 ve öncesi, Claude Haiku 4.5 dahil olmak üzere, önceki tokenizer'ı kullanır.

Kesin veriler için Admin API, kullanımı https://api.anthropic.com/v1/organizations/usage_report/messages ve maliyeti https://api.anthropic.com/v1/organizations/cost_report olarak raporlar. Her ikisi de anthropic-version: 2023-06-01 ile x-api-key: $ANTHROPIC_ADMIN_KEY olarak bir admin key (sk-ant-admin01-...) alır ve bucket_width=1d, group_by[]=model ve api_key_ids[]= kabul eder. Bir kısıtlama: "Admin API bireysel hesaplar için kullanılamaz."

Bu son parametre düşük maliyetli bir ilişkilendirme yöntemidir: her işe kendi API key değerini verin, api_key_ids[] ile filtreleyin ve raporu group_by[]=api_key_id ile anahtarlara göre bölün. Filtre çoğul, gruplandırma boyutu ise tekildir. Anahtarları kod içinde değil, bir VPS üzerindeki ilk Claude API uygulaması içinde yapıldığı gibi ortam değişkenlerinde (environment) tutun.

Bound the loop, because nothing else will

A bounded iteration count is not optional here. The loop is yours, so the counter is yours:

for step in range(MAX_STEPS):          # MAX_STEPS = 12, never "while True"
    resp = client.messages.create(...)
    if resp.stop_reason != "tool_use":
        break
else:
    log.warning("job %s hit MAX_STEPS=%d, giving up", job_name, MAX_STEPS)

Neither ceiling above does it for you: max_tokens caps one response, and the model is only advised of a task budget.

Put a second brake outside the process. Run the job from a systemd timer instead of a permanent process, and set RuntimeMaxSec= on its service unit. With RuntimeMaxSec=600, a hung run is killed after ten minutes instead of spinning until you notice. Running a program as a systemd service and timer covers the unit files themselves. Read what a run did with journalctl -u triage-agent.service --since "1 hour ago".

Cap retries as well, because a handler that retries forever bills every attempt. A 429 or a 500 deserves a few tries with backoff. A 400 deserves none, since the same request fails the same way.

AI agent maliyet kontrolü kendi verilerinizi okumakla başlar

Sürekli çalışan bir agent'ın maliyetini kimse size söyleyemez. Çünkü maliyet, işlem başına token sayısı ile günlük işlem sayısının çarpımıdır ve her iki veri de size aittir. Agent'ı bir kez çalıştırın, günlüğe kaydedilen kullanım satırını okuyun ve bunu planlanan işlem sayınızla çarpın. İki gün sonra maliyet raporunu bu hesaplamayla karşılaştırın. İki değer uyuşmuyorsa, aradaki fark neredeyse her zaman bozuk bir cache veya tahmin ettiğinizden uzun süren bir döngüden kaynaklanır.

Bu durum bir API key kullanımı varsayımıyla geçerlidir, çünkü agent Messages API'sini çağıran kendi programınızdır. Kendi etkileşimli çalışmalarınız için çalışma şeklinize en uygun Claude planı abonelik tarafını kapsar. Buradaki tüm fiyatlar ve limitler Temmuz 2026 tarihinde Anthropic dokümantasyonu ile kontrol edilmiştir; bu nedenle bütçe oluşturmadan önce fiyatlandırma sayfasını tekrar okuyun.

FAQ

Bir VPS üzerinde sürekli açık bir AI agent çalıştırmanın maliyeti nedir?

İki farklı fatura oluşur ve bunlardan sadece biri öngörülebilirdir. Sunucu sabit bir aylık ücrete tabidir. Model API'si token başına ücretlendirilir; maliyet, bir çalıştırmanın tükettiği miktar ile çalıştırma sıklığının çarpımıdır. Anthropic, kendi sunucusunda barındırılan sürekli açık bir agent için herhangi bir rakam yayınlamamaktadır, bu nedenle verilen tüm rakamlar tahmini olarak kabul edilmelidir. Bir gerçek çalıştırmadan usage kaydını alın ve bunu planlanan çalışma sıklığınızla çarpın.

max_tokens ile task budget arasındaki fark nedir?

max_tokens uygulanır ve model için görünmezdir. Bu değer, düşünme süreci dahil olmak üzere tek bir isteğin çıktısını sınırlar ve bu sınıra ulaşıldığında stop_reason: "max_tokens" hatası alınır. Task budget ise bunun tersidir: modele sayı verilir ve agent döngüsü bu sayıya göre ayarlanır, ancak "Task budgets are a soft hint, not a hard cap" (Görev bütçeleri katı bir sınır değil, esnek bir ipucudur) ve uygulanan limit hala max_tokens değeridir.

Agent'ım için cache_read_input_tokens neden her zaman sıfır?

Çünkü çağrılar arasında prefix değişmektedir veya önbelleğe alınamayacak kadar kısadır. Yaygın neden, sistem promptuna dahil edilen bir timestamp veya run id değeridir: cache, prefix üzerinden anahtarlanır, bu nedenle herhangi bir byte değişikliği kendisinden sonra gelen her şeyi geçersiz kılar. Tool tanımlarını veya effort değerini değiştirmek de aynı sonucu doğurur. Diğer bir neden ise boyuttur; kısa promptlar önbelleğe alınmaz ve hata döndürülmez.

Bir AI agent'ın sonsuz döngüye girmesini nasıl durdurabilirim?

Döngü kodunuzda iterasyonları sayın ve sabit bir maksimum değerde durdurun; çünkü max_tokens tek bir yanıtı sınırlar ancak bir agent birçok yanıt üretir. İşlem dışında bir zaman sınırı ekleyin: işi, RuntimeMaxSec= ayarlanmış bir systemd timer ile başlatın, böylece takılı kalan bir çalıştırma planlanan zamanda sonlandırılır. Yeniden denemeleri (retries) de sınırlayın, çünkü her deneme için ücretlendirilirsiniz.

Tek bir Claude API key için harcama limiti belirleyebilir miyim?

Belgelenen harcama limiti anahtar başına değil, workspace bazlıdır; bu nedenle agent'a kendine ait bir workspace tanımlayın ve aylık harcamasını orada sınırlayın. "You cannot set limits on the Default Workspace" (Varsayılan Workspace üzerinde limit belirleyemezsiniz). Bir eşik değer sizi uyarsın diye harcama bildirimlerini ekleyin. Harcamaları takip etmek için her işe kendi key'ini tanımlayın ve kullanım raporunu group_by[]=api_key_id ile gruplandırın.