how-tos

GPT-6.2 API para agentes de programação: ferramentas de funções, streaming, contexto longo e caching

Poyo.ai Team
10 min read
Share:

GPT-6.2 API a alimentar o ciclo de um agente de programação

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

ItemGPT-6.2 no PoYo
IDs de modelogpt-6.2-sol (predefinido), gpt-6.2-astra (escalada)
Endpoint para agentesPOST https://api.poyo.ai/v1/responses (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Chamadas de ferramentasSó Responses; OpenAI: "as chamadas de ferramentas exigem Responses"
Contexto / entrada máxima / saída máxima1,050,000 / 922,000 / 128,000 tokens
Streaming"stream": true; response.completed traz a saída final e o usage
Raciocínioreasoning.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
Erros400 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_id com 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_tokens limita o texto visível mais o raciocínio. Pede um ficheiro por cada chamada a write_file em 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:

RegraValor
Preço de leitura de cache0.05× a entrada ($0.08 por 1M no Sol, $0.32 no Astra, no PoYo)
Preço de escrita na cache1.25× a entrada para a retenção predefinida de 30 minutos ($2 / $8 por 1M no PoYo)
Prefixo mínimo para cache1,024 tokens de entrada visíveis
Breakpoint implícitoFim da última mensagem elegível
Campos de usousage.input_tokens_details.cached_tokens (leituras), cache_write_tokens (escritas)

Para tornar os acertos na cache prováveis:

  1. 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.
  2. Usa uma mensagem developer, não instructions de nível superior. O GPT-6.2 acrescenta as instructions depois de input, por isso ficariam fora do prefixo.
  3. Nunca edites itens anteriores. Acrescenta os outputs das ferramentas; não reescrevas o histórico.
  4. 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.

Share: