how-tos

Gemini 4 Carbon API dla agentów programistycznych: ograniczona pętla agenta ze streamingiem i kontrolą kosztów

Poyo.ai Team
10 min read
Share:

Gemini 4 Carbon API napędzające pętlę agenta programistycznego

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

ElementGemini 4 Carbon w PoYo
ID modelugemini-4-carbon
Endpoint agenta użyty tutajPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Natywna alternatywaPOST /v1beta/models/gemini-4-carbon:generateContent i :streamGenerateContent
Okno kontekstu1M 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ściDokumentacja PoYo mówi, że endpointy LLM obecnie nie mają limitów częstotliwości
Błędy400 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_tokens z pierwszego wywołania, a potem dostosuj MAX_SNAPSHOT_CHARS do 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

ZabezpieczenieCo zatrzymujeSkąd bierze się liczba
MAX_TURNSPętle, które nigdy nie wywołują doneTwój wybór; 12 to punkt wyjścia
BUDGET_USD + kontrola najgorszego przypadkuPrzekroczenie limitu przy następnym wywołaniuusage.prompt_tokens i usage.completion_tokens z ostatniego chunka strumienia, według stawek PoYo $1.60 / $8.00
MAX_TOKENS_PER_TURNPojedynczą niekontrolowaną odpowiedźmax_tokens, dla Carbon najwyżej 64,000
MAX_RESULT_CHARSOgromne logi testów rozdmuchujące każdą kolejną turęObcięcie, zanim wynik trafi do historii
usage is None → stopCiche wydatki, których nie da się zmierzyćPoYo dokumentuje usage w ostatnim chunku strumienia
402 nie jest ponawianyLawinę ponowień przy pustym saldzieKody 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ę.

Share: