how-tos

GPT-6.2 API para agentes de programação: function tools, streaming, contexto longo e cache

Poyo.ai Team
10 min read
Share:

GPT-6.2 API alimentando o loop 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 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

ItemGPT-6.2 na PoYo
IDs dos modelosgpt-6.2-sol (padrão), gpt-6.2-astra (escalonamento)
Endpoint do agentePOST https://api.poyo.ai/v1/responses (OpenAI SDK, base_url="https://api.poyo.ai/v1")
Chamada de ferramentasSomente Responses; OpenAI: "a chamada de ferramentas exige 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, 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
Erros400 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_id com 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_tokens limita o texto visível mais o raciocínio. Peça um arquivo por chamada write_file em 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:

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

Para aumentar as chances de acerto no cache:

  1. 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.
  2. Use uma mensagem developer, não instructions de nível superior. O GPT-6.2 anexa as instructions depois do input, então elas ficariam fora do prefixo.
  3. Nunca edite itens anteriores. Anexe as saídas das ferramentas; não reescreva o histórico.
  4. 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.

Share: