how-tos

Gemini 4 Carbon API voor coding agents: een begrensde agentlus met streaming en kostenbewaking

Poyo.ai Team
11 min read
Share:

De Gemini 4 Carbon API als motor van een coding-agentlus

De Gemini 4 Carbon API is de keuze van Google voor het zwaarste codeerwerk. Google bouwde hem voor debuggen in meerdere stappen en agentisch coderen met lange horizon, en zegt dat hij meer tokens dan Argon besteedt aan verkennen, redeneren en het draaien van verificatielussen. Deze gids koppelt gemini-4-carbon (modelpagina) via het OpenAI-compatibele endpoint van PoYo aan een coding agent. De agent streamt zijn output, kan een groot deel van de repository lezen, stopt bij een harde limiet op beurten en dollars, en weet wanneer hij werk aan Argon moet overdragen.

Heb je nog geen eerste verzoek verstuurd, begin dan met de Gemini 4 Carbon API-gids.

Wat de API een coding agent biedt

OnderdeelGemini 4 Carbon op PoYo
Model-IDgemini-4-carbon
Hier gebruikt agent-endpointPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Native alternatiefPOST /v1beta/models/gemini-4-carbon:generateContent en :streamGenerateContent
Contextvenster1M tokens: tekst, afbeelding, audio, video, PDF
Max. output per antwoord64K tokens
Streaming"stream": true; de laatste chunk bevat finish_reason en usage
Prijs$1.60 input / $8.00 output / $0.08 cache read per 1M tokens (320 / 1,600 / 16 credits)
Rate limitsVolgens de documentatie van PoYo hebben LLM-endpoints momenteel geen rate limit
Fouten400 ongeldige velden, 401 ongeldige sleutel, 402 onvoldoende credits, 404 onbekend model; 429 / 500 / 502 / 503 opnieuw proberen met backoff

De Chat Completions-documentatie documenteert deze verzoekvelden: model, messages (string-content met de rollen system, user of assistant), max_tokens, stream, temperature, top_p, stop, n en de penaltyvelden. De agent hieronder gebruikt alleen die velden.

Tool calling: wat er nu gedocumenteerd is

PoYo documenteert tools voor Anthropic Messages en voor Responses. Voor Gemini-modellen documenteert het geen tools of function declarations, niet in Chat Completions en niet in Gemini Native. Responses is niet beschikbaar voor gemini-4-carbon.

Deze agent stuurt dus geen tools-array. In plaats daarvan gebruikt hij een JSON-actieprotocol in gewone berichtcontent. De systeemprompt noemt de toegestane acties, het model antwoordt per beurt met één JSON-object, en jouw code voert die actie uit en stuurt het resultaat terug als het volgende user-bericht. Dit werkt met elk chatmodel. Zodra PoYo native function calling voor Gemini documenteert, kun je de parser vervangen door echte tool calls en de rest van de lus behouden.

Er is ook een veiligheidsvoordeel: het model kan alleen vier acties aanvragen die je zelf hebt geschreven. Het kan geen willekeurig shellcommando uitvoeren.

Repo-input met lange context: 1M erin, 64K eruit

Met een venster van 1M tokens kun je in de eerste beurt een groot deel van de repository meesturen, in plaats van bestanden één voor één op te halen. De launchtabel van Google geeft een reden om dat te doen: Carbon scoort 96,2% op GraphWalks bij 256K–1M tokens, tegenover 84,2% voor Argon. Drie limieten bepalen de vorm van de lus:

  • Elke beurt stuurt de hele geschiedenis opnieuw. De snapshot wordt bij elke aanroep opnieuw gefactureerd. Een snapshot van 300K tokens over 12 beurten is minstens 3,6M input-tokens, en dat is $5.76 bij $1.60 per 1M, nog vóór enige output.
  • Output is beperkt tot 64K per antwoord. Vraag om één bestand per write_file-actie, niet om een herschrijving van de hele repository in één antwoord.
  • Meet tokenaantallen, gok ze niet. PoYo documenteert geen tokenizer-endpoint. Lees usage.prompt_tokens uit de eerste aanroep en stem MAX_SNAPSHOT_CHARS daarna af op het tokenbudget dat je wilt.

Caching. De prijstabel van PoYo bevat een cache-read-tarief voor Carbon ($0.08 per 1M, tegenover $1.60 voor nieuwe input), en Google rekent gecachete input met 95% korting. De documentatie van PoYo beschrijft voor Gemini-modellen geen cachingparameter in het verzoek en geen usageveld voor gecachete tokens. Deze lus stuurt geen cachingparameter mee en budgetteert elk prompt-token tegen het volledige inputtarief. De systeemprompt en snapshot als ongewijzigd prefix houden kost niets, en je factuur laat zien of er reads tegen het cachetarief zijn gerekend.

De begrensde agentlus 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 vereist Python 3.9 of nieuwer. Draai de agent op een kopie of een branch van de repository, want write_file overschrijft bestanden.

Hoe de kostenbewaking werkt

BewakingWat het voorkomtWaar het getal vandaan komt
MAX_TURNSLussen die nooit done aanroepenJouw keuze; 12 is een startpunt
BUDGET_USD + worst-casecontroleBij de volgende aanroep over het plafond gaanusage.prompt_tokens en usage.completion_tokens uit de laatste streamchunk, tegen de $1.60 / $8.00 van PoYo
MAX_TOKENS_PER_TURNEén op hol geslagen antwoordmax_tokens, maximaal 64,000 voor Carbon
MAX_RESULT_CHARSEnorme testlogs die elke latere beurt opblazenInkorten voordat het resultaat in de geschiedenis komt
usage is None → stoppenOnzichtbare uitgaven die je niet kunt metenPoYo documenteert usage in de laatste streamchunk
402 niet opnieuw proberenRetry-stormen bij een leeg saldoFoutcodes van PoYo

Google rekent de output van Carbon inclusief thinking-tokens, dus een beurt kan meer output factureren dan de zichtbare JSON. Daarom gebruikt het budget completion_tokens en telt het nooit de tekens die je hebt ontvangen. De schatting telt alle input als niet-gecachet, dus het is een bovengrens voor wat PoYo factureert. Vergelijk het tijdens de eerste paar runs met je dashboard.

De worst-casecontrole is conservatief. Met een geschiedenis van 300K tokens kost één extra beurt minstens $0.48 aan input plus tot $0.128 aan output bij een max_tokens van 16K. Bij een budget van $2.00 stopt de lus vóór de aanroep die het plafond zou kunnen overschrijden.

Wanneer je terugvalt op Gemini 4 Argon

Argon accepteert hetzelfde verzoek en kost hetzelfde per input- en output-token. Google noemt het "de ideale keuze voor het merendeel van het software-engineering- en kenniswerk", met snellere antwoorden en een lager tokenverbruik per beurt. Route ernaartoe met run_agent(task, model=ARGON) als:

  • De taak routine is. Kleine fixes, wijzigingen in één bestand en tests schrijven hebben de extra verificatietokens van Carbon niet nodig.
  • Eén antwoord langer moet zijn dan 64K tokens. Carbon beperkt de output tot 64K. Onze Argon-gids behandelt de veel hogere outputlimiet van Argon.
  • Je een goedkope eerste poging wilt. Draai eerst Argon en escaleer pas naar Carbon als de tests nog steeds falen. De router in Gemini 4 Carbon API vs. Gemini 4 Argon API doet precies dat.

Houd Carbon voor oorzaakanalyse over de hele repository en lussen met veel terminalwerk. In de tabel van Google scoort Carbon 65,2% op Terminal-Bench 4.0 (AA) tegenover 57,1% voor Argon, en 9,6% op SWE-sweep tegenover 4,3%. De beschikbaarheidspost van Google stelt ook een taakverdeling voor: Carbon voor architectuur-, coördinatie- en auditrollen, gecombineerd met snellere, lichtere modellen voor parallel werk. In deze lus betekent dat één plannerrun op Carbon die bestanden toewijst aan Argon-workers.

Budgetten voor beide modellen staan in het artikel over de prijzen van de Gemini 4 Carbon API. Weeg je voor de agent ook andere leveranciers af, zie dan Gemini 4 Carbon API vs. Claude Opus 5.5 API vs. GPT-6 Astra API.

Veelgestelde vragen

Ondersteunt de Gemini 4 Carbon API function calling op PoYo?

De huidige documentatie van PoYo beschrijft voor Gemini-modellen geen tools of function declarations in Chat Completions of Gemini Native. Tools zijn gedocumenteerd voor Anthropic Messages en Responses. Deze gids gebruikt een JSON-actieprotocol in de berichtcontent, waarvoor alleen gedocumenteerde velden nodig zijn.

Kan ik de OpenAI Python SDK gebruiken met de Gemini 4 Carbon API?

Ja. Maak OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") aan en geef model="gemini-4-carbon" mee aan chat.completions.create. Streaming werkt met stream=True, en de laatste chunk bevat usage.

Wat zijn de maximale output en het contextvenster van de Gemini 4 Carbon API?

1M tokens context en tot 64K output-tokens per antwoord. Zet max_tokens op 64.000 of lager.

Hoe beperk ik de kosten van de Gemini 4 Carbon API in een agentlus?

Beperk het aantal beurten, beperk max_tokens per beurt, kort toolresultaten in en stop zodra de uitgaven tot nu toe plus een worst-case volgende beurt je budget zouden overschrijden. Bereken de uitgaven op PoYo uit usage.prompt_tokens × $1.60 en usage.completion_tokens × $8.00 per 1M tokens.

Ondersteunt de Gemini 4 Carbon API contextcaching?

PoYo vermeldt voor Carbon een cache-read-prijs van $0.08 per 1M tokens (16 credits). De documentatie beschrijft voor Gemini-modellen momenteel geen cachingparameter in het verzoek en geen usageveld voor gecachete tokens, dus budgetteer prompts tegen het volledige inputtarief en controleer je factuur op kosten tegen het cachetarief.

Wanneer moet een coding agent Gemini 4 Argon gebruiken in plaats van Carbon?

Gebruik Argon voor routinematig codeerwerk, voor elk afzonderlijk antwoord dat langer moet zijn dan 64K tokens, en als goedkopere eerste poging voordat je naar Carbon escaleert. Beide kosten op PoYo $1.60 / $8.00 per 1M tokens, maar volgens Google gebruikt Argon minder tokens per beurt.

Share: