how-tos

Gemini 4 Carbon API for kodeagenter: en avgrenset agentløkke med strømming og kostnadsvern

Poyo.ai Team
10 min read
Share:

Gemini 4 Carbon API driver en agentløkke for koding

Gemini 4 Carbon API er Googles valg for det vanskeligste kodearbeidet. Google bygde den for feilsøking i mange trinn og agentisk koding over lange forløp, og sier at den bruker flere tokens enn Argon på å utforske, resonnere og kjøre verifiseringsløkker. Denne guiden kobler gemini-4-carbon (modellside) inn i en kodeagent via PoYos OpenAI-kompatible endepunkt. Agenten strømmer outputen sin, kan lese en stor del av repositoriet, stopper ved et fast tak på runder og dollar, og vet når arbeidet bør overlates til Argon.

Hvis du ikke har sendt en første forespørsel ennå, begynn med Gemini 4 Carbon API-guiden.

Hva API-et gir en kodeagent

PunktGemini 4 Carbon på PoYo
Modell-IDgemini-4-carbon
Agentendepunkt brukt herPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Native alternativPOST /v1beta/models/gemini-4-carbon:generateContent og :streamGenerateContent
Kontekstvindu1M tokens: tekst, bilde, lyd, video, PDF
Maks. output per svar64K tokens
Strømming"stream": true; den siste chunken inneholder finish_reason og usage
Pris$1.60 input / $8.00 output / $0.08 cache-lesing per 1M tokens (320 / 1,600 / 16 kreditter)
Rate limitsPoYos dokumentasjon sier at LLM-endepunkter for øyeblikket ikke har rate limiting
Feil400 ugyldige felt, 401 ugyldig nøkkel, 402 ikke nok kreditter, 404 ukjent modell; prøv 429 / 500 / 502 / 503 igjen med backoff

Chat Completions-dokumentasjonen dokumenterer disse forespørselsfeltene: model, messages (streng-content med rollene system, user eller assistant), max_tokens, stream, temperature, top_p, stop, n og penalty-feltene. Agenten nedenfor bruker bare disse.

Tool calling: hva som er dokumentert i dag

PoYo dokumenterer tools for Anthropic Messages og for Responses. Det dokumenterer ikke tools eller funksjonsdeklarasjoner for Gemini-modeller, verken i Chat Completions eller Gemini Native. Responses er ikke tilgjengelig for gemini-4-carbon.

Derfor sender ikke denne agenten en tools-array. Den bruker i stedet en JSON-handlingsprotokoll i vanlig meldingsinnhold. Systemprompten lister opp de tillatte handlingene, modellen svarer med ett JSON-objekt per runde, og koden din utfører handlingen og sender resultatet tilbake som neste brukermelding. Dette fungerer med alle chatmodeller. Når PoYo dokumenterer native function calling for Gemini, kan du bytte ut parseren med ekte tool calls og beholde resten av løkken.

Det gir også en sikkerhetsfordel: modellen kan bare be om fire handlinger som du har skrevet selv. Den kan ikke kjøre en vilkårlig shell-kommando.

Repo-input med lang kontekst: 1M inn, 64K ut

Et vindu på 1M tokens lar deg sende en stor del av repositoriet i første runde i stedet for å hente filer én om gangen. Googles lanseringstabell gir en grunn til å bruke det: Carbon oppnår 96,2 % på GraphWalks ved 256K–1M tokens, mot 84,2 % for Argon. Tre grenser former løkken:

  • Hver runde sender hele historikken på nytt. Snapshotet faktureres igjen ved hvert kall. Et snapshot på 300K tokens over 12 runder er minst 3,6M input-tokens, som er $5.76 ved $1.60 per 1M før noe output.
  • Output er begrenset til 64K per svar. Be om én fil per write_file-handling, ikke en omskriving av hele repositoriet i ett svar.
  • Mål tokenantallet i stedet for å gjette. PoYo dokumenterer ikke noe tokenizer-endepunkt. Les usage.prompt_tokens fra det første kallet, og juster deretter MAX_SNAPSHOT_CHARS til tokenbudsjettet du ønsker.

Caching. PoYos pristabell har en sats for cache-lesing for Carbon ($0.08 per 1M, mot $1.60 for nytt input), og Google priser cachet input med 95 % rabatt. PoYos dokumentasjon beskriver ingen forespørselsparameter for caching eller noe usage-felt for cachede tokens for Gemini-modeller. Denne løkken sender ingen cachingparameter og budsjetterer hver prompt-token til full inputsats. Det koster ingenting å holde systemprompten og snapshotet som et uendret prefiks, og regningen din vil vise om noen lesinger ble fakturert til cachesatsen.

Den avgrensede agentløkken i 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 krever Python 3.9 eller nyere. Kjør agenten mot en kopi eller en branch av repositoriet, siden write_file overskriver filer.

Slik fungerer kostnadsvernene

VernHva det stopperHvor tallet kommer fra
MAX_TURNSLøkker som aldri kaller doneDitt valg; 12 er et utgangspunkt
BUDGET_USD + worst case-sjekkForbruk over taket ved neste kallusage.prompt_tokens og usage.completion_tokens fra den siste strømmechunken, til PoYos $1.60 / $8.00
MAX_TOKENS_PER_TURNEtt løpsk svarmax_tokens, maks. 64,000 for Carbon
MAX_RESULT_CHARSStore testlogger som blåser opp alle senere runderAvkorting før resultatet går inn i historikken
usage is None → stoppSkjult forbruk du ikke kan målePoYo dokumenterer usage på den siste strømmechunken
402 prøves ikke igjenStorm av nye forsøk på en tom saldoPoYos feilkoder

Google priser Carbons output inkludert thinking-tokens, så en runde kan fakturere mer output enn den synlige JSON-en. Derfor bruker budsjettet completion_tokens og teller aldri tegnene du mottok. Estimatet regner alt input som ikke-cachet, så det er en øvre grense for hva PoYo vil fakturere. Sammenhold det med dashbordet ditt for de første kjøringene.

Worst case-sjekken er konservativ. Med en historikk på 300K tokens koster én runde til minst $0.48 i input pluss opptil $0.128 i output ved max_tokens på 16K. Med et budsjett på $2.00 stopper løkken før kallet som kunne gått over taket.

Når du bør falle tilbake til Gemini 4 Argon

Argon tar samme forespørsel og koster det samme per input- og output-token. Google kaller den "det ideelle valget for det meste av programvareutvikling og kunnskapsarbeid", med raskere svar og lavere tokenforbruk per runde. Rut til den med run_agent(task, model=ARGON) når:

  • Oppgaven er rutine. Små rettelser, endringer i én fil og testskriving trenger ikke Carbons ekstra verifiseringstokens.
  • Ett svar må være lengre enn 64K tokens. Carbon begrenser output til 64K. Vår Argon-guide beskriver Argons mye større outputgrense.
  • Du vil ha et billig første forsøk. Kjør Argon først, og eskaler til Carbon bare når testene fortsatt feiler. Ruteren i Gemini 4 Carbon API vs Gemini 4 Argon API gjør akkurat dette.

Behold Carbon for rotårsaksanalyse på tvers av hele repositoriet og terminaltunge løkker. I Googles tabell oppnår Carbon 65,2 % på Terminal-Bench 4.0 (AA) mot Argons 57,1 %, og 9,6 % på SWE-sweep mot 4,3 %. Googles innlegg om tilgjengelighet foreslår også en arbeidsdeling: Carbon for roller innen arkitektur, koordinering og revisjon, kombinert med raskere, lettere modeller for parallelt arbeid. I denne løkken betyr det én Carbon-planleggingskjøring som fordeler filer til Argon-workers.

Budsjetter for begge modellene finner du i innlegget om Gemini 4 Carbon API-priser. Hvis du vurderer andre leverandører for agenten, se Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.

Ofte stilte spørsmål

Støtter Gemini 4 Carbon API function calling på PoYo?

PoYos gjeldende dokumentasjon beskriver ikke tools eller funksjonsdeklarasjoner for Gemini-modeller i Chat Completions eller Gemini Native. Tools er dokumentert for Anthropic Messages og Responses. Denne guiden bruker en JSON-handlingsprotokoll i meldingsinnholdet, som bare krever dokumenterte felt.

Kan jeg bruke OpenAI Python SDK med Gemini 4 Carbon API?

Ja. Opprett OpenAI(api_key=..., base_url="https://api.poyo.ai/v1"), og send model="gemini-4-carbon" til chat.completions.create. Strømming fungerer med stream=True, og den siste chunken inneholder usage.

Hva er maks. output og kontekstvindu for Gemini 4 Carbon API?

1M tokens kontekst og opptil 64K output-tokens per svar. Sett max_tokens til 64 000 eller mindre.

Hvordan begrenser jeg kostnadene for Gemini 4 Carbon API i en agentløkke?

Sett tak på antall runder, sett tak på max_tokens per runde, avkort verktøyresultater, og stopp når forbruket så langt pluss en worst case-runde ville gått over budsjettet. Beregn forbruket fra usage.prompt_tokens × $1.60 og usage.completion_tokens × $8.00 per 1M tokens på PoYo.

Støtter Gemini 4 Carbon API kontekstcaching?

PoYo oppgir en pris for cache-lesing for Carbon på $0.08 per 1M tokens (16 kreditter). Dokumentasjonen beskriver for øyeblikket ingen forespørselsparameter for caching eller noe usage-felt for cachede tokens for Gemini-modeller, så budsjetter prompter til full inputsats og sjekk regningen for belastninger til cachesatsen.

Når bør en kodeagent bruke Gemini 4 Argon i stedet for Carbon?

Bruk Argon til rutinekoding, til alle enkeltsvar som må være lengre enn 64K tokens, og som et billigere første forsøk før du eskalerer til Carbon. Begge koster $1.60 / $8.00 per 1M tokens på PoYo, men Google sier at Argon bruker færre tokens per runde.

Share: