how-tos

Gemini 4 Carbon API для агентов разработки: ограниченный агентный цикл со стримингом и контролем затрат

Poyo.ai Team
10 min read
Share:

Gemini 4 Carbon API в агентном цикле разработки

Gemini 4 Carbon API — выбор Google для самых сложных задач разработки. Google создала модель для многошаговой отладки и агентной разработки с длинным горизонтом и говорит, что она тратит больше токенов, чем Argon, на исследование, рассуждение и циклы проверки. Это руководство подключает gemini-4-carbon (страница модели) к агенту разработки через OpenAI-совместимый эндпоинт PoYo. Агент стримит вывод, может прочитать большой фрагмент репозитория, останавливается по жёсткому лимиту ходов и бюджета в долларах и знает, когда передать работу Argon.

Если вы ещё не отправляли первый запрос, начните с руководства по Gemini 4 Carbon API.

Что API даёт агенту разработки

ПараметрGemini 4 Carbon в PoYo
ID моделиgemini-4-carbon
Эндпоинт агента в этом руководствеPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Нативная альтернативаPOST /v1beta/models/gemini-4-carbon:generateContent и :streamGenerateContent
Контекстное окно1M токенов: текст, изображения, аудио, видео, PDF
Максимальный вывод на ответ64K токенов
Стриминг"stream": true; последний чанк содержит finish_reason и usage
Цена$1.60 за вход / $8.00 за выход / $0.08 за чтение из кэша за 1M токенов (320 / 1,600 / 16 кредитов)
Ограничения частотыВ документации PoYo сказано, что LLM-эндпоинты сейчас не ограничены по частоте
Ошибки400 некорректные поля, 401 неверный ключ, 402 недостаточно кредитов, 404 неизвестная модель; 429 / 500 / 502 / 503 повторяйте с задержкой

Документация Chat Completions описывает такие поля запроса: model, messages (строковый content с ролями system, user или assistant), max_tokens, stream, temperature, top_p, stop, n и поля штрафов. Агент ниже использует только их.

Вызов инструментов: что задокументировано сейчас

PoYo документирует tools для Anthropic Messages и для Responses. Для моделей Gemini tools и объявления функций не задокументированы ни в Chat Completions, ни в Gemini Native. Responses для gemini-4-carbon недоступен.

Поэтому этот агент не отправляет массив tools. Вместо этого он использует протокол JSON-действий в обычном содержимом сообщений. Системный промпт перечисляет допустимые действия, модель отвечает одним JSON-объектом за ход, а ваш код выполняет это действие и отправляет результат обратно следующим сообщением пользователя. Это работает с любой чат-моделью. Когда PoYo задокументирует нативный вызов функций для Gemini, вы сможете заменить парсер на настоящие вызовы инструментов и оставить остальной цикл как есть.

Есть и выигрыш в безопасности: модель может запросить только четыре действия, которые вы написали сами. Произвольную команду оболочки она выполнить не может.

Репозиторий в длинном контексте: 1M на входе, 64K на выходе

Окно в 1M токенов позволяет отправить большую часть репозитория уже на первом ходу, а не получать файлы по одному. В таблице Google к запуску есть повод этим воспользоваться: Carbon набирает 96.2% на GraphWalks при 256K–1M токенов против 84.2% у Argon. Цикл определяют три ограничения:

  • Каждый ход заново отправляет всю историю. Снимок оплачивается при каждом вызове заново. Снимок на 300K токенов за 12 ходов — это минимум 3.6M входных токенов, то есть $5.76 при $1.60 за 1M ещё до какого-либо вывода.
  • Вывод ограничен 64K на ответ. Просите один файл на действие write_file, а не переписывание всего репозитория в одном ответе.
  • Измеряйте число токенов, а не угадывайте. В PoYo не задокументирован эндпоинт токенизатора. Возьмите usage.prompt_tokens из первого вызова, а затем подстройте MAX_SNAPSHOT_CHARS под нужный бюджет токенов.

Кэширование. В таблице цен PoYo есть ставка чтения из кэша для Carbon ($0.08 за 1M против $1.60 за новый вход), а Google оценивает кэшированный вход со скидкой 95%. В документации PoYo не описаны ни параметр запроса для кэширования, ни поле usage с кэшированными токенами для моделей Gemini. Этот цикл не отправляет параметров кэширования и закладывает в бюджет каждый токен промпта по полной ставке входа. Сохранение системного промпта и снимка неизменным префиксом ничего не стоит, а ваш счёт покажет, были ли какие-то чтения оплачены по ставке кэша.

Ограниченный агентный цикл на 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 требует Python 3.9 или новее. Запускайте агента на копии или в отдельной ветке репозитория, поскольку write_file перезаписывает файлы.

Как работают ограничители затрат

ОграничительЧто он предотвращаетОткуда берётся число
MAX_TURNSЦиклы, которые никогда не вызывают doneВаш выбор; 12 — отправная точка
BUDGET_USD + проверка худшего случаяВыход за лимит на следующем вызовеusage.prompt_tokens и usage.completion_tokens из последнего чанка стрима по ставкам PoYo $1.60 / $8.00
MAX_TOKENS_PER_TURNОдин неуправляемый ответmax_tokens, для Carbon не больше 64,000
MAX_RESULT_CHARSОгромные логи тестов, раздувающие все последующие ходыОбрезка до того, как результат попадёт в историю
usage is None → остановкаСкрытые расходы, которые невозможно измеритьPoYo документирует usage в последнем чанке стрима
402 не повторяетсяЛавина повторов при нулевом балансеКоды ошибок PoYo

Google тарифицирует вывод Carbon вместе с токенами мышления, поэтому ход может стоить больше выходных токенов, чем видно в JSON. Именно поэтому бюджет опирается на completion_tokens и никогда не считает полученные символы. Оценка считает весь вход некэшированным, так что это оценка сверху того, что выставит PoYo. Сверьте её со своей панелью на первых нескольких запусках.

Проверка худшего случая консервативна. При истории на 300K токенов ещё один ход стоит минимум $0.48 за вход плюс до $0.128 за вывод при max_tokens 16K. При бюджете $2.00 цикл останавливается перед вызовом, который мог бы превысить лимит.

Когда переходить на Gemini 4 Argon

Argon принимает тот же запрос и стоит столько же за входной и выходной токен. Google называет её «идеальным выбором для большинства задач разработки ПО и работы со знаниями» с более быстрыми ответами и меньшим расходом токенов на ход. Направляйте в неё работу через run_agent(task, model=ARGON), когда:

  • Задача рутинная. Мелким исправлениям, изменениям в одном файле и написанию тестов дополнительные токены проверки Carbon не нужны.
  • Один ответ должен превышать 64K токенов. Carbon ограничивает вывод 64K. Гораздо больший лимит вывода Argon описан в нашем руководстве по Argon.
  • Нужна дешёвая первая попытка. Сначала запустите Argon и эскалируйте в Carbon, только если тесты всё ещё падают. Именно так работает маршрутизатор из статьи Gemini 4 Carbon API vs Gemini 4 Argon API.

Оставьте Carbon для поиска первопричин на уровне всего репозитория и циклов с интенсивной работой в терминале. В таблице Google Carbon набирает 65.2% на Terminal-Bench 4.0 (AA) против 57.1% у Argon и 9.6% на SWE-sweep против 4.3%. В посте Google о доступности также предлагается разделение: Carbon — для ролей архитектуры, координации и аудита, в паре с более быстрыми и лёгкими моделями для параллельной работы. В этом цикле это означает один запуск планировщика на Carbon, который распределяет файлы между исполнителями на Argon.

Бюджеты для обеих моделей — в статье о ценах Gemini 4 Carbon API. Если для агента вы рассматриваете других вендоров, см. Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.

Часто задаваемые вопросы

Поддерживает ли Gemini 4 Carbon API вызов функций в PoYo?

В текущей документации PoYo tools и объявления функций для моделей Gemini не описаны ни в Chat Completions, ни в Gemini Native. Инструменты задокументированы для Anthropic Messages и Responses. В этом руководстве используется протокол JSON-действий в содержимом сообщений, которому нужны только задокументированные поля.

Можно ли использовать OpenAI Python SDK с Gemini 4 Carbon API?

Да. Создайте OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") и передайте model="gemini-4-carbon" в chat.completions.create. Стриминг работает с stream=True, а последний чанк содержит usage.

Какой максимальный вывод и контекстное окно у Gemini 4 Carbon API?

1M токенов контекста и до 64K выходных токенов на ответ. Задавайте max_tokens не больше 64,000.

Как ограничить затраты на Gemini 4 Carbon API в агентном цикле?

Ограничьте число ходов, ограничьте max_tokens на ход, обрезайте результаты инструментов и останавливайтесь, когда уже потраченная сумма плюс худший сценарий следующего хода превысили бы бюджет. Считайте расходы как usage.prompt_tokens × $1.60 и usage.completion_tokens × $8.00 за 1M токенов в PoYo.

Поддерживает ли Gemini 4 Carbon API кэширование контекста?

В PoYo для Carbon указана цена чтения из кэша $0.08 за 1M токенов (16 кредитов). В документации сейчас не описаны ни параметр запроса для кэширования, ни поле usage с кэшированными токенами для моделей Gemini, поэтому закладывайте в бюджет промпты по полной ставке входа и проверяйте в счёте списания по ставке кэша.

Когда агенту разработки использовать Gemini 4 Argon вместо Carbon?

Используйте Argon для рутинной разработки, для любого одиночного ответа длиннее 64K токенов и как более дешёвую первую попытку перед эскалацией в Carbon. Обе стоят $1.60 / $8.00 за 1M токенов в PoYo, но, по словам Google, Argon расходует меньше токенов на ход.

Share: