how-tos

Gemini 4 Carbon API cho coding agent: Vòng lặp agent có giới hạn, kèm streaming và chốt chặn chi phí

Poyo.ai Team
12 min read
Share:

Gemini 4 Carbon API vận hành vòng lặp của một coding agent

Gemini 4 Carbon API là lựa chọn của Google cho những việc lập trình khó nhất. Google xây dựng mô hình này cho gỡ lỗi nhiều bước và lập trình agent dài hơi, và cho biết nó tiêu tốn nhiều token hơn Argon để khám phá, suy luận và chạy các vòng kiểm chứng. Hướng dẫn này nối gemini-4-carbon (trang mô hình) vào một coding agent thông qua endpoint tương thích OpenAI của PoYo. Agent stream đầu ra, có thể đọc một phần lớn repository, dừng lại ở giới hạn cứng về số lượt và ngân sách tính bằng đô la, và biết khi nào nên chuyển việc sang Argon.

Nếu bạn chưa gửi yêu cầu đầu tiên, hãy bắt đầu với hướng dẫn Gemini 4 Carbon API.

API cung cấp gì cho một coding agent

Hạng mụcGemini 4 Carbon trên PoYo
Model IDgemini-4-carbon
Endpoint agent dùng ở đâyPOST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Lựa chọn nativePOST /v1beta/models/gemini-4-carbon:generateContent và :streamGenerateContent
Cửa sổ ngữ cảnh1M token: văn bản, hình ảnh, âm thanh, video, PDF
Đầu ra tối đa mỗi phản hồi64K token
Streaming"stream": true; chunk cuối cùng chứa finish_reason và usage
Giá$1.60 đầu vào / $8.00 đầu ra / $0.08 đọc cache cho mỗi 1M token (320 / 1,600 / 16 credit)
Giới hạn tốc độTài liệu PoYo cho biết các endpoint LLM hiện không bị giới hạn tốc độ
Lỗi400 trường không hợp lệ, 401 khóa sai, 402 không đủ credit, 404 mô hình không xác định; thử lại 429 / 500 / 502 / 503 với backoff

Tài liệu Chat Completions mô tả các trường yêu cầu sau: model, messages (content dạng chuỗi với vai trò system, user hoặc assistant), max_tokens, stream, temperature, top_p, stop, n và các trường penalty. Agent bên dưới chỉ dùng những trường này.

Tool calling: những gì đã được tài liệu hóa đến nay

PoYo tài liệu hóa tools cho Anthropic Messages và cho Responses. PoYo không tài liệu hóa tools hay khai báo hàm (function declaration) cho các mô hình Gemini, ở cả Chat Completions lẫn Gemini Native. Responses không khả dụng cho gemini-4-carbon.

Vì vậy agent này không gửi mảng tools. Thay vào đó, nó dùng một giao thức hành động JSON trong nội dung tin nhắn thông thường. System prompt liệt kê các hành động được phép, mô hình trả lời bằng một đối tượng JSON mỗi lượt, mã của bạn thực thi hành động đó rồi gửi kết quả lại dưới dạng tin nhắn user tiếp theo. Cách này hoạt động với mọi mô hình chat. Khi PoYo tài liệu hóa function calling native cho Gemini, bạn có thể thay bộ phân tích bằng tool call thật và giữ nguyên phần còn lại của vòng lặp.

Cách này còn có lợi về an toàn: mô hình chỉ có thể yêu cầu bốn hành động do chính bạn viết. Nó không thể chạy một lệnh shell tùy ý.

Đầu vào repo ngữ cảnh dài: 1M vào, 64K ra

Cửa sổ 1M token cho phép bạn gửi một phần lớn repository ngay ở lượt đầu, thay vì lấy từng file một. Bảng công bố của Google đưa ra lý do để dùng nó: Carbon đạt 96,2% trên GraphWalks ở mức 256K–1M token, so với 84,2% của Argon. Ba giới hạn định hình vòng lặp:

  • Mỗi lượt gửi lại toàn bộ lịch sử. Snapshot bị tính phí lại ở mỗi lần gọi. Một snapshot 300K token qua 12 lượt tốn ít nhất 3,6M token đầu vào, tức $5.76 với giá $1.60 mỗi 1M, chưa tính đầu ra.
  • Đầu ra bị giới hạn 64K mỗi phản hồi. Hãy yêu cầu một file cho mỗi hành động write_file, đừng yêu cầu viết lại cả repo trong một lần trả lời.
  • Đo số token, đừng đoán. PoYo không tài liệu hóa endpoint tokenizer nào. Đọc usage.prompt_tokens từ lần gọi đầu tiên, rồi chỉnh MAX_SNAPSHOT_CHARS theo ngân sách token bạn muốn.

Cache. Bảng giá của PoYo có mức giá đọc cache cho Carbon ($0.08 mỗi 1M, so với $1.60 cho đầu vào mới), và Google định giá đầu vào đã cache rẻ hơn 95%. Tài liệu PoYo không mô tả tham số yêu cầu để bật cache hay trường usage cho token đã cache đối với các mô hình Gemini. Vòng lặp này không gửi tham số cache nào và tính mọi token prompt theo giá đầu vào đầy đủ. Giữ system prompt và snapshot làm phần tiền tố không đổi không tốn thêm gì, và hóa đơn của bạn sẽ cho thấy có lần đọc nào được tính theo giá cache hay không.

Vòng lặp agent có giới hạn bằng 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 cần Python 3.9 trở lên. Hãy chạy agent trên một bản sao hoặc một nhánh của repository, vì write_file ghi đè file.

Các chốt chặn chi phí hoạt động thế nào

Chốt chặnNgăn chặn điều gìCon số lấy từ đâu
MAX_TURNSVòng lặp không bao giờ gọi doneDo bạn chọn; 12 là điểm khởi đầu
BUDGET_USD + kiểm tra trường hợp xấu nhấtChi vượt giới hạn ở lần gọi tiếp theousage.prompt_tokens và usage.completion_tokens từ chunk stream cuối, theo giá $1.60 / $8.00 của PoYo
MAX_TOKENS_PER_TURNMột phản hồi chạy mất kiểm soátmax_tokens, tối đa 64,000 với Carbon
MAX_RESULT_CHARSLog test khổng lồ làm phình mọi lượt sauCắt bớt trước khi kết quả vào lịch sử
usage is None → dừngChi tiêu âm thầm mà bạn không đo đượcPoYo tài liệu hóa usage trên chunk stream cuối
Không thử lại 402Bão thử lại khi số dư đã hếtMã lỗi PoYo

Google tính giá đầu ra của Carbon bao gồm cả thinking token, nên một lượt có thể bị tính nhiều đầu ra hơn phần JSON bạn nhìn thấy. Đó là lý do ngân sách dùng completion_tokens và không bao giờ đếm số ký tự bạn nhận được. Ước tính coi toàn bộ đầu vào là không cache, nên đây là cận trên của số tiền PoYo sẽ tính. Hãy đối chiếu với dashboard của bạn trong vài lần chạy đầu.

Phép kiểm tra trường hợp xấu nhất mang tính thận trọng. Với lịch sử 300K token, thêm một lượt tốn ít nhất $0.48 đầu vào cộng tối đa $0.128 đầu ra khi max_tokens là 16K. Với ngân sách $2.00, vòng lặp dừng trước lần gọi có thể vượt giới hạn.

Khi nào chuyển sang Gemini 4 Argon

Argon nhận cùng một yêu cầu và có cùng giá cho mỗi token đầu vào và đầu ra. Google gọi nó là "lựa chọn lý tưởng cho phần lớn công việc kỹ thuật phần mềm và công việc tri thức", với phản hồi nhanh hơn và tốn ít token hơn mỗi lượt. Chuyển sang Argon bằng run_agent(task, model=ARGON) khi:

  • Nhiệm vụ mang tính thường lệ. Sửa lỗi nhỏ, thay đổi trong một file và viết test không cần thêm các token kiểm chứng của Carbon.
  • Một phản hồi phải vượt quá 64K token. Carbon giới hạn đầu ra ở 64K. Hướng dẫn Argon của chúng tôi trình bày giới hạn đầu ra lớn hơn nhiều của Argon.
  • Bạn muốn một lần thử đầu tiên rẻ. Chạy Argon trước và chỉ chuyển lên Carbon khi test vẫn thất bại. Bộ định tuyến trong bài Gemini 4 Carbon API vs Gemini 4 Argon API làm đúng việc này.

Hãy dành Carbon cho việc truy tìm nguyên nhân gốc trên toàn repository và các vòng lặp dùng terminal nhiều. Trong bảng của Google, Carbon đạt 65,2% trên Terminal-Bench 4.0 (AA) so với 57,1% của Argon, và 9,6% trên SWE-sweep so với 4,3%. Bài thông báo ra mắt của Google cũng gợi ý một cách chia việc: Carbon cho vai trò kiến trúc, điều phối và kiểm tra, kết hợp với các mô hình nhanh hơn, nhẹ hơn cho công việc song song. Trong vòng lặp này, điều đó nghĩa là một lần chạy Carbon làm planner để giao file cho các worker Argon.

Ngân sách cho cả hai mô hình có trong bài về giá Gemini 4 Carbon API. Nếu bạn đang cân nhắc nhà cung cấp khác cho agent, xem Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.

Câu hỏi thường gặp

Gemini 4 Carbon API có hỗ trợ function calling trên PoYo không?

Tài liệu hiện tại của PoYo không mô tả tools hay khai báo hàm cho các mô hình Gemini trong Chat Completions hoặc Gemini Native. Tools được tài liệu hóa cho Anthropic Messages và Responses. Hướng dẫn này dùng giao thức hành động JSON trong nội dung tin nhắn, chỉ cần các trường đã được tài liệu hóa.

Tôi có thể dùng OpenAI Python SDK với Gemini 4 Carbon API không?

Có. Tạo OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") và truyền model="gemini-4-carbon" vào chat.completions.create. Streaming hoạt động với stream=True, và chunk cuối cùng chứa usage.

Đầu ra tối đa và cửa sổ ngữ cảnh của Gemini 4 Carbon API là bao nhiêu?

Ngữ cảnh 1M token và tối đa 64K token đầu ra mỗi phản hồi. Đặt max_tokens ở mức 64,000 hoặc thấp hơn.

Làm sao giới hạn chi phí Gemini 4 Carbon API trong vòng lặp agent?

Giới hạn số lượt, giới hạn max_tokens mỗi lượt, cắt bớt kết quả tool, và dừng khi số tiền đã chi cộng với lượt tiếp theo trong trường hợp xấu nhất sẽ vượt ngân sách. Tính chi phí từ usage.prompt_tokens × $1.60 và usage.completion_tokens × $8.00 cho mỗi 1M token trên PoYo.

Gemini 4 Carbon API có hỗ trợ context caching không?

PoYo niêm yết giá đọc cache cho Carbon là $0.08 mỗi 1M token (16 credit). Tài liệu của PoYo hiện chưa mô tả tham số yêu cầu để bật cache hay trường usage cho token đã cache đối với các mô hình Gemini, vì vậy hãy tính ngân sách prompt theo giá đầu vào đầy đủ và kiểm tra hóa đơn xem có khoản nào tính theo giá cache không.

Khi nào coding agent nên dùng Gemini 4 Argon thay vì Carbon?

Dùng Argon cho việc lập trình thường lệ, cho bất kỳ phản hồi đơn lẻ nào phải vượt quá 64K token, và làm lần thử đầu tiên rẻ hơn trước khi chuyển lên Carbon. Cả hai đều có giá $1.60 / $8.00 mỗi 1M token trên PoYo, nhưng theo Google, Argon dùng ít token hơn mỗi lượt.

Share: