how-tos

Gemini 4 Carbon APIでコーディングエージェントを作る:ストリーミングと費用ガード付きの上限ありエージェントループ

Poyo.ai Team
5 min read
Share:

コーディングエージェントのループを動かすGemini 4 Carbon API

Gemini 4 Carbon APIは、Googleが最も難しいコーディング作業向けに位置づけるモデルです。Googleはこれをマルチステップのデバッグと長期のエージェント型コーディングのために構築し、探索、推論、検証ループの実行にArgonより多くのトークンを使うとしています。このガイドでは、PoYoのOpenAI互換エンドポイントを通じて gemini-4-carbon(モデルページ)をコーディングエージェントに組み込みます。このエージェントは出力をストリーミングし、リポジトリの大きな部分を読み込み、ターン数と金額の厳格な上限で停止し、作業をArgonに渡すべきタイミングを判断します。

まだ最初のリクエストを送っていない場合は、Gemini 4 Carbon APIガイドから始めてください。

APIがコーディングエージェントに提供するもの

項目PoYoのGemini 4 Carbon
モデルIDgemini-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
コンテキストウィンドウ100万トークン:テキスト、画像、音声、動画、PDF
1レスポンスあたりの最大出力64Kトークン
ストリーミング"stream": true。最後のチャンクに finish_reason と usage が含まれる
料金100万トークンあたり入力$1.60 / 出力$8.00 / キャッシュ読み取り$0.08(320 / 1,600 / 16クレジット)
レート制限PoYoのドキュメントによれば、LLMエンドポイントには現在レート制限がない
エラー400 不正なフィールド、401 キーの誤り、402 クレジット不足、404 不明なモデル。429 / 500 / 502 / 503 はバックオフ付きで再試行

Chat Completionsのドキュメントに記載されているリクエストフィールドは、model、messages(system、user、assistant のロールを持つ文字列の content)、max_tokens、stream、temperature、top_p、stop、n、およびペナルティ関連のフィールドです。以下のエージェントはこれらだけを使います。

ツール呼び出し:現在ドキュメント化されている範囲

PoYoはAnthropic MessagesとResponsesについて tools をドキュメント化しています。Geminiモデルについては、Chat CompletionsでもGemini Nativeでも、tools や関数宣言はドキュメント化されていません。gemini-4-carbon ではResponsesは利用できません。

そのため、このエージェントは tools 配列を送りません。代わりに、通常のメッセージ内容の中でJSONアクションプロトコルを使います。システムプロンプトで許可するアクションを列挙し、モデルは1ターンにつき1つのJSONオブジェクトで応答します。コードがそのアクションを実行し、結果を次のuserメッセージとして返します。この方法はどのチャットモデルでも機能します。PoYoがGeminiのネイティブな関数呼び出しをドキュメント化したら、パーサーを本物のツール呼び出しに置き換え、ループの残りはそのまま使えます。

安全面の利点もあります。モデルが要求できるのは、自分で書いた4つのアクションだけです。任意のシェルコマンドは実行できません。

長いコンテキストでのリポジトリ入力:入力1M、出力64K

1Mトークンのウィンドウがあれば、ファイルを1つずつ取得する代わりに、最初のターンでリポジトリの大部分を送れます。Googleの発表時の表は、それを使う理由を示しています。256K〜1MトークンのGraphWalksで、Carbonは96.2%、Argonは84.2%です。ループの設計には3つの制約が関わります。

  • 毎ターン、履歴全体が再送されます。 スナップショットは呼び出しごとに再び課金されます。300Kトークンのスナップショットを12ターン送ると少なくとも360万入力トークンになり、出力を除いても100万トークンあたり$1.60で$5.76です。
  • 出力は1レスポンスあたり64Kが上限です。 1回の応答でリポジトリ全体を書き換えさせるのではなく、write_file アクションごとに1ファイルを要求してください。
  • トークン数は推測せず測定してください。 PoYoにはトークナイザーのエンドポイントがドキュメント化されていません。最初の呼び出しの usage.prompt_tokens を読み取り、目標とするトークン予算に合わせて MAX_SNAPSHOT_CHARS を調整します。

キャッシュ。 PoYoの料金表にはCarbonのキャッシュ読み取り料金(新規入力の$1.60に対し100万トークンあたり$0.08)があり、Googleはキャッシュされた入力を95%オフにしています。PoYoのドキュメントには、Geminiモデル向けのキャッシュ用リクエストパラメーターや、キャッシュされたトークンのusageフィールドは記載されていません。このループはキャッシュ用のパラメーターを送らず、すべてのプロンプトトークンを通常の入力料金で予算計上します。システムプロンプトとスナップショットを変わらないプレフィックスとして保つことに費用はかからず、キャッシュ料金で課金された読み取りがあったかどうかは請求書で確認できます。

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_TURNSdone を呼ばずに続くループ任意に設定。12は出発点
BUDGET_USD と最悪ケースのチェック次の呼び出しで上限を超える支出ストリームの最後のチャンクの usage.prompt_tokens と usage.completion_tokens(PoYoの$1.60 / $8.00で計算)
MAX_TOKENS_PER_TURN暴走した1回の応答max_tokens。Carbonでは最大64,000
MAX_RESULT_CHARS巨大なテストログによるその後の全ターンの肥大化結果を履歴に入れる前に切り詰める
usage is None → 停止測定できない見えない支出PoYoはストリームの最後のチャンクに usage があるとドキュメント化している
402 は再試行しない残高ゼロでの再試行の嵐PoYoのエラーコード

GoogleはCarbonの出力を思考トークン込みで課金するため、1ターンで表示されたJSONより多くの出力が課金されることがあります。そのため予算計算では completion_tokens を使い、受信した文字数は決して数えません。この見積もりはすべての入力をキャッシュなしとして数えているので、PoYoが課金する額の上限値になります。最初の数回の実行では、ダッシュボードと照合してください。

最悪ケースのチェックは保守的です。履歴が300Kトークンの場合、もう1ターン実行すると少なくとも入力で$0.48、加えて max_tokens が16Kなら最大$0.128の出力がかかります。予算が$2.00なら、ループは上限を超えうる呼び出しの前に停止します。

Gemini 4 Argonにフォールバックすべき場面

Argonは同じリクエストを受け付け、入力・出力トークンの単価も同じです。Googleはこれを「大半のソフトウェアエンジニアリングとナレッジワークに最適な選択肢」と呼び、応答が速くターンあたりのトークン消費が少ないとしています。次の場合は run_agent(task, model=ARGON) でArgonに振り分けてください。

  • タスクが定型的な場合。 小さな修正、単一ファイルの変更、テストの作成には、Carbonの追加の検証トークンは必要ありません。
  • 1つのレスポンスが64Kトークンを超える必要がある場合。 Carbonの出力上限は64Kです。Argonのはるかに大きな出力上限についてはArgonガイドで解説しています。
  • 安価な最初の試行が欲しい場合。 まずArgonを実行し、テストがまだ失敗する場合にだけCarbonにエスカレーションします。Gemini 4 Carbon API vs Gemini 4 Argon APIのルーターがこれを行います。

Carbonは、リポジトリ全体にわたる根本原因の特定と、ターミナルを多用するループに使ってください。Googleの表では、Terminal-Bench 4.0 (AA)でCarbonは65.2%(Argonは57.1%)、SWE-sweepでは9.6%(同4.3%)です。Googleの提供開始の記事も役割分担を提案しています。設計、調整、監査の役割にはCarbonを使い、並列作業には高速で軽量なモデルを組み合わせる方法です。このループで言えば、Carbonのプランナーを1回実行してArgonのワーカーにファイルを割り当てることになります。

両モデルの予算はGemini 4 Carbon APIの料金記事にあります。エージェントに他社のモデルも検討している場合は、Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra APIを参照してください。

よくある質問

PoYoのGemini 4 Carbon APIは関数呼び出しに対応していますか?

PoYoの現在のドキュメントでは、Chat CompletionsとGemini NativeのいずれでもGeminiモデルの tools や関数宣言はドキュメント化されていません。ツールがドキュメント化されているのはAnthropic MessagesとResponsesです。このガイドでは、ドキュメント化されたフィールドだけで済む、メッセージ内容でのJSONアクションプロトコルを使っています。

Gemini 4 Carbon APIでOpenAI Python SDKを使えますか?

はい。OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") を作成し、chat.completions.create に model="gemini-4-carbon" を渡します。ストリーミングは stream=True で動作し、最後のチャンクに usage が含まれます。

Gemini 4 Carbon APIの最大出力とコンテキストウィンドウは?

コンテキストは100万トークン、出力は1レスポンスあたり最大64Kトークンです。max_tokens は64,000以下に設定してください。

エージェントループでGemini 4 Carbon APIの費用を抑えるには?

ターン数を制限し、ターンごとの max_tokens を制限し、ツールの結果を切り詰め、これまでの支出に最悪ケースの次のターンを加えると予算を超える場合は停止します。支出は、PoYoの100万トークンあたりの料金で usage.prompt_tokens × $1.60 と usage.completion_tokens × $8.00 から計算します。

Gemini 4 Carbon APIはコンテキストキャッシュに対応していますか?

PoYoはCarbonのキャッシュ読み取り料金を100万トークンあたり$0.08(16クレジット)と掲載しています。ドキュメントには現在、Geminiモデル向けのキャッシュ用リクエストパラメーターやキャッシュされたトークンのusageフィールドが記載されていないため、プロンプトは通常の入力料金で予算計上し、キャッシュ料金での課金があるかどうかは請求書で確認してください。

コーディングエージェントでCarbonではなくGemini 4 Argonを使うべきなのはどんなときですか?

定型的なコーディング、64Kトークンを超える必要がある単一レスポンス、そしてCarbonにエスカレーションする前の安価な最初の試行にはArgonを使ってください。PoYoではどちらも100万トークンあたり$1.60 / $8.00ですが、GoogleによればArgonはターンあたりのトークン消費が少なくなります。

Share: