how-tos

Gemini 4 Carbon API per agenti di coding: un loop di agente limitato con streaming e controlli di costo

Poyo.ai Team
11 min read
Share:

Gemini 4 Carbon API alla base di un loop di agente di coding

La Gemini 4 Carbon API è la scelta di Google per il lavoro di coding più difficile. Google l'ha costruita per il debugging a più passaggi e il coding agentico su orizzonti lunghi, e afferma che spende più token di Argon per esplorare, ragionare ed eseguire cicli di verifica. Questa guida collega gemini-4-carbon (pagina del modello) a un agente di coding tramite l'endpoint compatibile con OpenAI di PoYo. L'agente trasmette il suo output in streaming, può leggere una porzione ampia del repository, si ferma a un limite rigido di turni e di dollari, e sa quando passare il lavoro ad Argon.

Se non hai ancora inviato una prima richiesta, parti dalla guida alla Gemini 4 Carbon API.

Cosa offre l'API a un agente di coding

VoceGemini 4 Carbon su PoYo
ID modellogemini-4-carbon
Endpoint per l'agente usato quiPOST https://api.poyo.ai/v1/chat/completions (SDK OpenAI, base_url="https://api.poyo.ai/v1")
Alternativa nativaPOST /v1beta/models/gemini-4-carbon:generateContent e :streamGenerateContent
Finestra di contesto1M token: testo, immagine, audio, video, PDF
Output massimo per risposta64K token
Streaming"stream": true; l'ultimo chunk contiene finish_reason e usage
Prezzo$1.60 di input / $8.00 di output / $0.08 di lettura dalla cache per 1M di token (320 / 1,600 / 16 crediti)
Limiti di frequenzaLa documentazione di PoYo indica che al momento gli endpoint LLM non hanno limiti di frequenza
Errori400 campi non validi, 401 chiave errata, 402 crediti insufficienti, 404 modello sconosciuto; riprova 429 / 500 / 502 / 503 con backoff

La documentazione di Chat Completions documenta questi campi di richiesta: model, messages (content come stringa con ruoli system, user o assistant), max_tokens, stream, temperature, top_p, stop, n e i campi di penalità. L'agente qui sotto usa solo questi.

Tool calling: cosa è documentato oggi

PoYo documenta tools per Anthropic Messages e per Responses. Non documenta tools né dichiarazioni di funzioni per i modelli Gemini, né in Chat Completions né in Gemini Native. Responses non è disponibile per gemini-4-carbon.

Per questo l'agente non invia un array tools. Usa invece un protocollo di azioni JSON nel contenuto testuale dei messaggi. Il system prompt elenca le azioni consentite, il modello risponde con un oggetto JSON per turno e il tuo codice esegue quell'azione e rimanda il risultato come messaggio utente successivo. Funziona con qualsiasi modello di chat. Quando PoYo documenterà il function calling nativo per Gemini, potrai sostituire il parser con vere chiamate a strumenti e mantenere il resto del loop.

C'è anche un vantaggio di sicurezza: il modello può richiedere solo quattro azioni che hai scritto tu. Non può eseguire un comando di shell arbitrario.

Input del repository con contesto lungo: 1M in ingresso, 64K in uscita

Una finestra da 1M token ti permette di inviare una parte ampia del repository al primo turno invece di recuperare i file uno alla volta. La tabella di lancio di Google offre un motivo per farlo: Carbon ottiene il 96,2% su GraphWalks a 256K–1M token, contro l'84,2% di Argon. Tre limiti condizionano il loop:

  • Ogni turno reinvia l'intera cronologia. Lo snapshot viene fatturato di nuovo a ogni chiamata. Uno snapshot da 300K token su 12 turni fa almeno 3,6M token di input, cioè $5.76 a $1.60 per 1M prima di qualsiasi output.
  • L'output è limitato a 64K per risposta. Chiedi un file per ogni azione write_file, non la riscrittura dell'intero repository in una sola risposta.
  • Misura i conteggi di token, non indovinarli. PoYo non documenta un endpoint di tokenizzazione. Leggi usage.prompt_tokens dalla prima chiamata, poi regola MAX_SNAPSHOT_CHARS sul budget di token che vuoi.

Caching. La tabella prezzi di PoYo prevede per Carbon una tariffa di lettura dalla cache ($0.08 per 1M, contro $1.60 per l'input nuovo), e Google applica all'input in cache uno sconto del 95%. La documentazione di PoYo non descrive un parametro di richiesta per il caching né un campo di usage per i token in cache per i modelli Gemini. Questo loop non invia alcun parametro di caching e mette a budget ogni token del prompt alla tariffa di input piena. Mantenere il system prompt e lo snapshot come prefisso invariato non costa nulla, e la tua fattura mostrerà se qualche lettura è stata addebitata alla tariffa della cache.

Il loop di agente limitato 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 richiede Python 3.9 o successivo. Esegui l'agente su una copia o su un branch del repository, perché write_file sovrascrive i file.

Come funzionano i controlli di costo

ControlloCosa impedisceDa dove viene il numero
MAX_TURNSLoop che non chiamano mai doneUna tua scelta; 12 è un punto di partenza
BUDGET_USD + controllo del caso peggioreSuperare il limite di spesa alla chiamata successivausage.prompt_tokens e usage.completion_tokens dall'ultimo chunk dello stream, ai $1.60 / $8.00 di PoYo
MAX_TOKENS_PER_TURNUna singola risposta fuori controllomax_tokens, al massimo 64,000 per Carbon
MAX_RESULT_CHARSLog di test enormi che gonfiano ogni turno successivoTroncamento prima che il risultato entri nella cronologia
usage is None → stopSpesa silenziosa che non puoi misurarePoYo documenta usage nell'ultimo chunk dello stream
402 non ritentatoRaffiche di tentativi con saldo esauritoCodici di errore di PoYo

Google fattura l'output di Carbon includendo i token di thinking, quindi un turno può addebitare più output del JSON visibile. Per questo il budget usa completion_tokens e non conta mai i caratteri ricevuti. La stima conta tutto l'input come non in cache, quindi è un limite superiore di ciò che PoYo addebiterà. Confrontala con la tua dashboard per le prime esecuzioni.

Il controllo del caso peggiore è prudente. Con una cronologia da 300K token, un turno in più costa almeno $0.48 di input più fino a $0.128 di output con un max_tokens di 16K. Con un budget di $2.00, il loop si ferma prima della chiamata che potrebbe superare il limite.

Quando ripiegare su Gemini 4 Argon

Argon accetta la stessa richiesta e costa uguale per token di input e di output. Google lo definisce "la scelta ideale per la maggior parte dell'ingegneria del software e del lavoro di conoscenza", con risposte più rapide e meno token spesi per turno. Instradalo con run_agent(task, model=ARGON) quando:

  • Il task è di routine. Piccole correzioni, modifiche a un solo file e scrittura di test non hanno bisogno dei token di verifica extra di Carbon.
  • Una risposta deve superare i 64K token. Carbon limita l'output a 64K. La nostra guida ad Argon illustra il limite di output molto più ampio di Argon.
  • Vuoi un primo tentativo economico. Esegui prima Argon e fai escalation a Carbon solo se i test continuano a fallire. Il router in Gemini 4 Carbon API vs Gemini 4 Argon API fa proprio questo.

Tieni Carbon per l'individuazione della causa radice su tutto il repository e per i loop con uso intensivo del terminale. Nella tabella di Google, Carbon ottiene il 65,2% su Terminal-Bench 4.0 (AA) contro il 57,1% di Argon, e il 9,6% su SWE-sweep contro il 4,3%. Il post di Google sulla disponibilità suggerisce anche una suddivisione: Carbon per i ruoli di architettura, coordinamento e audit, affiancato da modelli più veloci e leggeri per il lavoro in parallelo. In questo loop significa un'esecuzione di Carbon come pianificatore che assegna i file a worker Argon.

I budget per entrambi i modelli sono nell'articolo sui prezzi della Gemini 4 Carbon API. Se stai valutando altri fornitori per l'agente, vedi Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.

Domande frequenti

La Gemini 4 Carbon API supporta il function calling su PoYo?

La documentazione attuale di PoYo non descrive tools né dichiarazioni di funzioni per i modelli Gemini in Chat Completions o Gemini Native. Gli strumenti sono documentati per Anthropic Messages e Responses. Questa guida usa un protocollo di azioni JSON nel contenuto dei messaggi, che richiede solo campi documentati.

Posso usare l'SDK OpenAI per Python con la Gemini 4 Carbon API?

Sì. Crea OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") e passa model="gemini-4-carbon" a chat.completions.create. Lo streaming funziona con stream=True e l'ultimo chunk contiene usage.

Qual è l'output massimo e la finestra di contesto della Gemini 4 Carbon API?

1M token di contesto e fino a 64K token di output per risposta. Imposta max_tokens a 64.000 o meno.

Come limito i costi della Gemini 4 Carbon API in un loop di agente?

Limita i turni, limita max_tokens per turno, tronca i risultati degli strumenti e fermati quando la spesa accumulata più un turno successivo nel caso peggiore supererebbe il budget. Calcola la spesa da usage.prompt_tokens × $1.60 e usage.completion_tokens × $8.00 per 1M di token su PoYo.

La Gemini 4 Carbon API supporta il caching del contesto?

PoYo indica per Carbon un prezzo di lettura dalla cache di $0.08 per 1M di token (16 crediti). La sua documentazione al momento non descrive un parametro di richiesta per il caching né un campo di usage per i token in cache per i modelli Gemini, quindi metti a budget i prompt alla tariffa di input piena e controlla in fattura gli addebiti alla tariffa della cache.

Quando un agente di coding dovrebbe usare Gemini 4 Argon invece di Carbon?

Usa Argon per il coding di routine, per qualsiasi singola risposta che deve superare i 64K token e come primo tentativo più economico prima dell'escalation a Carbon. Entrambi costano $1.60 / $8.00 per 1M di token su PoYo, ma secondo Google Argon usa meno token per turno.

Share: