
A GPT-6.2 API é a escolha atual da OpenAI para trabalho com agentes: o changelog da API recomenda gpt-6.2-sol "para a programação do dia a dia e fluxos de trabalho de agentes" e gpt-6.2-astra para "tarefas exigentes de raciocínio e programação." Este guia liga qualquer um dos modelos a um agente de programação através do endpoint Responses do PoYo, com ferramentas de funções, um ciclo limitado, progresso em streaming, um contexto de repositório grande e caching que mantém as sessões longas comportáveis. Começa na página do modelo GPT-6.2 Sol e guarda o GPT-6.2 Astra para a escalada.
Se ainda não enviaste um primeiro pedido, começa pelo guia da GPT-6.2 API.
O que a API dá a um agente de programação
| Item | GPT-6.2 no PoYo |
|---|---|
| IDs de modelo | gpt-6.2-sol (predefinido), gpt-6.2-astra (escalada) |
| Endpoint para agentes | POST https://api.poyo.ai/v1/responses (OpenAI SDK, base_url="https://api.poyo.ai/v1") |
| Chamadas de ferramentas | Só Responses; OpenAI: "as chamadas de ferramentas exigem 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, começa em medium |
| Preço por 1M (Sol) | $1.60 de entrada / $8 de saída / $0.08 de leitura de cache / $2 de escrita na cache |
| Preço por 1M (Astra) | $6.40 de entrada / $32 de saída / $0.32 de leitura de cache / $8 de escrita na cache |
| Erros | 400 campos inválidos, 401 chave errada, 402 créditos insuficientes, 404 modelo desconhecido; repete 429 / 5xx com backoff |
A referência de Responses do PoYo documenta tools, tool_choice, parallel_tool_calls, reasoning, include, store, previous_response_id e truncation, e diz que o suporte de ferramentas depende do modelo. As páginas de modelo da OpenAI listam chamadas de funções e um conjunto de ferramentas alojadas para o GPT-6.2. A documentação do PoYo mostra apenas web_search_preview como exemplo de ferramenta alojada, por isso este agente usa as tuas próprias ferramentas de funções, que controlas de ponta a ponta.
Definir as ferramentas de funções
Mantém o conjunto de ferramentas pequeno e seguro. O modelo só pode pedir as ações que implementares:
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}"
Executa o agente num checkout ou contentor descartável, nunca na tua árvore de trabalho.
Um ciclo de agente limitado
O ciclo envia a conversa, executa cada item function_call, acrescenta um function_call_output com o mesmo call_id e repete até o modelo responder sem chamar nenhuma ferramenta. Para ao atingir um limite de turnos e 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")
Porque é que o ciclo está construído assim:
- Os itens de saída voltam por ordem, incluindo os itens de raciocínio. Nos pedidos em que
storeé false, como em Zero Data Retention, o guia do GPT-6.2 da OpenAI diz para "devolver os itens de saída anteriores por ordem, incluindo os itens de raciocínio encriptados."include=["reasoning.encrypted_content"]pede-os. A alternativa éprevious_response_idcom respostas armazenadas, que o PoYo também documenta. - O histórico só cresce no fim. A OpenAI avisa que as edições a meio da conversa podem fazer a API Responses descartar itens de raciocínio, o que "pode reduzir a qualidade da resposta e aumentar o uso de tokens", e uma edição também parte o prefixo em cache.
- O orçamento é verificado em cada turno, com a mesma tabela de preços da fatura.
Não executámos este ciclo exato de ponta a ponta no PoYo para este artigo. Corre-o primeiro numa tarefa pequena e confirma que as chamadas de ferramentas e o usage são os esperados.
Mostrar o progresso ao utilizador em streaming
Os turnos longos de um agente parecem lentos sem feedback. Faz streaming de cada turno, mostra os deltas de texto e obtém a saída final de response.completed. Estes são os tipos de evento que o 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
Usa stream_turn no ciclo em vez 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 pedido. Um agente pode carregar logo à partida uma grande parte de um repositório em vez de ler os ficheiros um a um. Há três limites que condicionam essa escolha:
- Cada turno reenvia o histórico. Um snapshot de 200K tokens ao longo de 20 turnos são pelo menos 4M de tokens de entrada. Aos $1.60 do Sol, isso dá $6.40 sem cache. Com uma escrita na 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 duplica as tarifas de entrada e de cache e cobra 1.5× a saída para todo o pedido a partir dessa linha. Mantém os pedidos do agente abaixo de 272K, a menos que a tarefa precise de mais, e consulta a página do modelo para veres a tarifa do PoYo que se aplica.
- O raciocínio partilha o orçamento de saída.
max_output_tokenslimita o texto visível mais o raciocínio. Pede um ficheiro por cada chamada awrite_fileem vez de reescrever o repositório inteiro.
Corta o output das ferramentas antes de o acrescentar: devolve as últimas 200 linhas de uma execução de testes, não 20,000. Assim o crescimento por turno, e a fatura, mantêm-se lineares e pequenos.
Caching de prompts em sessões de agentes
O guia de caching da OpenAI define estas regras para o GPT-6.2:
| Regra | Valor |
|---|---|
| Preço de leitura de cache | 0.05× a entrada ($0.08 por 1M no Sol, $0.32 no Astra, no PoYo) |
| Preço de escrita na cache | 1.25× a entrada para a retenção predefinida de 30 minutos ($2 / $8 por 1M no PoYo) |
| Prefixo mínimo para cache | 1,024 tokens de entrada visíveis |
| Breakpoint implícito | Fim da última mensagem elegível |
| Campos de uso | usage.input_tokens_details.cached_tokens (leituras), cache_write_tokens (escritas) |
Para tornar os acertos na cache prováveis:
- Coloca primeiro o conteúdo estável. A mensagem developer, depois as definições de ferramentas, depois o snapshot do repositório e, por fim, a tarefa.
- Usa uma mensagem
developer, nãoinstructionsde nível superior. O GPT-6.2 acrescenta asinstructionsdepois deinput, por isso ficariam fora do prefixo. - Nunca edites itens anteriores. Acrescenta os outputs das ferramentas; não reescrevas o histórico.
- Mantém as definições estáveis dentro de uma sessão. O guia da OpenAI diz para manter o prefixo inalterado quando mudas definições entre respostas.
A OpenAI também documenta prompt_cache_options (breakpoints explícitos e uma retenção de 12 horas). O esquema de Responses do PoYo não lista esse campo e está declarado como fechado a campos extra (additionalProperties: false), por isso deixa-o de fora e confia no caching implícito. Uma sessão de 25 turnos no Sol, no melhor caso, desce de $3.82 sem cache para cerca de $0.74; as contas estão em preços da GPT-6.2 API.
Quando passar a execução para o Astra
Começa todas as execuções em gpt-6.2-sol. Se parar no limite de turnos com testes a falhar, reinicia a tarefa em gpt-6.2-astra com uma lista de itens nova. Não mudes de modelo dentro da mesma conversa, porque a OpenAI diz que as mudanças de modelo podem descartar itens de raciocínio. As contas do encaminhamento e um router estão em GPT-6.2 Sol API vs GPT-6.2 Astra API. Para ver a abordagem de outro fornecedor ao mesmo ciclo, compara com Gemini 4 Carbon API para agentes de programação.
Perguntas frequentes
A GPT-6.2 API suporta chamadas de funções?
Sim, em /v1/responses. Define as ferramentas com type: "function", lê os itens function_call de output e devolve os resultados como itens function_call_output com o mesmo call_id.
Posso usar ferramentas da GPT-6.2 API com o Chat Completions?
Não. A OpenAI diz que o GPT-6.2 suporta Chat Completions, mas as chamadas de ferramentas exigem Responses.
Como faço streaming de um turno de agente na GPT-6.2 API?
Define stream: true no Responses, imprime os eventos response.output_text.delta e lê 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 agentes?
Mantém um prefixo estável (mensagem developer, ferramentas, snapshot) no início, acrescenta em vez de editar, corta o output das ferramentas e fica abaixo de 272K tokens de entrada por pedido sempre que possível.
Que modelo GPT-6.2 deve correr o meu agente de programação?
Começa com gpt-6.2-sol, que custa um quarto do Astra por token, e reinicia em gpt-6.2-astra as execuções que falharem.