
Gemini 4 Carbon API는 Google이 가장 어려운 코딩 작업용으로 내세우는 모델입니다. Google은 이 모델을 다단계 디버깅과 장기 과제 에이전트 코딩을 위해 만들었으며, 탐색하고 추론하고 검증 루프를 실행하는 데 Argon보다 더 많은 토큰을 쓴다고 밝힙니다. 이 가이드에서는 PoYo의 OpenAI 호환 엔드포인트를 통해 gemini-4-carbon(모델 페이지)을 코딩 에이전트에 연결합니다. 이 에이전트는 출력을 스트리밍하고, 저장소의 큰 부분을 읽을 수 있으며, 엄격한 턴 수와 달러 예산에서 멈추고, 언제 Argon에 작업을 넘길지 압니다.
아직 첫 요청을 보내 보지 않았다면 Gemini 4 Carbon API 가이드부터 시작하세요.
API가 코딩 에이전트에 제공하는 것
| 항목 | PoYo의 Gemini 4 Carbon |
|---|---|
| 모델 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 포함 |
| 가격 | 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 배열을 보내지 않습니다. 대신 일반 메시지 content 안에서 JSON 액션 프로토콜을 사용합니다. 시스템 프롬프트에 허용된 액션을 나열하면, 모델은 턴마다 JSON 객체 하나로 답하고, 코드가 그 액션을 실행해 결과를 다음 user 메시지로 돌려보냅니다. 이 방식은 어떤 채팅 모델에서도 동작합니다. PoYo가 Gemini용 네이티브 함수 호출을 문서화하면, 파서를 실제 도구 호출로 바꾸고 루프의 나머지는 그대로 둘 수 있습니다.
안전상의 이점도 있습니다. 모델은 직접 작성한 네 가지 액션만 요청할 수 있고, 임의의 셸 명령은 실행할 수 없습니다.
긴 컨텍스트 저장소 입력: 입력 1M, 출력 64K
1M 토큰 윈도우 덕분에 파일을 하나씩 가져오는 대신 첫 턴에 저장소의 큰 부분을 보낼 수 있습니다. Google의 출시 표가 그 근거를 제공합니다. 256K–1M 토큰 범위의 GraphWalks에서 Carbon은 96.2%, Argon은 84.2%입니다. 루프를 설계할 때 세 가지 제한을 고려해야 합니다.
- 매 턴마다 전체 기록을 다시 보냅니다. 스냅샷은 호출할 때마다 다시 과금됩니다. 300K 토큰 스냅샷으로 12턴을 돌리면 최소 3.6M 입력 토큰이며, 출력을 빼고도 100만 토큰당 $1.60 기준 $5.76입니다.
- 출력은 응답당 64K로 제한됩니다. 저장소 전체를 한 번의 응답으로 다시 쓰게 하지 말고,
write_file액션 하나당 파일 하나를 요청하세요. - 토큰 수는 추측하지 말고 측정하세요. 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_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, 그리고 max_tokens 16K 기준으로 출력이 최대 $0.128 듭니다. 예산이 $2.00이라면 루프는 상한을 넘을 수 있는 호출 직전에 멈춥니다.
Gemini 4 Argon으로 폴백해야 할 때
Argon은 같은 요청을 받고 입력·출력 토큰당 가격도 같습니다. Google은 Argon을 "대부분의 소프트웨어 엔지니어링과 지식 작업에 이상적인 선택"이라고 부르며, 더 빠른 응답과 턴당 더 적은 토큰 사용을 특징으로 듭니다. 다음 경우에는 run_agent(task, model=ARGON)으로 Argon에 보내세요.
- 작업이 일상적일 때. 작은 수정, 단일 파일 변경, 테스트 작성에는 Carbon의 추가 검증 토큰이 필요 없습니다.
- 단일 응답이 64K 토큰을 넘어야 할 때. Carbon은 출력을 64K로 제한합니다. Argon의 훨씬 큰 출력 한도는 Argon 가이드에서 다룹니다.
- 저렴한 첫 시도를 원할 때. 먼저 Argon을 실행하고, 테스트가 여전히 실패할 때만 Carbon으로 승격하세요. Gemini 4 Carbon API vs Gemini 4 Argon API의 라우터가 이를 수행합니다.
Carbon은 저장소 전체의 근본 원인 분석과 터미널 중심 루프에 쓰세요. Google 표에서 Carbon은 Terminal-Bench 4.0 (AA)에서 65.2%로 Argon의 57.1%를, SWE-sweep에서 9.6%로 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를 참고하세요.
자주 묻는 질문
PoYo에서 Gemini 4 Carbon API는 함수 호출을 지원하나요?
PoYo의 현재 문서는 Chat Completions와 Gemini Native에서 Gemini 모델용 tools나 함수 선언을 문서화하지 않습니다. 도구는 Anthropic Messages와 Responses에 대해 문서화되어 있습니다. 이 가이드는 문서화된 필드만 필요한 메시지 content 기반 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의 최대 출력과 컨텍스트 윈도우는 얼마인가요?
컨텍스트는 1M 토큰이고 출력은 응답당 최대 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은 턴당 더 적은 토큰을 사용합니다.