
A GPT-6.2 API é a escolha atual da OpenAI para trabalho com agentes: o changelog da API recomenda o gpt-6.2-sol "para programação e fluxos de agentes do dia a dia" e o gpt-6.2-astra para "tarefas exigentes de raciocínio e programação". Este guia conecta qualquer um dos dois modelos a um agente de programação pelo endpoint Responses da PoYo, com function tools, um loop limitado, progresso em streaming, um contexto grande de repositório e um cache que mantém sessões longas acessíveis. Comece pela página do modelo GPT-6.2 Sol e deixe o GPT-6.2 Astra para o escalonamento.
Se você ainda não enviou uma primeira requisição, comece pelo guia da GPT-6.2 API.
O que a API oferece a um agente de programação
| Item | GPT-6.2 na PoYo |
|---|---|
| IDs dos modelos | gpt-6.2-sol (padrão), gpt-6.2-astra (escalonamento) |
| Endpoint do agente | POST https://api.poyo.ai/v1/responses (OpenAI SDK, base_url="https://api.poyo.ai/v1") |
| Chamada de ferramentas | Somente Responses; OpenAI: "a chamada de ferramentas exige Responses" |
| Contexto / entrada máxima / saída máxima | 1,050,000 / 922,000 / 128,000 tokens |
| Streaming | "stream": true; response.completed traz a saída final e o usage |
| Raciocínio | reasoning.effort; none rejeitado, comece em medium |
| Preço por 1M (Sol) | $1.60 entrada / $8 saída / $0.08 leitura de cache / $2 escrita de cache |
| Preço por 1M (Astra) | $6.40 entrada / $32 saída / $0.32 leitura de cache / $8 escrita de cache |
| Erros | 400 campos inválidos, 401 chave inválida, 402 créditos insuficientes, 404 modelo desconhecido; repita 429 / 5xx com backoff |
A referência de Responses da PoYo documenta tools, tool_choice, parallel_tool_calls, reasoning, include, store, previous_response_id e truncation, e diz que o suporte a ferramentas depende do modelo. As páginas de modelo da OpenAI listam function calling e um conjunto de ferramentas hospedadas para o GPT-6.2. A documentação da PoYo mostra apenas web_search_preview como exemplo de ferramenta hospedada, então este agente usa as suas próprias function tools, que você controla de ponta a ponta.
Definir as function tools
Mantenha o conjunto de ferramentas pequeno e seguro. O modelo só pode pedir ações que você implementa:
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}"
Rode o agente em um checkout ou contêiner descartável, nunca na sua árvore de trabalho.
Um loop de agente limitado
O loop envia a conversa, executa cada item function_call, anexa um function_call_output com o mesmo call_id e repete até o modelo responder sem chamar ferramentas. Ele para em um limite de turnos e em um orçamento em dólares.
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")
Por que o loop é construído assim:
- Os itens de saída voltam em ordem, incluindo os itens de raciocínio. Para requisições em que
storeé false, como sob Zero Data Retention, o guia do GPT-6.2 da OpenAI diz para "devolver os itens de saída anteriores em ordem, incluindo os itens de raciocínio criptografados".include=["reasoning.encrypted_content"]pede esses itens. A alternativa éprevious_response_idcom respostas armazenadas, que a PoYo também documenta. - O histórico só recebe acréscimos. A OpenAI avisa que edições no meio da conversa podem fazer a Responses API descartar itens de raciocínio, o que "pode reduzir a qualidade das respostas e aumentar o uso de tokens", e uma edição também quebra o prefixo em cache.
- O orçamento é verificado a cada turno, usando a mesma tabela de preços da cobrança.
Não rodamos exatamente este loop de ponta a ponta na PoYo para este post. Rode-o primeiro em uma tarefa pequena e confirme que as chamadas de ferramentas e o usage estão como o esperado.
Progresso em streaming para o usuário
Turnos longos de agente parecem lentos sem feedback. Faça streaming de cada turno, mostre os deltas de texto e pegue a saída final de response.completed. Estes são os tipos de evento que a PoYo documenta:
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
Use stream_turn no loop no lugar de responses.create. As chamadas de ferramentas são lidas de final.output exatamente como antes.
Contexto longo: 922K de entrada, 128K de saída
O GPT-6.2 aceita até 922,000 tokens de entrada por requisição. Um agente pode carregar uma grande parte de um repositório logo de início, em vez de ler os arquivos um a um. Três limites pesam nessa escolha:
- Todo turno reenvia o histórico. Um snapshot de 200K tokens ao longo de 20 turnos soma pelo menos 4M de tokens de entrada. A $1.60 do Sol, isso dá $6.40 sem cache. Com uma escrita de cache do snapshot ($0.40) e 19 leituras de cache a $0.08 ($0.30), fica em cerca de $0.70.
- O nível de contexto longo da OpenAI começa acima de 272K tokens de entrada. A página de preços da OpenAI dobra as tarifas de entrada e de cache e cobra 1.5× a saída para a requisição inteira depois dessa linha. Mantenha as requisições do agente abaixo de 272K, a menos que a tarefa precise de mais, e confira na página do modelo a tarifa da PoYo que se aplica.
- O raciocínio divide o orçamento de saída.
max_output_tokenslimita o texto visível mais o raciocínio. Peça um arquivo por chamadawrite_fileem vez de uma reescrita do repositório inteiro.
Corte a saída das ferramentas antes de anexá-la: devolva as últimas 200 linhas de uma execução de testes, não 20,000. Isso mantém o crescimento por turno, e a conta, linear e pequeno.
Cache de prompt para sessões de agente
O guia de cache da OpenAI define estas regras para o GPT-6.2:
| Regra | Valor |
|---|---|
| Preço da leitura de cache | 0.05× a entrada ($0.08 por 1M no Sol, $0.32 no Astra, na PoYo) |
| Preço da escrita de cache | 1.25× a entrada com a retenção padrão de 30 minutos ($2 / $8 por 1M na PoYo) |
| Prefixo mínimo para cache | 1,024 tokens de entrada visíveis |
| Breakpoint implícito | Fim da última mensagem elegível |
| Campos de usage | usage.input_tokens_details.cached_tokens (leituras), cache_write_tokens (escritas) |
Para aumentar as chances de acerto no cache:
- Coloque o conteúdo estável primeiro. Mensagem developer, depois as definições de ferramentas, depois o snapshot do repositório e, por fim, a tarefa.
- Use uma mensagem
developer, nãoinstructionsde nível superior. O GPT-6.2 anexa asinstructionsdepois doinput, então elas ficariam fora do prefixo. - Nunca edite itens anteriores. Anexe as saídas das ferramentas; não reescreva o histórico.
- Mantenha as configurações estáveis dentro de uma sessão. O guia da OpenAI diz para manter o prefixo inalterado quando você muda configurações entre respostas.
A OpenAI também documenta prompt_cache_options (breakpoints explícitos e retenção de 12 horas). O schema de Responses da PoYo não lista esse campo e é declarado fechado para campos extras (additionalProperties: false), então deixe-o de fora e conte com o cache implícito. Uma sessão de 25 turnos no melhor caso no Sol cai de $3.82 sem cache para cerca de $0.74; a conta está em Preço da GPT-6.2 API.
Quando passar a execução para o Astra
Comece toda execução no gpt-6.2-sol. Se ela parar no limite de turnos com testes falhando, reinicie a tarefa no gpt-6.2-astra com uma lista de itens nova. Não troque o modelo dentro da mesma conversa, porque a OpenAI diz que trocas de modelo podem descartar itens de raciocínio. A conta do roteamento e um roteador estão em GPT-6.2 Sol API vs GPT-6.2 Astra API. Para ver como outro fornecedor lida com o mesmo loop, compare com Gemini 4 Carbon API para agentes de programação.
Perguntas frequentes
A GPT-6.2 API suporta function calling?
Sim, em /v1/responses. Defina as ferramentas com type: "function", leia os itens function_call de output e devolva os resultados como itens function_call_output com o mesmo call_id.
Posso usar ferramentas da GPT-6.2 API com Chat Completions?
Não. A OpenAI diz que o GPT-6.2 suporta Chat Completions, mas a chamada de ferramentas exige Responses.
Como faço streaming de um turno de agente na GPT-6.2 API?
Defina stream: true no Responses, imprima os eventos response.output_text.delta e leia as chamadas de ferramentas e o usage do evento response.completed.
Como reduzo os custos da GPT-6.2 API em sessões longas de agente?
Mantenha um prefixo estável (mensagem developer, ferramentas, snapshot) no início, acrescente em vez de editar, corte a saída das ferramentas e fique abaixo de 272K tokens de entrada por requisição quando puder.
Qual modelo GPT-6.2 deve rodar o meu agente de programação?
Comece com o gpt-6.2-sol, que custa um quarto do Astra por token, e reinicie uma execução que falhou no gpt-6.2-astra.