how-tos

GPT-6.2 API para agentes de programación: herramientas de funciones, streaming, contexto largo y caché

Poyo.ai Team
10 min read
Share:

GPT-6.2 API impulsando el bucle de un agente de programación

La GPT-6.2 API es la opción actual de OpenAI para el trabajo con agentes: el changelog de la API recomienda gpt-6.2-sol «para la programación diaria y los flujos de trabajo de agentes» y gpt-6.2-astra para «tareas exigentes de razonamiento y programación». Esta guía conecta cualquiera de los dos modelos a un agente de programación a través del endpoint Responses de PoYo, con herramientas de funciones, un bucle acotado, progreso en streaming, un contexto de repositorio grande y una caché que mantiene asequibles las sesiones largas. Empieza en la página del modelo GPT-6.2 Sol y reserva GPT-6.2 Astra para escalar.

Si todavía no has enviado una primera solicitud, empieza por la guía de la GPT-6.2 API.

Qué ofrece la API a un agente de programación

ElementoGPT-6.2 en PoYo
IDs de modelogpt-6.2-sol (por defecto), gpt-6.2-astra (escalado)
Endpoint para agentesPOST https://api.poyo.ai/v1/responses (SDK de OpenAI, base_url="https://api.poyo.ai/v1")
Llamadas a herramientasSolo Responses; OpenAI: «las llamadas a herramientas requieren Responses»
Contexto / entrada máxima / salida máxima1,050,000 / 922,000 / 128,000 tokens
Streaming"stream": true; response.completed lleva la salida final y usage
Razonamientoreasoning.effort; none se rechaza, empieza con medium
Precio por 1M (Sol)$1.60 de entrada / $8 de salida / $0.08 de lectura de caché / $2 de escritura en caché
Precio por 1M (Astra)$6.40 de entrada / $32 de salida / $0.32 de lectura de caché / $8 de escritura en caché
Errores400 campos no válidos, 401 clave incorrecta, 402 créditos insuficientes, 404 modelo desconocido; reintenta 429 / 5xx con backoff

La referencia de Responses de PoYo documenta tools, tool_choice, parallel_tool_calls, reasoning, include, store, previous_response_id y truncation, e indica que la compatibilidad con herramientas depende del modelo. Las páginas de modelo de OpenAI incluyen llamadas a funciones y un conjunto de herramientas alojadas para GPT-6.2. La documentación de PoYo solo muestra web_search_preview como ejemplo de herramienta alojada, así que este agente usa tus propias herramientas de funciones, que controlas de principio a fin.

Definir las herramientas de funciones

Mantén el conjunto de herramientas pequeño y seguro. El modelo solo puede solicitar las acciones que tú implementes:

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

Ejecuta el agente sobre un checkout o un contenedor desechable, nunca sobre tu árbol de trabajo.

Un bucle de agente acotado

El bucle envía la conversación, ejecuta cada elemento function_call, añade un function_call_output con el mismo call_id y repite hasta que el modelo responde sin llamar a ninguna herramienta. Se detiene al llegar a un límite de turnos y a un presupuesto en 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 qué el bucle está construido así:

  • Los elementos de salida se devuelven en orden, incluidos los de razonamiento. En las solicitudes en las que store es false, como con Zero Data Retention, la guía de GPT-6.2 de OpenAI indica que hay que «devolver los elementos de salida anteriores en orden, incluidos los elementos de razonamiento cifrados». include=["reasoning.encrypted_content"] los solicita. La alternativa es previous_response_id con respuestas almacenadas, que PoYo también documenta.
  • El historial solo crece por el final. OpenAI advierte de que las ediciones a mitad de conversación pueden hacer que la API Responses descarte elementos de razonamiento, lo que «puede reducir la calidad de la respuesta y aumentar el uso de tokens», y además una edición rompe el prefijo en caché.
  • El presupuesto se comprueba en cada turno, con la misma tabla de precios que la factura.

No hemos ejecutado este bucle exacto de principio a fin en PoYo para este artículo. Pruébalo primero con una tarea pequeña y confirma que las llamadas a herramientas y usage son las esperadas.

Mostrar el progreso al usuario en streaming

Los turnos largos de un agente parecen lentos si no hay respuesta visible. Haz streaming de cada turno, muestra los deltas de texto y toma la salida final de response.completed. Estos son los tipos de evento que documenta 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

Sustituye responses.create por stream_turn dentro del bucle. Las llamadas a herramientas se leen de final.output exactamente igual que antes.

Contexto largo: 922K de entrada, 128K de salida

GPT-6.2 acepta hasta 922,000 tokens de entrada por solicitud. Un agente puede cargar de entrada una gran parte de un repositorio en lugar de leer los archivos uno a uno. Tres límites condicionan esa decisión:

  • Cada turno vuelve a enviar el historial. Una instantánea de 200K tokens a lo largo de 20 turnos supone al menos 4M de tokens de entrada. A los $1.60 de Sol, eso son $6.40 sin caché. Con una escritura en caché de la instantánea ($0.40) y 19 lecturas de caché a $0.08 ($0.30), son unos $0.70.
  • El nivel de contexto largo de OpenAI empieza por encima de 272K tokens de entrada. La página de precios de OpenAI duplica las tarifas de entrada y de caché y cobra 1.5× la salida para toda la solicitud a partir de ese umbral. Mantén las solicitudes del agente por debajo de 272K salvo que la tarea necesite más, y consulta la página del modelo para ver la tarifa de PoYo aplicable.
  • El razonamiento comparte el presupuesto de salida. max_output_tokens limita el texto visible más el razonamiento. Pide un archivo por cada llamada a write_file en lugar de reescribir todo el repositorio.

Recorta la salida de las herramientas antes de añadirla: devuelve las últimas 200 líneas de una ejecución de tests, no 20,000. Así el crecimiento por turno, y la factura, se mantienen lineales y pequeños.

Caché de prompts en sesiones de agentes

La guía de caché de OpenAI fija estas reglas para GPT-6.2:

ReglaValor
Precio de lectura de caché0.05× la entrada ($0.08 por 1M en Sol, $0.32 en Astra, en PoYo)
Precio de escritura en caché1.25× la entrada para la retención por defecto de 30 minutos ($2 / $8 por 1M en PoYo)
Prefijo mínimo cacheable1,024 tokens de entrada visibles
Punto de corte implícitoFinal del último mensaje apto
Campos de usousage.input_tokens_details.cached_tokens (lecturas), cache_write_tokens (escrituras)

Para que los aciertos de caché sean probables:

  1. Pon primero el contenido estable. El mensaje developer, después las definiciones de herramientas, después la instantánea del repositorio y, por último, la tarea.
  2. Usa un mensaje developer, no instructions de nivel superior. GPT-6.2 añade instructions después de input, así que quedarían fuera del prefijo.
  3. No edites nunca elementos anteriores. Añade las salidas de las herramientas; no reescribas el historial.
  4. Mantén estables los ajustes dentro de una sesión. La guía de OpenAI indica que se mantenga el prefijo sin cambios cuando cambies ajustes entre respuestas.

OpenAI también documenta prompt_cache_options (puntos de corte explícitos y una retención de 12 horas). El esquema de Responses de PoYo no incluye ese campo y está declarado como cerrado a campos adicionales (additionalProperties: false), así que no lo envíes y confía en la caché implícita. Una sesión de 25 turnos en Sol, en el mejor caso, baja de $3.82 sin caché a unos $0.74; el cálculo está en precios de la GPT-6.2 API.

Cuándo pasar la ejecución a Astra

Empieza cada ejecución en gpt-6.2-sol. Si se detiene en el límite de turnos con tests que fallan, reinicia la tarea en gpt-6.2-astra con una lista de elementos nueva. No cambies de modelo dentro de la misma conversación, porque OpenAI indica que los cambios de modelo pueden descartar elementos de razonamiento. El cálculo del enrutamiento y un router están en GPT-6.2 Sol API frente a GPT-6.2 Astra API. Para ver cómo plantea el mismo bucle otro proveedor, compáralo con Gemini 4 Carbon API para agentes de programación.

Preguntas frecuentes

¿La GPT-6.2 API admite llamadas a funciones?

Sí, en /v1/responses. Define las herramientas con type: "function", lee los elementos function_call de output y devuelve los resultados como elementos function_call_output con el mismo call_id.

¿Puedo usar herramientas de la GPT-6.2 API con Chat Completions?

No. OpenAI indica que GPT-6.2 admite Chat Completions, pero las llamadas a herramientas requieren Responses.

¿Cómo hago streaming de un turno de agente con la GPT-6.2 API?

Define stream: true en Responses, imprime los eventos response.output_text.delta y lee las llamadas a herramientas y usage del evento response.completed.

¿Cómo reduzco los costes de la GPT-6.2 API en sesiones largas de agentes?

Mantén un prefijo estable (mensaje developer, herramientas, instantánea) al principio, añade en lugar de editar, recorta la salida de las herramientas y quédate por debajo de 272K tokens de entrada por solicitud cuando puedas.

¿Qué modelo GPT-6.2 debería ejecutar mi agente de programación?

Empieza con gpt-6.2-sol, que cuesta una cuarta parte que Astra por token, y reinicia en gpt-6.2-astra las ejecuciones que fallen.

Share: