
GPT-6.2 API는 현재 OpenAI가 에이전트 작업에 권하는 모델입니다. API 변경 로그는 gpt-6.2-sol을 "일상적인 코딩과 에이전트 워크플로"에, gpt-6.2-astra를 "까다로운 추론과 코딩 작업"에 권장합니다. 이 가이드에서는 두 모델 중 하나를 PoYo의 Responses 엔드포인트를 통해 코딩 에이전트에 연결합니다. 함수 도구, 상한이 있는 루프, 진행 상황 스트리밍, 대규모 저장소 컨텍스트, 그리고 긴 세션의 비용을 감당할 만하게 유지하는 캐싱까지 다룹니다. GPT-6.2 Sol 모델 페이지에서 시작하고, GPT-6.2 Astra는 승격용으로 남겨 두세요.
아직 첫 요청을 보내 보지 않았다면 GPT-6.2 API 가이드부터 시작하세요.
API가 코딩 에이전트에 제공하는 것
| 항목 | PoYo의 GPT-6.2 |
|---|---|
| 모델 ID | gpt-6.2-sol (기본), gpt-6.2-astra (승격용) |
| 에이전트 엔드포인트 | POST https://api.poyo.ai/v1/responses (OpenAI SDK, base_url="https://api.poyo.ai/v1") |
| 도구 호출 | Responses에서만. OpenAI: "도구 호출에는 Responses가 필요합니다" |
| 컨텍스트 / 최대 입력 / 최대 출력 | 1,050,000 / 922,000 / 128,000 토큰 |
| 스트리밍 | "stream": true. response.completed가 최종 출력과 usage를 전달 |
| 추론 | reasoning.effort. none은 거부됨, medium부터 시작 |
| 100만당 가격 (Sol) | 입력 $1.60 / 출력 $8 / 캐시 읽기 $0.08 / 캐시 쓰기 $2 |
| 100만당 가격 (Astra) | 입력 $6.40 / 출력 $32 / 캐시 읽기 $0.32 / 캐시 쓰기 $8 |
| 오류 | 400 잘못된 필드, 401 잘못된 키, 402 크레딧 부족, 404 알 수 없는 모델. 429 / 5xx는 백오프로 재시도 |
PoYo의 Responses 레퍼런스는 tools, tool_choice, parallel_tool_calls, reasoning, include, store, previous_response_id, truncation을 문서화하며, 도구 지원은 모델에 따라 다르다고 밝힙니다. OpenAI 모델 페이지에는 GPT-6.2의 함수 호출과 여러 호스팅 도구가 나와 있습니다. PoYo 문서에 호스팅 도구 예시로 나온 것은 web_search_preview뿐이므로, 이 에이전트는 처음부터 끝까지 직접 제어할 수 있는 자체 함수 도구를 사용합니다.
함수 도구 정의하기
도구 세트는 작고 안전하게 유지하세요. 모델은 여러분이 구현한 동작만 요청할 수 있습니다.
import json, os, subprocess
from pathlib import Path
from openai import OpenAI
client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])
REPO = Path("/srv/checkout").resolve()
TOOLS = [
{"type": "function", "name": "read_file",
"description": "Read a UTF-8 text file from the repository.",
"parameters": {"type": "object", "properties": {"path": {"type": "string"}},
"required": ["path"], "additionalProperties": False}},
{"type": "function", "name": "write_file",
"description": "Replace a file in the repository with new content.",
"parameters": {"type": "object",
"properties": {"path": {"type": "string"}, "content": {"type": "string"}},
"required": ["path", "content"], "additionalProperties": False}},
{"type": "function", "name": "run_tests",
"description": "Run the test suite and return the last 200 lines of output.",
"parameters": {"type": "object", "properties": {}, "additionalProperties": False}},
]
def safe_path(p: str) -> Path:
full = (REPO / p).resolve()
if not full.is_relative_to(REPO):
raise ValueError("path escapes the repository")
return full
def call_tool(name: str, args: dict) -> str:
try:
if name == "read_file":
return safe_path(args["path"]).read_text(encoding="utf-8")[:200_000]
if name == "write_file":
safe_path(args["path"]).write_text(args["content"], encoding="utf-8")
return "ok"
if name == "run_tests":
r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
return "\n".join((r.stdout + r.stderr).splitlines()[-200:])
return f"unknown tool {name}"
except Exception as e: # return errors to the model instead of crashing the loop
return f"error: {e}"
에이전트는 쓰고 버릴 수 있는 체크아웃이나 컨테이너에서 실행하고, 작업 중인 워킹 트리에서는 절대 실행하지 마세요.
상한이 있는 에이전트 루프
이 루프는 대화를 보내고, 모든 function_call 항목을 실행한 뒤, 같은 call_id를 가진 function_call_output을 덧붙이고, 모델이 도구 호출 없이 답할 때까지 반복합니다. 턴 상한과 금액 예산에 도달하면 멈춥니다.
PRICES = {"gpt-6.2-sol": (1.60, 8.00, 0.08, 2.00), "gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00)}
def cost(model, u) -> float:
p_in, p_out, p_read, p_write = PRICES[model]
d = getattr(u, "input_tokens_details", None)
read = getattr(d, "cached_tokens", 0) or 0
write = getattr(d, "cache_write_tokens", 0) or 0
return ((u.input_tokens - read - write) * p_in + read * p_read
+ write * p_write + u.output_tokens * p_out) / 1e6
DEVELOPER = ("You are a coding agent working in a Python repository. "
"Read files before editing. Run the tests after every change. "
"When the tests pass, reply with a short summary and no tool call.")
def run_agent(task: str, model="gpt-6.2-sol", max_turns=30, budget_usd=3.00):
items = [{"role": "developer", "content": DEVELOPER},
{"role": "user", "content": task}]
spent = 0.0
for turn in range(max_turns):
resp = client.responses.create(
model=model, input=items, tools=TOOLS,
reasoning={"effort": "medium"}, max_output_tokens=16000,
store=False, include=["reasoning.encrypted_content"],
)
spent += cost(model, resp.usage)
items += [o.model_dump(exclude_none=True) for o in resp.output]
calls = [o for o in resp.output if o.type == "function_call"]
if not calls:
return resp.output_text, spent, turn + 1
for c in calls:
items.append({"type": "function_call_output", "call_id": c.call_id,
"output": call_tool(c.name, json.loads(c.arguments))})
if spent >= budget_usd:
break
raise RuntimeError(f"stopped after {turn + 1} turns, ${spent:.3f} spent")
루프를 이렇게 만든 이유:
- 출력 항목은 추론 항목을 포함해 순서대로 다시 넣습니다. Zero Data Retention처럼
store가 false인 요청에 대해 OpenAI GPT-6.2 가이드는 "암호화된 추론 항목을 포함해 이전 출력 항목을 순서대로 다시 전달하라"고 안내합니다.include=["reasoning.encrypted_content"]가 이를 요청합니다. 다른 방법은 저장된 응답과 함께previous_response_id를 쓰는 것으로, PoYo도 이 방식을 문서화하고 있습니다. - 기록은 덧붙이기만 합니다. OpenAI는 대화 도중 편집하면 Responses API가 추론 항목을 버릴 수 있고, 이는 "답변 품질을 떨어뜨리고 토큰 사용량을 늘릴 수 있다"고 경고합니다. 편집은 캐시된 프리픽스도 깨뜨립니다.
- 예산은 매 턴 확인합니다. 청구서와 같은 가격표를 사용합니다.
이 글을 위해 이 루프 그대로를 PoYo에서 처음부터 끝까지 실행해 보지는 않았습니다. 먼저 작은 작업으로 실행해 도구 호출과 usage가 예상대로 나오는지 확인하세요.
사용자에게 진행 상황 스트리밍하기
긴 에이전트 턴은 피드백이 없으면 느리게 느껴집니다. 각 턴을 스트리밍해 텍스트 델타를 보여 주고, 최종 출력은 response.completed에서 가져오세요. 다음은 PoYo가 문서화한 이벤트 타입입니다.
def stream_turn(model, items):
final = None
with client.responses.create(model=model, input=items, tools=TOOLS,
reasoning={"effort": "medium"}, max_output_tokens=16000,
store=False, include=["reasoning.encrypted_content"],
stream=True) as stream:
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
final = event.response
elif event.type == "response.failed":
raise RuntimeError(event.response)
return final # same object as the non-streaming call: .output, .usage
루프 안의 responses.create 자리에 stream_turn을 넣으세요. 도구 호출은 이전과 똑같이 final.output에서 읽습니다.
긴 컨텍스트: 입력 922K, 출력 128K
GPT-6.2는 요청당 최대 922,000 입력 토큰을 받습니다. 에이전트는 파일을 하나씩 읽는 대신 저장소의 상당 부분을 처음에 불러올 수 있습니다. 이 선택을 좌우하는 제약은 세 가지입니다.
- 매 턴 기록 전체를 다시 보냅니다. 200K 토큰 스냅샷으로 20턴을 진행하면 입력은 최소 4M 토큰입니다. Sol의 $1.60 기준으로 캐시 없이 $6.40입니다. 스냅샷 캐시 쓰기 1회($0.40)와 $0.08의 캐시 읽기 19회($0.30)라면 약 $0.70입니다.
- OpenAI의 긴 컨텍스트 요금은 입력 272K 토큰 초과부터 적용됩니다. OpenAI 가격 페이지는 이 기준선을 넘으면 요청 전체에 대해 입력·캐시 요금을 두 배로 하고 출력을 1.5×로 과금합니다. 작업에 꼭 필요하지 않다면 에이전트 요청을 272K 미만으로 유지하고, 적용되는 PoYo 요금은 모델 페이지에서 확인하세요.
- 추론은 출력 예산을 공유합니다.
max_output_tokens는 보이는 텍스트와 추론을 합친 상한입니다. 저장소 전체를 다시 쓰게 하기보다write_file호출마다 파일 하나를 요청하세요.
도구 출력은 덧붙이기 전에 줄이세요. 테스트 실행 결과는 20,000줄이 아니라 마지막 200줄을 반환합니다. 그래야 턴당 증가량과 청구 금액이 선형적이고 작게 유지됩니다.
에이전트 세션을 위한 프롬프트 캐싱
OpenAI 캐싱 가이드는 GPT-6.2에 대해 다음 규칙을 정하고 있습니다.
| 규칙 | 값 |
|---|---|
| 캐시 읽기 가격 | 입력의 0.05× (PoYo 기준 100만당 Sol $0.08, Astra $0.32) |
| 캐시 쓰기 가격 | 기본 30분 보존 시 입력의 1.25× (PoYo 기준 100만당 $2 / $8) |
| 최소 캐시 가능 프리픽스 | 보이는 입력 토큰 1,024개 |
| 암시적 브레이크포인트 | 조건을 충족하는 최신 메시지의 끝 |
| usage 필드 | usage.input_tokens_details.cached_tokens(읽기), cache_write_tokens(쓰기) |
캐시 히트 가능성을 높이려면:
- 고정된 내용을 앞에 두세요. developer 메시지, 도구 정의, 저장소 스냅샷, 작업 순서로 둡니다.
- 최상위
instructions대신developer메시지를 쓰세요. GPT-6.2는instructions를input뒤에 덧붙이므로 프리픽스 밖에 놓이게 됩니다. - 이전 항목은 절대 편집하지 마세요. 도구 출력은 덧붙이고, 기록은 다시 쓰지 마세요.
- 세션 안에서는 설정을 고정하세요. OpenAI 가이드는 응답 사이에 설정을 바꿀 때도 프리픽스는 그대로 유지하라고 안내합니다.
OpenAI는 prompt_cache_options(명시적 브레이크포인트와 12시간 보존)도 문서화하고 있습니다. PoYo의 Responses 스키마에는 이 필드가 없고 추가 필드를 받지 않는다고(additionalProperties: false) 선언되어 있으므로, 이 필드는 빼고 암시적 캐싱에 맡기세요. Sol에서 최선의 경우 25턴 세션은 캐시 없는 $3.82에서 약 $0.74로 줄어듭니다. 계산 과정은 GPT-6.2 API 가격에 있습니다.
Astra에 실행을 넘길 때
모든 실행은 gpt-6.2-sol로 시작하세요. 테스트가 실패한 채 턴 상한에서 멈추면, 새 항목 목록으로 gpt-6.2-astra에서 작업을 다시 시작합니다. OpenAI에 따르면 모델 변경으로 추론 항목이 버려질 수 있으므로, 같은 대화 안에서 모델을 바꾸지 마세요. 라우팅 계산과 라우터는 GPT-6.2 Sol API vs GPT-6.2 Astra API에 있습니다. 다른 벤더로 같은 루프를 구성한 사례는 코딩 에이전트를 위한 Gemini 4 Carbon API와 비교해 보세요.
자주 묻는 질문
GPT-6.2 API는 함수 호출을 지원하나요?
예, /v1/responses에서 지원합니다. type: "function"으로 도구를 정의하고, output에서 function_call 항목을 읽은 뒤, 결과를 같은 call_id를 가진 function_call_output 항목으로 돌려보내세요.
GPT-6.2 API 도구를 Chat Completions에서 쓸 수 있나요?
아니요. OpenAI에 따르면 GPT-6.2는 Chat Completions를 지원하지만, 도구 호출에는 Responses가 필요합니다.
GPT-6.2 API 에이전트 턴은 어떻게 스트리밍하나요?
Responses에서 stream: true를 설정하고, response.output_text.delta 이벤트를 출력한 뒤, 도구 호출과 usage는 response.completed 이벤트에서 읽으세요.
긴 에이전트 세션에서 GPT-6.2 API 비용을 어떻게 줄이나요?
고정 프리픽스(developer 메시지, 도구, 스냅샷)를 앞에 두고, 편집 대신 덧붙이고, 도구 출력을 줄이고, 가능하면 요청당 입력을 272K 토큰 미만으로 유지하세요.
코딩 에이전트에는 어떤 GPT-6.2 모델을 써야 하나요?
토큰당 비용이 Astra의 4분의 1인 gpt-6.2-sol로 시작하고, 실패한 실행은 gpt-6.2-astra에서 다시 시작하세요.