how-tos

Gemini 4 Carbon API para agentes de programação: um ciclo de agente limitado com streaming e proteções de custo

Poyo.ai Team
12 min read
Share:

A Gemini 4 Carbon API a alimentar o ciclo de um agente de programação

A Gemini 4 Carbon API é a escolha da Google para o seu trabalho de programação mais difícil. A Google construiu-a para depuração com vários passos e programação agêntica de horizonte longo, e diz que gasta mais tokens do que o Argon para explorar, raciocinar e executar ciclos de verificação. Este guia liga o gemini-4-carbon (página do modelo) a um agente de programação através do endpoint compatível com a OpenAI do PoYo. O agente faz streaming do output, consegue ler uma grande fatia do repositório, pára num limite rígido de turnos e de dólares e sabe quando passar o trabalho ao Argon.

Se ainda não enviaste um primeiro pedido, começa pelo guia da Gemini 4 Carbon API.

O que a API oferece a um agente de programação

ItemGemini 4 Carbon no PoYo
ID do modelogemini-4-carbon
Endpoint do agente usado aquiPOST https://api.poyo.ai/v1/chat/completions (SDK da OpenAI, base_url="https://api.poyo.ai/v1")
Alternativa nativaPOST /v1beta/models/gemini-4-carbon:generateContent e :streamGenerateContent
Janela de contexto1M tokens: texto, imagem, áudio, vídeo, PDF
Saída máxima por resposta64K tokens
Streaming"stream": true; o último chunk traz finish_reason e usage
Preço$1.60 de entrada / $8.00 de saída / $0.08 de leitura de cache por 1M de tokens (320 / 1,600 / 16 créditos)
Limites de taxaA documentação do PoYo indica que os endpoints de LLM não têm atualmente limite de taxa
Erros400 campos inválidos, 401 chave inválida, 402 créditos insuficientes, 404 modelo desconhecido; repete 429 / 500 / 502 / 503 com backoff

A documentação do Chat Completions documenta estes campos de pedido: model, messages (content em string com os papéis system, user ou assistant), max_tokens, stream, temperature, top_p, stop, n e os campos de penalização. O agente abaixo usa apenas esses.

Tool calling: o que está documentado hoje

O PoYo documenta tools para o Anthropic Messages e para o Responses. Não documenta tools nem declarações de funções para os modelos Gemini, nem no Chat Completions nem no Gemini Native. O Responses não está disponível para o gemini-4-carbon.

Por isso, este agente não envia um array tools. Em vez disso, usa um protocolo de ações em JSON no conteúdo simples das mensagens. O prompt de sistema lista as ações permitidas, o modelo responde com um objeto JSON por turno, e o teu código executa essa ação e devolve o resultado como a mensagem de utilizador seguinte. Isto funciona com qualquer modelo de chat. Quando o PoYo documentar function calling nativo para o Gemini, podes trocar o parser por tool calls reais e manter o resto do ciclo.

Há também uma vantagem de segurança: o modelo só pode pedir quatro ações que tu próprio escreveste. Não consegue executar um comando de shell arbitrário.

Repositório em contexto longo: 1M de entrada, 64K de saída

Uma janela de 1M de tokens permite-te enviar uma grande parte do repositório no primeiro turno, em vez de ires buscar os ficheiros um a um. A tabela de lançamento da Google dá uma razão para o fazer: o Carbon obtém 96,2% no GraphWalks entre 256K e 1M tokens, contra 84,2% do Argon. Há três limites que moldam o ciclo:

  • Cada turno reenvia todo o histórico. O snapshot é faturado outra vez em cada chamada. Um snapshot de 300K tokens ao longo de 12 turnos dá pelo menos 3,6M tokens de entrada, ou seja, $5.76 a $1.60 por 1M antes de qualquer saída.
  • A saída está limitada a 64K por resposta. Pede um ficheiro por ação write_file, e não uma reescrita de todo o repositório numa única resposta.
  • Mede as contagens de tokens, não as adivinhes. O PoYo não documenta nenhum endpoint de tokenizer. Lê usage.prompt_tokens da primeira chamada e depois ajusta MAX_SNAPSHOT_CHARS ao orçamento de tokens que queres.

Caching. A tabela de preços do PoYo tem uma tarifa de leitura de cache para o Carbon ($0.08 por 1M, contra $1.60 para entrada nova), e a Google cobra a entrada em cache com 95% de desconto. A documentação do PoYo não documenta nenhum parâmetro de pedido para caching nem nenhum campo de uso com tokens em cache para os modelos Gemini. Este ciclo não envia nenhum parâmetro de caching e orçamenta todos os tokens do prompt à tarifa de entrada completa. Manter o prompt de sistema e o snapshot como um prefixo inalterado não custa nada, e a tua fatura mostrará se alguma leitura foi cobrada à tarifa de cache.

O ciclo de agente limitado em 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 requer Python 3.9 ou posterior. Corre o agente sobre uma cópia ou um branch do repositório, já que write_file substitui ficheiros.

Como funcionam as proteções de custo

ProteçãoO que impedeDe onde vem o número
MAX_TURNSCiclos que nunca chamam doneEscolha tua; 12 é um ponto de partida
BUDGET_USD + verificação do pior casoGastar acima do limite na chamada seguinteusage.prompt_tokens e usage.completion_tokens do último chunk do stream, aos $1.60 / $8.00 do PoYo
MAX_TOKENS_PER_TURNUma resposta descontroladamax_tokens, no máximo 64,000 para o Carbon
MAX_RESULT_CHARSLogs de testes enormes a inflacionar todos os turnos seguintesTruncagem antes de o resultado entrar no histórico
usage is None → pararGastos silenciosos que não consegues medirO PoYo documenta usage no último chunk do stream
402 sem repetiçãoTempestades de repetições com o saldo a zeroCódigos de erro do PoYo

A Google cobra a saída do Carbon incluindo os tokens de thinking, por isso um turno pode faturar mais saída do que o JSON visível. É por isso que o orçamento usa completion_tokens e nunca conta os carateres que recebeste. A estimativa conta toda a entrada como sem cache, por isso é um limite superior do que o PoYo vai faturar. Compara-a com o teu painel nas primeiras execuções.

A verificação do pior caso é conservadora. Com um histórico de 300K tokens, mais um turno custa pelo menos $0.48 de entrada mais até $0.128 de saída com max_tokens de 16K. Com um orçamento de $2.00, o ciclo pára antes da chamada que poderia ultrapassar o limite.

Quando recorrer ao Gemini 4 Argon

O Argon recebe o mesmo pedido e custa o mesmo por token de entrada e de saída. A Google chama-lhe "a escolha ideal para a maioria do trabalho de engenharia de software e de conhecimento", com respostas mais rápidas e menor gasto de tokens por turno. Encaminha para ele com run_agent(task, model=ARGON) quando:

  • A tarefa é rotineira. Pequenas correções, alterações num único ficheiro e escrita de testes não precisam dos tokens de verificação extra do Carbon.
  • Uma resposta tem de ultrapassar os 64K tokens. O Carbon limita a saída a 64K. O nosso guia do Argon cobre o limite de saída muito maior do Argon.
  • Queres uma primeira tentativa barata. Corre primeiro o Argon e escala para o Carbon apenas quando os testes continuarem a falhar. O router em Gemini 4 Carbon API vs Gemini 4 Argon API faz isto.

Reserva o Carbon para encontrar a causa raiz em todo o repositório e para ciclos com muito trabalho no terminal. Na tabela da Google, o Carbon obtém 65,2% no Terminal-Bench 4.0 (AA) contra 57,1% do Argon, e 9,6% no SWE-sweep contra 4,3%. O artigo da Google sobre a disponibilidade sugere também uma divisão: o Carbon para funções de arquitetura, coordenação e auditoria, combinado com modelos mais rápidos e leves para o trabalho em paralelo. Neste ciclo, isso significa uma execução de planeamento com o Carbon que atribui ficheiros a workers com o Argon.

Os orçamentos para ambos os modelos estão no artigo sobre os preços da Gemini 4 Carbon API. Se estiveres a ponderar outros fornecedores para o agente, vê Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.

Perguntas frequentes

A Gemini 4 Carbon API suporta function calling no PoYo?

A documentação atual do PoYo não documenta tools nem declarações de funções para os modelos Gemini no Chat Completions nem no Gemini Native. As ferramentas estão documentadas para o Anthropic Messages e o Responses. Este guia usa um protocolo de ações em JSON no conteúdo das mensagens, que só precisa de campos documentados.

Posso usar o SDK Python da OpenAI com a Gemini 4 Carbon API?

Sim. Cria OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") e passa model="gemini-4-carbon" a chat.completions.create. O streaming funciona com stream=True, e o último chunk traz usage.

Qual é a saída máxima e a janela de contexto da Gemini 4 Carbon API?

1M de tokens de contexto e até 64K tokens de saída por resposta. Define max_tokens como 64 000 ou menos.

Como limito os custos da Gemini 4 Carbon API num ciclo de agente?

Limita os turnos, limita max_tokens por turno, trunca os resultados das ferramentas e pára quando o gasto acumulado mais o pior caso do turno seguinte ultrapassariam o teu orçamento. Calcula o gasto a partir de usage.prompt_tokens × $1.60 e usage.completion_tokens × $8.00 por 1M de tokens no PoYo.

A Gemini 4 Carbon API suporta caching de contexto?

O PoYo indica para o Carbon um preço de leitura de cache de $0.08 por 1M de tokens (16 créditos). A sua documentação não documenta atualmente nenhum parâmetro de pedido para caching nem nenhum campo de uso com tokens em cache para os modelos Gemini, por isso orçamenta os prompts à tarifa de entrada completa e verifica na tua fatura se há cobranças à tarifa de cache.

Quando deve um agente de programação usar o Gemini 4 Argon em vez do Carbon?

Usa o Argon para programação rotineira, para qualquer resposta individual que tenha de ultrapassar os 64K tokens e como primeira tentativa mais barata antes de escalares para o Carbon. Ambos custam $1.60 / $8.00 por 1M de tokens no PoYo, mas a Google diz que o Argon usa menos tokens por turno.

Share: