
Gemini 4 Carbon API to wybór Google do najtrudniejszej pracy programistycznej. Google zbudowało ten model do wieloetapowego debugowania i agentowego programowania o długim horyzoncie i twierdzi, że zużywa on więcej tokenów niż Argon na eksplorację, rozumowanie i pętle weryfikacji. Ten przewodnik podłącza gemini-4-carbon (strona modelu) do agenta programistycznego przez zgodny z OpenAI endpoint PoYo. Agent streamuje wyjście, może odczytać duży fragment repozytorium, zatrzymuje się po twardym limicie tur i budżetu w dolarach i wie, kiedy przekazać pracę do Argon.
Jeśli nie wysłałeś jeszcze pierwszego żądania, zacznij od przewodnika po Gemini 4 Carbon API.
Co API daje agentowi programistycznemu
| Element | Gemini 4 Carbon w PoYo |
|---|---|
| ID modelu | gemini-4-carbon |
| Endpoint agenta użyty tutaj | POST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1") |
| Natywna alternatywa | POST /v1beta/models/gemini-4-carbon:generateContent i :streamGenerateContent |
| Okno kontekstu | 1M tokenów: tekst, obraz, audio, wideo, PDF |
| Maks. wyjście na odpowiedź | 64K tokenów |
| Streaming | "stream": true; ostatni chunk zawiera finish_reason i usage |
| Cena | $1.60 za wejście / $8.00 za wyjście / $0.08 za odczyt z cache za 1M tokenów (320 / 1,600 / 16 kredytów) |
| Limity częstotliwości | Dokumentacja PoYo mówi, że endpointy LLM obecnie nie mają limitów częstotliwości |
| Błędy | 400 nieprawidłowe pola, 401 zły klucz, 402 za mało kredytów, 404 nieznany model; 429 / 500 / 502 / 503 ponawiaj z backoffem |
Dokumentacja Chat Completions opisuje następujące pola żądania: model, messages (content jako ciąg znaków z rolami system, user lub assistant), max_tokens, stream, temperature, top_p, stop, n oraz pola kar. Poniższy agent używa wyłącznie ich.
Wywoływanie narzędzi: co jest dziś udokumentowane
PoYo dokumentuje tools dla Anthropic Messages i dla Responses. Nie dokumentuje tools ani deklaracji funkcji dla modeli Gemini, ani w Chat Completions, ani w Gemini Native. Responses nie jest dostępne dla gemini-4-carbon.
Dlatego ten agent nie wysyła tablicy tools. Zamiast tego używa protokołu akcji JSON w zwykłej treści wiadomości. Prompt systemowy wymienia dozwolone akcje, model odpowiada jednym obiektem JSON na turę, a Twój kod wykonuje tę akcję i odsyła wynik jako kolejną wiadomość użytkownika. Działa to z każdym modelem czatowym. Gdy PoYo udokumentuje natywne wywoływanie funkcji dla Gemini, możesz zamienić parser na prawdziwe wywołania narzędzi i zachować resztę pętli.
Jest też korzyść dla bezpieczeństwa: model może zażądać tylko czterech akcji, które sam napisałeś. Nie może uruchomić dowolnego polecenia powłoki.
Repozytorium w długim kontekście: 1M na wejściu, 64K na wyjściu
Okno 1M tokenów pozwala wysłać dużą część repozytorium już w pierwszej turze, zamiast pobierać pliki pojedynczo. Tabela premierowa Google daje powód, by z tego korzystać: Carbon uzyskuje 96.2% w GraphWalks przy 256K–1M tokenów, wobec 84.2% dla Argon. Pętlę kształtują trzy ograniczenia:
- Każda tura wysyła ponownie całą historię. Snapshot jest rozliczany przy każdym wywołaniu od nowa. Snapshot 300K tokenów przez 12 tur to co najmniej 3.6M tokenów wejściowych, czyli $5.76 przy $1.60 za 1M, jeszcze przed jakimkolwiek wyjściem.
- Wyjście jest ograniczone do 64K na odpowiedź. Proś o jeden plik na akcję
write_file, a nie o przepisanie całego repozytorium w jednej odpowiedzi. - Mierz liczbę tokenów, zamiast zgadywać. PoYo nie dokumentuje endpointu tokenizera. Odczytaj
usage.prompt_tokensz pierwszego wywołania, a potem dostosujMAX_SNAPSHOT_CHARSdo pożądanego budżetu tokenów.
Cache'owanie. Tabela cen PoYo zawiera stawkę odczytu z cache dla Carbon ($0.08 za 1M wobec $1.60 za nowe wejście), a Google wycenia wejście z cache 95% taniej. Dokumentacja PoYo nie opisuje parametru żądania do cache'owania ani pola usage z tokenami z cache dla modeli Gemini. Ta pętla nie wysyła żadnego parametru cache'owania i budżetuje każdy token promptu po pełnej stawce za wejście. Utrzymywanie promptu systemowego i snapshotu jako niezmiennego prefiksu nic nie kosztuje, a rachunek pokaże, czy jakiekolwiek odczyty zostały rozliczone według stawki cache.
Ograniczona pętla agenta w Pythonie
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 wymaga Pythona 3.9 lub nowszego. Uruchamiaj agenta na kopii lub gałęzi repozytorium, bo write_file nadpisuje pliki.
Jak działają zabezpieczenia kosztów
| Zabezpieczenie | Co zatrzymuje | Skąd bierze się liczba |
|---|---|---|
MAX_TURNS | Pętle, które nigdy nie wywołują done | Twój wybór; 12 to punkt wyjścia |
BUDGET_USD + kontrola najgorszego przypadku | Przekroczenie limitu przy następnym wywołaniu | usage.prompt_tokens i usage.completion_tokens z ostatniego chunka strumienia, według stawek PoYo $1.60 / $8.00 |
MAX_TOKENS_PER_TURN | Pojedynczą niekontrolowaną odpowiedź | max_tokens, dla Carbon najwyżej 64,000 |
MAX_RESULT_CHARS | Ogromne logi testów rozdmuchujące każdą kolejną turę | Obcięcie, zanim wynik trafi do historii |
usage is None → stop | Ciche wydatki, których nie da się zmierzyć | PoYo dokumentuje usage w ostatnim chunku strumienia |
402 nie jest ponawiany | Lawinę ponowień przy pustym saldzie | Kody błędów PoYo |
Google wycenia wyjście Carbon razem z tokenami myślenia, więc tura może rozliczyć więcej wyjścia, niż widać w JSON. Dlatego budżet używa completion_tokens i nigdy nie liczy otrzymanych znaków. Szacunek liczy całe wejście jako niecache'owane, więc jest górną granicą tego, co rozliczy PoYo. Porównaj go z panelem przy pierwszych kilku uruchomieniach.
Kontrola najgorszego przypadku jest zachowawcza. Przy historii 300K tokenów jeszcze jedna tura kosztuje co najmniej $0.48 za wejście plus do $0.128 za wyjście przy max_tokens 16K. Przy budżecie $2.00 pętla zatrzymuje się przed wywołaniem, które mogłoby przekroczyć limit.
Kiedy przejść na Gemini 4 Argon
Argon przyjmuje to samo żądanie i kosztuje tyle samo za token wejściowy i wyjściowy. Google nazywa go „idealnym wyborem dla większości prac z zakresu inżynierii oprogramowania i pracy z wiedzą”, z szybszymi odpowiedziami i mniejszym zużyciem tokenów na turę. Kieruj do niego pracę przez run_agent(task, model=ARGON), gdy:
- Zadanie jest rutynowe. Drobne poprawki, zmiany w jednym pliku i pisanie testów nie potrzebują dodatkowych tokenów weryfikacji Carbon.
- Pojedyncza odpowiedź musi przekroczyć 64K tokenów. Carbon ogranicza wyjście do 64K. Znacznie większy limit wyjścia Argon opisuje nasz przewodnik po Argon.
- Chcesz taniej pierwszej próby. Uruchom najpierw Argon i eskaluj do Carbon tylko wtedy, gdy testy nadal nie przechodzą. Tak działa router z artykułu Gemini 4 Carbon API vs Gemini 4 Argon API.
Zostaw Carbon do znajdowania przyczyn na poziomie całego repozytorium i pętli intensywnie korzystających z terminala. W tabeli Google Carbon uzyskuje 65.2% w Terminal-Bench 4.0 (AA) wobec 57.1% dla Argon i 9.6% w SWE-sweep wobec 4.3%. Wpis Google o dostępności sugeruje też podział: Carbon do ról architektury, koordynacji i audytu, w parze z szybszymi, lżejszymi modelami do pracy równoległej. W tej pętli oznacza to jedno uruchomienie planisty na Carbon, który przydziela pliki wykonawcom na Argon.
Budżety dla obu modeli znajdziesz w artykule o cenniku Gemini 4 Carbon API. Jeśli rozważasz dla agenta innych dostawców, zobacz Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Najczęściej zadawane pytania
Czy Gemini 4 Carbon API obsługuje wywoływanie funkcji w PoYo?
Obecna dokumentacja PoYo nie opisuje tools ani deklaracji funkcji dla modeli Gemini w Chat Completions ani w Gemini Native. Narzędzia są udokumentowane dla Anthropic Messages i Responses. Ten przewodnik używa protokołu akcji JSON w treści wiadomości, który wymaga wyłącznie udokumentowanych pól.
Czy mogę używać OpenAI Python SDK z Gemini 4 Carbon API?
Tak. Utwórz OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") i przekaż model="gemini-4-carbon" do chat.completions.create. Streaming działa z stream=True, a ostatni chunk zawiera usage.
Jakie jest maksymalne wyjście i okno kontekstu Gemini 4 Carbon API?
1M tokenów kontekstu i do 64K tokenów wyjściowych na odpowiedź. Ustawiaj max_tokens na 64,000 lub mniej.
Jak ograniczyć koszty Gemini 4 Carbon API w pętli agenta?
Ogranicz liczbę tur, ogranicz max_tokens na turę, obcinaj wyniki narzędzi i zatrzymuj się, gdy dotychczasowe wydatki plus najgorszy przypadek następnej tury przekroczyłyby budżet. Wydatki licz jako usage.prompt_tokens × $1.60 i usage.completion_tokens × $8.00 za 1M tokenów w PoYo.
Czy Gemini 4 Carbon API obsługuje cache'owanie kontekstu?
PoYo podaje dla Carbon cenę odczytu z cache $0.08 za 1M tokenów (16 kredytów). Dokumentacja nie opisuje obecnie parametru żądania do cache'owania ani pola usage z tokenami z cache dla modeli Gemini, więc budżetuj prompty po pełnej stawce za wejście i sprawdzaj na rachunku opłaty według stawki cache.
Kiedy agent programistyczny powinien używać Gemini 4 Argon zamiast Carbon?
Używaj Argon do rutynowego programowania, do każdej pojedynczej odpowiedzi, która musi przekroczyć 64K tokenów, oraz jako tańszej pierwszej próby przed eskalacją do Carbon. Oba kosztują w PoYo $1.60 / $8.00 za 1M tokenów, ale według Google Argon zużywa mniej tokenów na turę.