how-tos

GPT-6.2 API per agenti di coding: function tool, streaming, contesto lungo e caching

Poyo.ai Team
10 min read
Share:

La GPT-6.2 API alla guida di un loop di agente di coding

La GPT-6.2 API è la scelta attuale di OpenAI per il lavoro degli agenti: il changelog dell'API consiglia gpt-6.2-sol "per il coding e i flussi di lavoro agentici di tutti i giorni" e gpt-6.2-astra per "task impegnativi di ragionamento e coding". Questa guida collega uno dei due modelli a un agente di coding tramite l'endpoint Responses di PoYo, con function tool, un loop limitato, avanzamento in streaming, un ampio contesto di repository e un caching che rende sostenibili le sessioni lunghe. Parti dalla pagina del modello GPT-6.2 Sol e tieni GPT-6.2 Astra per l'escalation.

Se non hai ancora inviato una prima richiesta, parti dalla guida alla GPT-6.2 API.

Cosa offre l'API a un agente di coding

VoceGPT-6.2 su PoYo
ID modellogpt-6.2-sol (predefinito), gpt-6.2-astra (escalation)
Endpoint per l'agentePOST https://api.poyo.ai/v1/responses (SDK di OpenAI, base_url="https://api.poyo.ai/v1")
Tool callingSolo Responses; OpenAI: "il tool calling richiede Responses"
Contesto / input massimo / output massimo1,050,000 / 922,000 / 128,000 token
Streaming"stream": true; response.completed contiene l'output finale e usage
Ragionamentoreasoning.effort; none rifiutato, partire da medium
Prezzo per 1M (Sol)$1.60 di input / $8 di output / $0.08 di lettura dalla cache / $2 di scrittura in cache
Prezzo per 1M (Astra)$6.40 di input / $32 di output / $0.32 di lettura dalla cache / $8 di scrittura in cache
Errori400 campi non validi, 401 chiave errata, 402 crediti insufficienti, 404 modello sconosciuto; riprova 429 / 5xx con backoff

Il riferimento Responses di PoYo documenta tools, tool_choice, parallel_tool_calls, reasoning, include, store, previous_response_id e truncation, e precisa che il supporto ai tool dipende dal modello. Le pagine dei modelli di OpenAI elencano per GPT-6.2 il function calling e una serie di tool ospitati. La documentazione di PoYo mostra solo web_search_preview come esempio di tool ospitato, quindi questo agente usa i tuoi function tool, che controlli dall'inizio alla fine.

Definire i function tool

Mantieni il set di tool piccolo e sicuro. Il modello può richiedere solo le azioni che implementi:

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}"

Esegui l'agente su un checkout o un container usa e getta, mai sulla tua working tree.

Un loop di agente limitato

Il loop invia la conversazione, esegue ogni elemento function_call, aggiunge un function_call_output con lo stesso call_id e ripete finché il modello non risponde senza chiamare tool. Si ferma al raggiungimento di un limite di turni e di un budget in dollari.

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")

Perché il loop è costruito così:

  • Gli elementi di output tornano indietro in ordine, compresi gli elementi di ragionamento. Per le richieste in cui store è false, come con la Zero Data Retention, la guida GPT-6.2 di OpenAI dice di "restituire gli elementi di output precedenti in ordine, compresi gli elementi di ragionamento cifrati". include=["reasoning.encrypted_content"] li richiede. L'alternativa è previous_response_id con risposte memorizzate, che PoYo documenta anch'essa.
  • La cronologia è solo in aggiunta. OpenAI avverte che le modifiche a metà conversazione possono far scartare alla Responses API gli elementi di ragionamento, il che "può ridurre la qualità delle risposte e aumentare l'uso di token", e una modifica rompe anche il prefisso in cache.
  • Il budget viene controllato a ogni turno, con la stessa tabella prezzi della fattura.

Non abbiamo eseguito questo loop esatto end-to-end su PoYo per questo articolo. Provalo prima su un task piccolo e verifica che le chiamate ai tool e usage siano come previsto.

Mostrare l'avanzamento all'utente in streaming

I turni lunghi di un agente sembrano lenti senza feedback. Esegui ogni turno in streaming, mostra i delta di testo e prendi l'output finale da response.completed. Questi sono i tipi di evento documentati da 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

Inserisci stream_turn nel loop al posto di responses.create. Le chiamate ai tool si leggono da final.output esattamente come prima.

Contesto lungo: 922K in input, 128K in output

GPT-6.2 accetta fino a 922,000 token di input per richiesta. Un agente può caricare subito gran parte di un repository invece di leggere i file uno alla volta. Tre limiti condizionano questa scelta:

  • Ogni turno reinvia la cronologia. Uno snapshot da 200K token su 20 turni equivale ad almeno 4M token di input. Ai $1.60 di Sol fanno $6.40 senza cache. Con una scrittura in cache dello snapshot ($0.40) e 19 letture dalla cache a $0.08 ($0.30), si arriva a circa $0.70.
  • Il livello per contesto lungo di OpenAI parte oltre i 272K token di input. La pagina dei prezzi di OpenAI raddoppia le tariffe di input e cache e applica 1.5× all'output per l'intera richiesta oltre quella soglia. Tieni le richieste dell'agente sotto i 272K a meno che il task non richieda di più, e controlla nella pagina del modello la tariffa PoYo applicabile.
  • Il ragionamento condivide il budget di output. max_output_tokens limita il testo visibile più il ragionamento. Chiedi un file per ogni chiamata a write_file invece di una riscrittura dell'intero repository.

Riduci l'output dei tool prima di aggiungerlo: restituisci le ultime 200 righe di un'esecuzione dei test, non 20,000. Così la crescita per turno, e la fattura, restano lineari e contenute.

Prompt caching per le sessioni degli agenti

La guida al caching di OpenAI fissa queste regole per GPT-6.2:

RegolaValore
Prezzo di lettura dalla cache0.05× l'input ($0.08 per 1M su Sol, $0.32 su Astra, su PoYo)
Prezzo di scrittura in cache1.25× l'input per la retention predefinita di 30 minuti ($2 / $8 per 1M su PoYo)
Prefisso minimo memorizzabile in cache1,024 token di input visibili
Breakpoint implicitoFine dell'ultimo messaggio idoneo
Campi di usageusage.input_tokens_details.cached_tokens (letture), cache_write_tokens (scritture)

Per rendere probabili i cache hit:

  1. Metti prima i contenuti stabili. Messaggio developer, poi definizioni dei tool, poi snapshot del repository, poi il task.
  2. Usa un messaggio developer, non le instructions di primo livello. GPT-6.2 accoda le instructions dopo input, quindi finirebbero fuori dal prefisso.
  3. Non modificare mai gli elementi precedenti. Aggiungi gli output dei tool; non riscrivere la cronologia.
  4. Mantieni stabili le impostazioni all'interno di una sessione. La guida di OpenAI dice di mantenere invariato il prefisso quando cambi le impostazioni tra una risposta e l'altra.

OpenAI documenta anche prompt_cache_options (breakpoint espliciti e retention di 12 ore). Lo schema Responses di PoYo non elenca quel campo ed è dichiarato chiuso ai campi aggiuntivi (additionalProperties: false), quindi omettilo e affidati al caching implicito. Nel caso migliore, una sessione da 25 turni su Sol scende da $3.82 senza cache a circa $0.74; il calcolo è in Prezzi della GPT-6.2 API.

Quando passare l'esecuzione ad Astra

Avvia ogni esecuzione su gpt-6.2-sol. Se si ferma al limite di turni con test che falliscono, riavvia il task su gpt-6.2-astra con una nuova lista di elementi. Non cambiare modello all'interno della stessa conversazione, perché OpenAI dice che i cambi di modello possono scartare gli elementi di ragionamento. Il calcolo dell'instradamento e un router sono in GPT-6.2 Sol API vs GPT-6.2 Astra API. Per lo stesso loop con un altro fornitore, confronta con Gemini 4 Carbon API per agenti di coding.

Domande frequenti

La GPT-6.2 API supporta il function calling?

Sì, su /v1/responses. Definisci i tool con type: "function", leggi gli elementi function_call da output e rimanda i risultati come elementi function_call_output con lo stesso call_id.

Posso usare i tool della GPT-6.2 API con Chat Completions?

No. OpenAI dice che GPT-6.2 supporta Chat Completions, ma il tool calling richiede Responses.

Come faccio lo streaming di un turno di agente con la GPT-6.2 API?

Imposta stream: true su Responses, stampa gli eventi response.output_text.delta e leggi le chiamate ai tool e usage dall'evento response.completed.

Come riduco i costi della GPT-6.2 API nelle sessioni lunghe degli agenti?

Mantieni un prefisso stabile (messaggio developer, tool, snapshot) all'inizio, aggiungi invece di modificare, riduci l'output dei tool e resta sotto i 272K token di input per richiesta quando possibile.

Quale modello GPT-6.2 dovrebbe far girare il mio agente di coding?

Parti da gpt-6.2-sol, che per token costa un quarto di Astra, e riavvia su gpt-6.2-astra un'esecuzione non riuscita.

Share: