how-tos

Gemini 4 Carbon API ile Kodlama Ajanları: Akış ve Maliyet Korumalarıyla Sınırlı Bir Ajan Döngüsü

Poyo.ai Team
10 min read
Share:

Bir kodlama ajanı döngüsünü çalıştıran Gemini 4 Carbon API

Gemini 4 Carbon API, Google'ın en zor kodlama işleri için önerdiği modeldir. Google bu modeli çok adımlı hata ayıklama ve uzun soluklu ajan tabanlı kodlama için geliştirdi; Google'a göre model keşif, akıl yürütme ve doğrulama döngüleri için Argon'dan daha fazla token harcar. Bu rehber, gemini-4-carbon modelini (model sayfası) PoYo'nun OpenAI uyumlu uç noktası üzerinden bir kodlama ajanına bağlar. Ajan çıktısını akış olarak iletir, deponun büyük bir bölümünü okuyabilir, kesin bir tur ve dolar bütçesinde durur ve işi ne zaman Argon'a devredeceğini bilir.

Henüz ilk isteğinizi göndermediyseniz Gemini 4 Carbon API rehberi ile başlayın.

API'nin bir kodlama ajanına sağladıkları

ÖğePoYo üzerinde Gemini 4 Carbon
Model kimliğigemini-4-carbon
Burada kullanılan ajan uç noktasıPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Yerel alternatifPOST /v1beta/models/gemini-4-carbon:generateContent ve :streamGenerateContent
Bağlam penceresi1M token: metin, görsel, ses, video, PDF
Yanıt başına maksimum çıktı64K token
Akış"stream": true; son parça finish_reason ve usage bilgisini taşır
Fiyat1M token başına $1.60 girdi / $8.00 çıktı / $0.08 önbellek okuma (320 / 1,600 / 16 kredi)
Hız limitleriPoYo belgelerine göre LLM uç noktalarında şu anda hız limiti yoktur
Hatalar400 geçersiz alanlar, 401 hatalı anahtar, 402 yetersiz kredi, 404 bilinmeyen model; 429 / 500 / 502 / 503 için geri çekilmeyle (backoff) yeniden deneyin

Chat Completions belgeleri şu istek alanlarını tanımlar: model, messages (system, user veya assistant rolleriyle metin türünde content), max_tokens, stream, temperature, top_p, stop, n ve ceza (penalty) alanları. Aşağıdaki ajan yalnızca bunları kullanır.

Araç çağırma: bugün belgelenmiş olanlar

PoYo, tools alanını Anthropic Messages ve Responses için belgeler. Gemini modelleri için ise ne Chat Completions'ta ne de Gemini Native'de tools veya fonksiyon bildirimlerini belgeler. Responses, gemini-4-carbon için kullanılamaz.

Bu nedenle bu ajan bir tools dizisi göndermez. Bunun yerine düz mesaj içeriğinde bir JSON eylem protokolü kullanır. Sistem istemi izin verilen eylemleri listeler, model her turda tek bir JSON nesnesiyle yanıt verir, kodunuz bu eylemi çalıştırır ve sonucu bir sonraki kullanıcı mesajı olarak geri gönderir. Bu yöntem herhangi bir sohbet modeliyle çalışır. PoYo, Gemini için yerel fonksiyon çağırmayı belgelediğinde ayrıştırıcıyı gerçek araç çağrılarıyla değiştirip döngünün geri kalanını koruyabilirsiniz.

Bir güvenlik avantajı da var: Model yalnızca sizin yazdığınız dört eylemi isteyebilir. Rastgele bir kabuk komutu çalıştıramaz.

Uzun bağlamlı depo girdisi: 1M girdi, 64K çıktı

1M token'lık bir pencere, dosyaları tek tek getirmek yerine deponun büyük bir bölümünü ilk turda göndermenizi sağlar. Google'ın lansman tablosu bunu kullanmak için bir gerekçe sunar: Carbon, 256K–1M token aralığında GraphWalks'ta %96,2 puan alırken Argon %84,2 alır. Döngüyü üç sınır belirler:

  • Her tur tüm geçmişi yeniden gönderir. Anlık görüntü her çağrıda yeniden faturalandırılır. 12 tur boyunca 300K token'lık bir anlık görüntü en az 3,6M girdi token'ı eder; bu, herhangi bir çıktıdan önce 1M başına $1.60 fiyatla $5.76 demektir.
  • Çıktı yanıt başına 64K ile sınırlıdır. Tek bir yanıtta tüm depoyu yeniden yazdırmak yerine her write_file eylemi için tek bir dosya isteyin.
  • Token sayılarını tahmin etmeyin, ölçün. PoYo bir tokenizer uç noktası belgelemez. İlk çağrıdan usage.prompt_tokens değerini okuyun, ardından MAX_SNAPSHOT_CHARS değerini istediğiniz token bütçesine göre ayarlayın.

Önbellekleme. PoYo'nun fiyat tablosunda Carbon için bir önbellek okuma ücreti vardır (yeni girdi için $1.60'a karşılık 1M başına $0.08) ve Google önbelleğe alınmış girdiyi %95 indirimli fiyatlandırır. PoYo belgeleri, Gemini modelleri için bir önbellekleme istek parametresi veya önbelleğe alınmış token'lar için bir usage alanı tanımlamaz. Bu döngü hiçbir önbellekleme parametresi göndermez ve her istem token'ını tam girdi fiyatıyla bütçeler. Sistem istemini ve anlık görüntüyü değişmeyen bir önek olarak tutmanın maliyeti yoktur; faturanız, okumaların önbellek fiyatından ücretlendirilip ücretlendirilmediğini gösterecektir.

Python'da sınırlı ajan döngüsü

import json
import os
import subprocess
import time
from pathlib import Path

from openai import OpenAI, APIStatusError

client = OpenAI(api_key=os.environ["POYO_API_KEY"], base_url="https://api.poyo.ai/v1")

CARBON, ARGON = "gemini-4-carbon", "gemini-4-argon"
PRICE_IN, PRICE_OUT = 1.60, 8.00      # PoYo USD per 1M tokens, same for both (2026-11-16)

MAX_TURNS = 12
BUDGET_USD = 2.00
MAX_TOKENS_PER_TURN = 16_000          # Carbon allows up to 64,000
MAX_SNAPSHOT_CHARS = 400_000          # tune against usage.prompt_tokens
MAX_RESULT_CHARS = 20_000
REPO = Path("./my-repo").resolve()

SYSTEM = """You are a coding agent working in a Python repository.
Reply with exactly one JSON object and nothing else. Allowed actions:
{"action": "read_file", "path": "<relative path>"}
{"action": "write_file", "path": "<relative path>", "content": "<full file content>"}
{"action": "run_tests"}
{"action": "done", "summary": "<what changed and why>"}"""


def snapshot() -> str:
    parts, total = [], 0
    for p in sorted(REPO.rglob("*.py")):
        block = f"### {p.relative_to(REPO)}\n{p.read_text(encoding='utf-8', errors='replace')}\n"
        if total + len(block) > MAX_SNAPSHOT_CHARS:
            break
        parts.append(block)
        total += len(block)
    return "".join(parts)


def safe_path(rel: str) -> Path:
    p = (REPO / rel).resolve()
    if not p.is_relative_to(REPO):
        raise ValueError("path outside repository")
    return p


def execute(action: dict) -> str:
    kind = action.get("action")
    if kind == "read_file":
        return safe_path(action["path"]).read_text(encoding="utf-8", errors="replace")
    if kind == "write_file":
        safe_path(action["path"]).write_text(action["content"], encoding="utf-8")
        return "written"
    if kind == "run_tests":
        r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
        return f"exit={r.returncode}\n{r.stdout}\n{r.stderr}"
    raise ValueError(f"unknown action {kind!r}")


def call(model: str, messages: list):
    """One streamed turn. Returns (text, usage, finish_reason)."""
    for attempt in range(4):
        try:
            stream = client.chat.completions.create(
                model=model, messages=messages, max_tokens=MAX_TOKENS_PER_TURN, stream=True
            )
            text, usage, finish = [], None, None
            for chunk in stream:
                if chunk.choices:
                    choice = chunk.choices[0]
                    if choice.delta and choice.delta.content:
                        text.append(choice.delta.content)
                        print(choice.delta.content, end="", flush=True)
                    finish = choice.finish_reason or finish
                if getattr(chunk, "usage", None):
                    usage = chunk.usage
            return "".join(text), usage, finish
        except APIStatusError as e:
            if e.status_code in (429, 500, 502, 503) and attempt < 3:
                time.sleep(2 ** attempt)
                continue
            raise  # 400, 401, 402, 404: fix the request or the account, don't retry


def parse(text: str) -> dict:
    t = text.strip()
    if t.startswith("```"):
        t = t.strip("`").removeprefix("json").strip()
    return json.loads(t)


def run_agent(task: str, model: str = CARBON) -> dict:
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": f"Repository snapshot:\n{snapshot()}\n\nTask: {task}"},
    ]
    spent, last_prompt = 0.0, 0
    for turn in range(1, MAX_TURNS + 1):
        # Worst case for the next turn: at least last turn's input plus a full output
        worst_next = last_prompt / 1e6 * PRICE_IN + MAX_TOKENS_PER_TURN / 1e6 * PRICE_OUT
        if spent + worst_next > BUDGET_USD:
            return {"status": "budget_stop", "turns": turn - 1, "spent_usd": round(spent, 4)}

        text, usage, finish = call(model, messages)
        if usage is None:
            raise RuntimeError("no usage in stream; stopping so the budget stays enforceable")
        spent += usage.prompt_tokens / 1e6 * PRICE_IN + usage.completion_tokens / 1e6 * PRICE_OUT
        last_prompt = usage.prompt_tokens
        messages.append({"role": "assistant", "content": text})

        if finish == "length":
            messages.append({"role": "user", "content": "Reply was cut off. Send one shorter JSON action."})
            continue
        try:
            action = parse(text)
        except json.JSONDecodeError:
            messages.append({"role": "user", "content": "Reply with exactly one JSON object."})
            continue
        if action.get("action") == "done":
            return {"status": "done", "summary": action.get("summary"), "turns": turn, "spent_usd": round(spent, 4)}
        try:
            result = execute(action)
        except Exception as e:  # report the failure to the model instead of crashing
            result = f"error: {e}"
        messages.append({"role": "user", "content": f"Result of {action.get('action')}:\n{result[:MAX_RESULT_CHARS]}"})

    return {"status": "max_turns", "turns": MAX_TURNS, "spent_usd": round(spent, 4)}


if __name__ == "__main__":
    print(run_agent("tests/test_parser.py::test_unicode fails. Find the root cause and fix it."))

Path.is_relative_to için Python 3.9 veya üzeri gerekir. write_file dosyaların üzerine yazdığı için ajanı deponun bir kopyasında veya bir dalında çalıştırın.

Maliyet korumaları nasıl çalışır

KorumaNeyi durdururSayının kaynağı
MAX_TURNSHiç done çağırmayan döngüleriSizin seçiminiz; 12 bir başlangıç noktasıdır
BUDGET_USD + en kötü durum kontrolüBir sonraki çağrıda sınırın aşılmasınıSon akış parçasındaki usage.prompt_tokens ve usage.completion_tokens, PoYo'nun $1.60 / $8.00 fiyatıyla
MAX_TOKENS_PER_TURNKontrolden çıkan tek bir yanıtımax_tokens, Carbon için en fazla 64,000
MAX_RESULT_CHARSSonraki her turu şişiren devasa test günlükleriniSonuç geçmişe girmeden önce kırpma
usage is None → durÖlçemediğiniz sessiz harcamayıPoYo, son akış parçasında usage alanını belgeler
402 yeniden denenmezBoş bakiyede yeniden deneme fırtınalarınıPoYo hata kodları

Google, Carbon'un çıktısını düşünme token'ları dahil fiyatlandırır; bu yüzden bir tur, görünen JSON'dan daha fazla çıktı faturalandırabilir. Bütçenin completion_tokens kullanması ve aldığınız karakterleri asla saymamasının nedeni budur. Tahmin tüm girdiyi önbelleksiz sayar; dolayısıyla PoYo'nun faturalandıracağı tutarın üst sınırıdır. İlk birkaç çalıştırmada bunu panelinizle karşılaştırın.

En kötü durum kontrolü temkinlidir. 300K token'lık bir geçmişle bir tur daha, en az $0.48 girdi ve 16K max_tokens ile en fazla $0.128 çıktı maliyeti getirir. $2.00'lık bir bütçede döngü, sınırı aşabilecek çağrıdan önce durur.

Ne zaman Gemini 4 Argon'a geçilmeli

Argon aynı isteği kabul eder ve girdi ve çıktı token'ı başına aynı fiyattadır. Google onu "yazılım mühendisliği ve bilgi çalışmasının büyük çoğunluğu için ideal seçim" olarak tanımlar; daha hızlı yanıtlar verir ve tur başına daha az token harcar. Şu durumlarda run_agent(task, model=ARGON) ile ona yönlendirin:

  • Görev rutinse. Küçük düzeltmeler, tek dosyalık değişiklikler ve test yazımı, Carbon'un ek doğrulama token'larına ihtiyaç duymaz.
  • Tek bir yanıtın 64K token'ı aşması gerekiyorsa. Carbon çıktıyı 64K ile sınırlar. Argon rehberimiz, Argon'un çok daha büyük çıktı limitini ele alır.
  • Ucuz bir ilk deneme istiyorsanız. Önce Argon'u çalıştırın ve yalnızca testler hâlâ başarısız olursa Carbon'a yükseltin. Gemini 4 Carbon API ile Gemini 4 Argon API karşılaştırmasındaki yönlendirici bunu yapar.

Carbon'u depo genelinde kök neden analizi ve terminal ağırlıklı döngüler için saklayın. Google'ın tablosunda Carbon, Terminal-Bench 4.0 (AA) testinde Argon'un %57,1'ine karşı %65,2, SWE-sweep'te ise %4,3'e karşı %9,6 puan alır. Google'ın kullanılabilirlik duyurusu da bir iş bölümü önerir: mimari, koordinasyon ve denetim rolleri için Carbon, paralel işler için daha hızlı ve hafif modellerle birlikte. Bu döngüde bu, dosyaları Argon çalışanlarına atayan tek bir Carbon planlayıcı çalıştırması anlamına gelir.

Her iki modelin bütçeleri Gemini 4 Carbon API fiyatlandırma yazısında yer alır. Ajan için başka sağlayıcıları değerlendiriyorsanız Gemini 4 Carbon API, Claude Opus 5.5 API ve GPT-6 Astra API karşılaştırmasına bakın.

Sıkça sorulan sorular

Gemini 4 Carbon API, PoYo üzerinde fonksiyon çağırmayı destekliyor mu?

PoYo'nun güncel belgeleri, Gemini modelleri için Chat Completions veya Gemini Native'de tools ya da fonksiyon bildirimlerini tanımlamaz. Araçlar, Anthropic Messages ve Responses için belgelenmiştir. Bu rehber, mesaj içeriğinde yalnızca belgelenmiş alanlara ihtiyaç duyan bir JSON eylem protokolü kullanır.

Gemini 4 Carbon API ile OpenAI Python SDK'sını kullanabilir miyim?

Evet. OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") oluşturun ve chat.completions.create çağrısına model="gemini-4-carbon" geçin. Akış stream=True ile çalışır ve son parça usage bilgisini taşır.

Gemini 4 Carbon API'nin maksimum çıktısı ve bağlam penceresi nedir?

1M token bağlam ve yanıt başına en fazla 64K çıktı token'ı. max_tokens değerini 64,000 veya altına ayarlayın.

Bir ajan döngüsünde Gemini 4 Carbon API maliyetlerini nasıl sınırlarım?

Turları sınırlayın, tur başına max_tokens değerini sınırlayın, araç sonuçlarını kırpın ve şu ana kadarki harcama artı en kötü durumdaki bir sonraki tur bütçenizi aşacaksa durun. Harcamayı PoYo'da 1M token başına usage.prompt_tokens × $1.60 ve usage.completion_tokens × $8.00 üzerinden hesaplayın.

Gemini 4 Carbon API bağlam önbelleklemeyi destekliyor mu?

PoYo, Carbon için 1M token başına $0.08 (16 kredi) önbellek okuma fiyatı listeler. Belgeleri şu anda Gemini modelleri için bir önbellekleme istek parametresi veya önbelleğe alınmış token'lar için bir usage alanı tanımlamaz; bu nedenle istemleri tam girdi fiyatıyla bütçeleyin ve faturanızda önbellek fiyatından yapılan ücretlendirmeleri kontrol edin.

Bir kodlama ajanı ne zaman Carbon yerine Gemini 4 Argon kullanmalı?

Argon'u rutin kodlama için, 64K token'ı aşması gereken her tekil yanıt için ve Carbon'a yükseltmeden önce daha ucuz bir ilk deneme olarak kullanın. Her ikisi de PoYo'da 1M token başına $1.60 / $8.00 tutar, ancak Google'a göre Argon tur başına daha az token kullanır.

Share: