
La Gemini 4 Carbon API es la opción de Google para su trabajo de programación más difícil. Google la diseñó para la depuración de varios pasos y la programación agéntica de horizonte largo, y afirma que gasta más tokens que Argon para explorar, razonar y ejecutar bucles de verificación. Esta guía conecta gemini-4-carbon (página del modelo) a un agente de programación a través del endpoint compatible con OpenAI de PoYo. El agente transmite su salida en streaming, puede leer una parte grande del repositorio, se detiene al llegar a un límite estricto de turnos y de dólares, y sabe cuándo pasar el trabajo a Argon.
Si todavía no has enviado una primera solicitud, empieza por la guía de la Gemini 4 Carbon API.
Qué ofrece la API a un agente de programación
| Elemento | Gemini 4 Carbon en PoYo |
|---|---|
| ID de modelo | gemini-4-carbon |
| Endpoint del agente usado aquí | POST https://api.poyo.ai/v1/chat/completions (SDK de OpenAI, base_url="https://api.poyo.ai/v1") |
| Alternativa nativa | POST /v1beta/models/gemini-4-carbon:generateContent y :streamGenerateContent |
| Ventana de contexto | 1M tokens: texto, imagen, audio, vídeo, PDF |
| Salida máxima por respuesta | 64K tokens |
| Streaming | "stream": true; el último fragmento incluye finish_reason y usage |
| Precio | $1.60 de entrada / $8.00 de salida / $0.08 de lectura de caché por 1M de tokens (320 / 1,600 / 16 créditos) |
| Límites de tasa | La documentación de PoYo indica que los endpoints de LLM no tienen actualmente límite de tasa |
| Errores | 400 campos no válidos, 401 clave errónea, 402 créditos insuficientes, 404 modelo desconocido; reintenta 429 / 500 / 502 / 503 con backoff |
La documentación de Chat Completions describe estos campos de solicitud: model, messages (content de tipo cadena con los roles system, user o assistant), max_tokens, stream, temperature, top_p, stop, n y los campos de penalización. El agente que verás a continuación solo usa esos.
Llamadas a herramientas: qué está documentado hoy
PoYo documenta tools para Anthropic Messages y para Responses. No documenta tools ni declaraciones de funciones para los modelos Gemini, ni en Chat Completions ni en Gemini Native. Responses no está disponible para gemini-4-carbon.
Por eso, este agente no envía un array tools. En su lugar, usa un protocolo de acciones en JSON dentro del contenido normal de los mensajes. El prompt de sistema enumera las acciones permitidas, el modelo responde con un objeto JSON por turno y tu código ejecuta esa acción y devuelve el resultado como el siguiente mensaje de usuario. Funciona con cualquier modelo de chat. Cuando PoYo documente las llamadas a funciones nativas para Gemini, podrás sustituir el parser por llamadas a herramientas reales y conservar el resto del bucle.
También hay una ventaja de seguridad: el modelo solo puede solicitar cuatro acciones que has escrito tú. No puede ejecutar un comando de shell arbitrario.
Repositorio con contexto largo: 1M de entrada, 64K de salida
Una ventana de 1M de tokens te permite enviar una gran parte del repositorio en el primer turno, en lugar de ir obteniendo los archivos de uno en uno. La tabla de lanzamiento de Google da un motivo para aprovecharlo: Carbon obtiene un 96,2% en GraphWalks con 256K–1M tokens, frente al 84,2% de Argon. Tres límites condicionan el bucle:
- Cada turno reenvía todo el historial. La instantánea se vuelve a facturar en cada llamada. Una instantánea de 300K tokens a lo largo de 12 turnos supone al menos 3,6M de tokens de entrada, es decir, 5,76 $ a 1,60 $ por 1M antes de contar la salida.
- La salida está limitada a 64K por respuesta. Pide un archivo por cada acción
write_file, no una reescritura de todo el repositorio en una sola respuesta. - Mide los recuentos de tokens en lugar de adivinarlos. PoYo no documenta ningún endpoint de tokenizador. Lee
usage.prompt_tokensen la primera llamada y después ajustaMAX_SNAPSHOT_CHARSal presupuesto de tokens que quieras.
Caché. La tabla de precios de PoYo incluye una tarifa de lectura de caché para Carbon (0,08 $ por 1M, frente a 1,60 $ por entrada nueva), y Google cobra la entrada en caché con un 95% de descuento. La documentación de PoYo no describe ningún parámetro de solicitud de caché ni ningún campo de uso con tokens en caché para los modelos Gemini. Este bucle no envía ningún parámetro de caché y presupuesta todos los tokens del prompt a la tarifa de entrada completa. Mantener el prompt de sistema y la instantánea como un prefijo sin cambios no cuesta nada, y tu factura mostrará si alguna lectura se cobró a la tarifa de caché.
El bucle de agente acotado en 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 requiere Python 3.9 o posterior. Ejecuta el agente sobre una copia o una rama del repositorio, ya que write_file sobrescribe archivos.
Cómo funcionan los controles de coste
| Control | Qué evita | De dónde sale la cifra |
|---|---|---|
MAX_TURNS | Bucles que nunca llaman a done | Tu elección; 12 es un punto de partida |
BUDGET_USD + comprobación del peor caso | Superar el límite en la siguiente llamada | usage.prompt_tokens y usage.completion_tokens del último fragmento del stream, a los $1.60 / $8.00 de PoYo |
MAX_TOKENS_PER_TURN | Una respuesta desbocada | max_tokens, como máximo 64,000 para Carbon |
MAX_RESULT_CHARS | Logs de tests enormes que inflan todos los turnos posteriores | Truncado antes de que el resultado entre en el historial |
usage is None → parar | Gasto silencioso que no puedes medir | PoYo documenta usage en el último fragmento del stream |
402 sin reintento | Avalanchas de reintentos con el saldo a cero | Códigos de error de PoYo |
Google cobra la salida de Carbon incluyendo los tokens de razonamiento, así que un turno puede facturar más salida que el JSON visible. Por eso el presupuesto usa completion_tokens y nunca cuenta los caracteres recibidos. La estimación trata toda la entrada como sin caché, así que es un límite superior de lo que facturará PoYo. Compárala con tu panel en las primeras ejecuciones.
La comprobación del peor caso es conservadora. Con un historial de 300K tokens, un turno más cuesta al menos 0,48 $ de entrada más hasta 0,128 $ de salida con un max_tokens de 16K. Con un presupuesto de 2,00 $, el bucle se detiene antes de la llamada que podría superar el límite.
Cuándo recurrir a Gemini 4 Argon
Argon acepta la misma solicitud y cuesta lo mismo por token de entrada y de salida. Google lo define como «la opción ideal para la mayoría del trabajo de ingeniería de software y de conocimiento», con respuestas más rápidas y menos gasto de tokens por turno. Envíale el trabajo con run_agent(task, model=ARGON) cuando:
- La tarea es rutinaria. Las correcciones pequeñas, los cambios en un solo archivo y la escritura de tests no necesitan los tokens de verificación adicionales de Carbon.
- Una respuesta debe superar los 64K tokens. Carbon limita la salida a 64K. Nuestra guía de Argon explica el límite de salida mucho mayor de Argon.
- Quieres un primer intento barato. Ejecuta primero Argon y escala a Carbon solo cuando los tests sigan fallando. El enrutador de Gemini 4 Carbon API vs Gemini 4 Argon API hace exactamente esto.
Reserva Carbon para encontrar la causa raíz a nivel de repositorio y para los bucles con mucho trabajo en terminal. En la tabla de Google, Carbon obtiene un 65,2% en Terminal-Bench 4.0 (AA) frente al 57,1% de Argon, y un 9,6% en SWE-sweep frente al 4,3%. El artículo de disponibilidad de Google también sugiere un reparto: Carbon para funciones de arquitectura, coordinación y auditoría, combinado con modelos más rápidos y ligeros para el trabajo en paralelo. En este bucle, eso significa una ejecución planificadora con Carbon que asigna archivos a trabajadores con Argon.
Los presupuestos de ambos modelos están en el artículo de precios de la Gemini 4 Carbon API. Si estás valorando otros proveedores para el agente, consulta Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Preguntas frecuentes
¿La Gemini 4 Carbon API admite llamadas a funciones en PoYo?
La documentación actual de PoYo no describe tools ni declaraciones de funciones para los modelos Gemini en Chat Completions ni en Gemini Native. Las herramientas están documentadas para Anthropic Messages y Responses. Esta guía usa un protocolo de acciones en JSON dentro del contenido de los mensajes, que solo necesita campos documentados.
¿Puedo usar el SDK de OpenAI para Python con la Gemini 4 Carbon API?
Sí. Crea OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") y pasa model="gemini-4-carbon" a chat.completions.create. El streaming funciona con stream=True y el último fragmento incluye usage.
¿Cuál es la salida máxima y la ventana de contexto de la Gemini 4 Carbon API?
1M de tokens de contexto y hasta 64K tokens de salida por respuesta. Define max_tokens en 64.000 o menos.
¿Cómo limito los costes de la Gemini 4 Carbon API en un bucle de agente?
Limita los turnos, limita max_tokens por turno, trunca los resultados de las herramientas y detente cuando el gasto acumulado más un siguiente turno en el peor caso supere tu presupuesto. Calcula el gasto a partir de usage.prompt_tokens × 1,60 $ y usage.completion_tokens × 8,00 $ por cada millón de tokens en PoYo.
¿La Gemini 4 Carbon API admite caché de contexto?
PoYo indica un precio de lectura de caché para Carbon de 0,08 $ por 1M de tokens (16 créditos). Su documentación no describe actualmente ningún parámetro de solicitud de caché ni ningún campo de uso con tokens en caché para los modelos Gemini, así que presupuesta los prompts a la tarifa de entrada completa y revisa en tu factura si hay cargos a la tarifa de caché.
¿Cuándo debe un agente de programación usar Gemini 4 Argon en lugar de Carbon?
Usa Argon para la programación rutinaria, para cualquier respuesta individual que deba superar los 64K tokens y como primer intento más barato antes de escalar a Carbon. Ambos cuestan 1,60 $ / 8,00 $ por cada millón de tokens en PoYo, pero según Google, Argon usa menos tokens por turno.