how-tos

Gemini 4 Carbon API für Coding-Agenten: eine begrenzte Agenten-Schleife mit Streaming und Kostenschutz

Poyo.ai Team
10 min read
Share:

Die Gemini 4 Carbon API als Antrieb einer Coding-Agenten-Schleife

Die Gemini 4 Carbon API ist Googles Wahl für die schwierigste Coding-Arbeit. Google hat das Modell für mehrstufiges Debugging und agentisches Coding mit langem Horizont gebaut und sagt, dass es mehr Token als Argon verbraucht, um zu erkunden, zu schlussfolgern und Verifikationsschleifen zu durchlaufen. Dieser Leitfaden bindet gemini-4-carbon (Modellseite) über PoYos OpenAI-kompatiblen Endpunkt in einen Coding-Agenten ein. Der Agent streamt seinen Output, kann einen großen Teil des Repositorys lesen, stoppt an einer festen Grenze für Turns und Dollar und weiß, wann er Arbeit an Argon übergeben sollte.

Wenn Sie noch keine erste Anfrage gesendet haben, beginnen Sie mit dem Gemini 4 Carbon API-Leitfaden.

Was die API einem Coding-Agenten bietet

PunktGemini 4 Carbon auf PoYo
Modell-IDgemini-4-carbon
Hier verwendeter Agenten-EndpunktPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Native AlternativePOST /v1beta/models/gemini-4-carbon:generateContent und :streamGenerateContent
Kontextfenster1M Token: Text, Bild, Audio, Video, PDF
Max. Output pro Antwort64K Token
Streaming"stream": true; der letzte Chunk enthält finish_reason und usage
Preis$1.60 Input / $8.00 Output / $0.08 Cache-Read pro 1M Token (320 / 1,600 / 16 Credits)
RatenlimitsLaut PoYos Dokumentation sind LLM-Endpunkte derzeit nicht ratenbegrenzt
Fehler400 ungültige Felder, 401 ungültiger Schlüssel, 402 nicht genügend Credits, 404 unbekanntes Modell; 429 / 500 / 502 / 503 mit Backoff wiederholen

Die Chat-Completions-Dokumentation dokumentiert diese Anfragefelder: model, messages (String-content mit den Rollen system, user oder assistant), max_tokens, stream, temperature, top_p, stop, n und die Penalty-Felder. Der Agent unten verwendet nur diese.

Tool Calling: was heute dokumentiert ist

PoYo dokumentiert tools für Anthropic Messages und für Responses. Für Gemini-Modelle dokumentiert es weder tools noch Function Declarations, weder in Chat Completions noch in Gemini Native. Responses ist für gemini-4-carbon nicht verfügbar.

Dieser Agent sendet daher kein tools-Array. Stattdessen nutzt er ein JSON-Aktionsprotokoll im normalen Message-Content. Der System-Prompt listet die erlaubten Aktionen auf, das Modell antwortet pro Turn mit einem JSON-Objekt, und Ihr Code führt diese Aktion aus und schickt das Ergebnis als nächste User-Message zurück. Das funktioniert mit jedem Chat-Modell. Sobald PoYo natives Function Calling für Gemini dokumentiert, können Sie den Parser durch echte Tool Calls ersetzen und den Rest der Schleife behalten.

Es gibt auch einen Sicherheitsvorteil: Das Modell kann nur vier Aktionen anfordern, die Sie selbst geschrieben haben. Es kann keinen beliebigen Shell-Befehl ausführen.

Repo-Input mit langem Kontext: 1M rein, 64K raus

Ein Fenster von 1M Token erlaubt es, im ersten Turn einen großen Teil des Repositorys zu senden, statt Dateien einzeln abzurufen. Googles Launch-Tabelle liefert einen Grund dafür: Carbon erreicht bei GraphWalks mit 256K–1M Token 96,2 %, gegenüber 84,2 % für Argon. Drei Limits prägen die Schleife:

  • Jeder Turn sendet den gesamten Verlauf erneut. Der Snapshot wird bei jedem Aufruf erneut abgerechnet. Ein Snapshot mit 300K Token über 12 Turns ergibt mindestens 3,6M Input-Token, also $5.76 bei $1.60 pro 1M, noch vor jedem Output.
  • Der Output ist auf 64K pro Antwort begrenzt. Fordern Sie eine Datei pro write_file-Aktion an, kein Rewrite des ganzen Repositorys in einer Antwort.
  • Token-Zahlen messen, nicht raten. PoYo dokumentiert keinen Tokenizer-Endpunkt. Lesen Sie usage.prompt_tokens aus dem ersten Aufruf und stimmen Sie dann MAX_SNAPSHOT_CHARS auf das gewünschte Token-Budget ab.

Caching. PoYos Preistabelle enthält einen Cache-Read-Tarif für Carbon ($0.08 pro 1M gegenüber $1.60 für neuen Input), und Google berechnet gecachten Input mit 95 % Rabatt. PoYos Dokumentation beschreibt für Gemini-Modelle weder einen Caching-Parameter in der Anfrage noch ein Usage-Feld für gecachte Token. Diese Schleife sendet keinen Caching-Parameter und kalkuliert jedes Prompt-Token zum vollen Input-Tarif. System-Prompt und Snapshot als unverändertes Präfix beizubehalten kostet nichts, und Ihre Rechnung zeigt, ob Reads zum Cache-Tarif abgerechnet wurden.

Die begrenzte Agenten-Schleife in Python

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 erfordert Python 3.9 oder neuer. Lassen Sie den Agenten auf einer Kopie oder einem Branch des Repositorys laufen, da write_file Dateien überschreibt.

So funktioniert der Kostenschutz

SchutzWas er verhindertWoher die Zahl kommt
MAX_TURNSSchleifen, die nie done aufrufenIhre Wahl; 12 ist ein Ausgangspunkt
BUDGET_USD + Worst-Case-PrüfungAusgaben über die Grenze beim nächsten Aufrufusage.prompt_tokens und usage.completion_tokens aus dem letzten Stream-Chunk, zu PoYos $1.60 / $8.00
MAX_TOKENS_PER_TURNEine einzelne ausufernde Antwortmax_tokens, höchstens 64,000 für Carbon
MAX_RESULT_CHARSRiesige Test-Logs, die jeden späteren Turn aufblähenKürzung, bevor das Ergebnis in den Verlauf gelangt
usage is None → StoppUnbemerkte Ausgaben, die Sie nicht messen könnenPoYo dokumentiert usage im letzten Stream-Chunk
402 wird nicht wiederholtRetry-Stürme bei leerem GuthabenPoYo-Fehlercodes

Google berechnet Carbons Output einschließlich Thinking-Token, ein Turn kann also mehr Output abrechnen als das sichtbare JSON. Deshalb verwendet das Budget completion_tokens und zählt nie die empfangenen Zeichen. Die Schätzung zählt jeden Input als ungecacht, sie ist also eine Obergrenze für das, was PoYo abrechnet. Gleichen Sie sie bei den ersten Läufen mit Ihrem Dashboard ab.

Die Worst-Case-Prüfung ist konservativ. Bei einem Verlauf von 300K Token kostet ein weiterer Turn mindestens $0.48 für den Input plus bis zu $0.128 für den Output bei max_tokens von 16K. Bei einem Budget von $2.00 stoppt die Schleife vor dem Aufruf, der die Grenze überschreiten könnte.

Wann Sie auf Gemini 4 Argon ausweichen sollten

Argon nimmt dieselbe Anfrage entgegen und kostet pro Input- und Output-Token gleich viel. Google nennt es „die ideale Wahl für den Großteil der Softwareentwicklung und Wissensarbeit“, mit schnelleren Antworten und geringerem Token-Verbrauch pro Turn. Routen Sie mit run_agent(task, model=ARGON) dorthin, wenn:

  • Die Aufgabe Routine ist. Kleine Fixes, Änderungen an einer einzelnen Datei und das Schreiben von Tests brauchen Carbons zusätzliche Verifikations-Token nicht.
  • Eine Antwort 64K Token überschreiten muss. Carbon begrenzt den Output auf 64K. Unser Argon-Leitfaden behandelt Argons deutlich höheres Output-Limit.
  • Sie einen günstigen ersten Versuch wollen. Lassen Sie zuerst Argon laufen und eskalieren Sie nur dann zu Carbon, wenn die Tests weiterhin fehlschlagen. Der Router in Gemini 4 Carbon API vs. Gemini 4 Argon API macht genau das.

Behalten Sie Carbon für repository-weite Ursachenanalyse und terminallastige Schleifen. In Googles Tabelle erreicht Carbon bei Terminal-Bench 4.0 (AA) 65,2 % gegenüber Argons 57,1 % und bei SWE-sweep 9,6 % gegenüber 4,3 %. Googles Verfügbarkeitsbeitrag schlägt außerdem eine Aufteilung vor: Carbon für Architektur-, Koordinations- und Audit-Rollen, kombiniert mit schnelleren, leichteren Modellen für parallele Arbeit. In dieser Schleife bedeutet das einen Carbon-Planer-Lauf, der Dateien an Argon-Worker verteilt.

Budgets für beide Modelle finden Sie im Beitrag zu den Preisen der Gemini 4 Carbon API. Wenn Sie für den Agenten auch andere Anbieter abwägen, lesen Sie Gemini 4 Carbon API vs. Claude Opus 5.5 API vs. GPT-6 Astra API.

Häufig gestellte Fragen

Unterstützt die Gemini 4 Carbon API auf PoYo Function Calling?

PoYos aktuelle Dokumentation beschreibt für Gemini-Modelle weder tools noch Function Declarations in Chat Completions oder Gemini Native. Tools sind für Anthropic Messages und Responses dokumentiert. Dieser Leitfaden verwendet ein JSON-Aktionsprotokoll im Message-Content, das nur dokumentierte Felder braucht.

Kann ich das OpenAI Python SDK mit der Gemini 4 Carbon API verwenden?

Ja. Erstellen Sie OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") und übergeben Sie model="gemini-4-carbon" an chat.completions.create. Streaming funktioniert mit stream=True, und der letzte Chunk enthält usage.

Wie groß sind maximaler Output und Kontextfenster der Gemini 4 Carbon API?

1M Token Kontext und bis zu 64K Output-Token pro Antwort. Setzen Sie max_tokens auf höchstens 64.000.

Wie begrenze ich die Kosten der Gemini 4 Carbon API in einer Agenten-Schleife?

Begrenzen Sie die Turns, begrenzen Sie max_tokens pro Turn, kürzen Sie Tool-Ergebnisse und stoppen Sie, wenn die bisherigen Ausgaben plus ein Worst-Case-Turn Ihr Budget überschreiten würden. Berechnen Sie die Ausgaben bei PoYo aus usage.prompt_tokens × $1.60 und usage.completion_tokens × $8.00 pro 1M Token.

Unterstützt die Gemini 4 Carbon API Kontext-Caching?

PoYo nennt für Carbon einen Cache-Read-Preis von $0.08 pro 1M Token (16 Credits). Die Dokumentation beschreibt für Gemini-Modelle derzeit weder einen Caching-Parameter in der Anfrage noch ein Usage-Feld für gecachte Token. Kalkulieren Sie Prompts daher zum vollen Input-Tarif und prüfen Sie Ihre Rechnung auf Abrechnungen zum Cache-Tarif.

Wann sollte ein Coding-Agent Gemini 4 Argon statt Carbon verwenden?

Verwenden Sie Argon für Routine-Coding, für jede einzelne Antwort, die 64K Token überschreiten muss, und als günstigeren ersten Versuch, bevor Sie zu Carbon eskalieren. Beide kosten bei PoYo $1.60 / $8.00 pro 1M Token, aber laut Google verbraucht Argon weniger Token pro Turn.

Share: