¿Cómo usar la API de Agentes de OpenAI?

La API de OpenAI Agents ejecuta para usted el arnés de código abierto Codex de OpenAI. Usted envía POST https://api.openai.com/v1/agents/sessions con el encabezado OpenAI-Beta: agents=v1, una definición de agente y una tarea; OpenAI ejecuta el bucle del modelo y las herramientas, mantiene la sesión y puede aprovisionar un sandbox. No hay tarifa por la API de Agents: usted paga por los tokens, las herramientas y el tiempo del contenedor alojado (de $0.03 a $0.48 por sesión de 20 minutos para los tamaños de sandbox de 1 GB a 16 GB). Entró en beta pública el 10 de septiembre de 2026, y OpenAI añadió el uso de computadoras en DevDay el 29 de septiembre.

A continuación: una primera sesión REST, eventos de progreso, herramientas MCP, subagentes y el flujo de aprobación del uso de computadoras. Para saber cómo se compara con otras superficies de agente de OpenAI, lea API de Agents vs API de Responses vs SDK de Agents; para el resto del evento, consulte el resumen de DevDay 2026. Cada llamada es HTTP simple, por lo que puede enviarla desde Apidog antes de escribir código de aplicación.

La API de OpenAI Agents de un vistazo

Fuentes: Presentación de la API de Agents, la descripción general de la API de Agents y la página de precios.

Los cuatro conceptos

La documentación construye la API en torno a cuatro elementos:

• Agente: el modelo, las instrucciones, las herramientas y los servidores MCP. Páselo en línea, o guárdelo y reutilice su agent_id.
• Entorno: un sandbox o computadora opcional donde el agente lee archivos y ejecuta comandos.
• Sesión: una instancia duradera del agente que mantiene la configuración, la conversación y el trabajo guardado.
• Eventos y elementos: los eventos informan el progreso en vivo; los elementos son los mensajes guardados y las llamadas a herramientas.

Un mensaje enviado a una sesión inactiva inicia un nuevo turno; un mensaje enviado a mitad del turno lo dirige. El arnés (según la página de arquitectura, la instancia de Codex alojada que ejecuta el bucle del modelo y las herramientas) también maneja la compactación del contexto, por lo que usted no lo configura.

Elija un entorno

environment.type decide dónde se ejecutan los comandos:

• none: sin cómputo. Los servidores MCP remotos y sus herramientas de función aún funcionan; Bash integrado, aplicación de parches, archivos de espacio de trabajo y MCP de ejecutores no lo hacen.
• openai_hosted: OpenAI administra un sandbox de Linux con Python y Node.js en /workspace. Establezca container_size en small (1 GB), medium (predeterminado, 4 GB) o large (16 GB), y network.access en enabled, disabled o restricted con allowed_domains. Los archivos en /workspace/outputs se convierten en artefactos cuando un turno se completa. Un sandbox inactivo sin keep-alives puede ser eliminado después de una hora.
• self_hosted: su infraestructura. Ejecuta codex exec-server en una computadora portátil, contenedor o sandbox remoto, y se conecta de forma saliente con una clave de entorno separada.

La publicación de lanzamiento enumera a los socios de sandbox Blaxel, Cloudflare, Daytona, DigitalOcean, E2B, Modal, Oracle, Runloop y Vercel; la guía de autoalojamiento añade las MicroVM de AWS Lambda.

Su primera sesión a través de REST

Exporte una clave con los permisos anteriores como OPENAI_API_KEY, luego envíe la tarea de inicio rápido con un contenedor pequeño:

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

Con stream: true, la respuesta es el flujo de eventos del primer turno. Guarde el ID de sesión de este; el resto del ciclo de vida utiliza el mismo recurso:

El SDK de JavaScript tiene la misma forma. Esta versión, adaptada de la publicación de lanzamiento, añade una herramienta, subagentes y una bóveda:

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

Seguir el progreso: flujo o webhooks

Streaming. Abra GET /v1/agents/sessions/{id}/events?stream=true con Accept: text/event-stream antes de enviar la entrada, para no perderse los eventos iniciales. Esté atento a:

• agent.session.turn.output_text.delta y agent.session.turn.output_text.done para el texto
• agent.session.turn.completed, agent.session.turn.failed o agent.session.turn.cancelled para el resultado
• agent.session.requires_action cuando el agente necesita el resultado de una función, una conexión de entorno o una aprobación de uso de computadora

Tres trampas: agent.session.idle no significa que el turno haya tenido éxito, un turno completado puede contener llamadas a herramientas fallidas y cerrar el flujo no detiene la tarea. Los flujos no reproducen eventos perdidos, por lo que después de una desconexión, abra un nuevo flujo y recupere la sesión y sus elementos.

Webhooks. Suscríbase a agent.session.created, agent.session.action_required, agent.session.in_progress, agent.session.idle y agent.session.failed. Tenga en cuenta la nomenclatura: el flujo dice requires_action, el webhook dice action_required. Las cargas útiles omiten los detalles de la llamada, por lo que su manejador recupera la sesión y lee required_actions. Verifique cada firma (verificación de firma de webhook); operaciones de API de larga duración de agentes de IA explica por qué los webhooks son adecuados para tareas de varios minutos.

Herramientas MCP, búsqueda de herramientas, llamada programática de herramientas y subagentes

MCP. Añada un servidor a agent.tools:

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

Por defecto, OpenAI establece la conexión (connection_origin: "service"), por lo que el servidor debe ser accesible desde OpenAI. Utilice connection_origin: "environment" para un servidor de red privada, o stdio para iniciar uno en el sandbox. Para las credenciales, pase transport.authorization para una sesión, o adjunte una credencial de bóveda (static_bearer o mcp_oauth) con vault_ids.

Búsqueda de herramientas. Las herramientas MCP se descubren automáticamente cuando el modelo admite la búsqueda de herramientas. Para muchas herramientas de función, añada {"type": "tool_search"} y marque las funciones defer_loading: true.

Llamada programática de herramientas. Activada por defecto: el agente obtiene una herramienta exec que ejecuta JavaScript en un entorno de ejecución V8 aislado, por lo que puede recorrer las llamadas a herramientas y recortar grandes resultados antes de que lleguen al contexto. Desactívela con {"type": "programmatic_tool_calling", "enabled": false}.

Subagentes. Configure multi_agent: {"enabled": true, "max_concurrent_subagents": 3} (el límite predeterminado es 6). Los subagentes comparten el sistema de archivos del entorno y heredan las herramientas MCP y la búsqueda web, pero no pueden usar herramientas de función. El subagent_id de un turno es null para el agente principal.

Uso de la computadora: la adición de DevDay

El uso de la computadora le da al agente un navegador alojado. Agregue la herramienta y un escritorio a un entorno alojado:

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

El navegador necesita la aprobación del usuario antes de visitar cada nuevo origen de sitio web, incluidos los sitios públicos. En agent.session.requires_action, recupere la sesión y busque las entradas de computer_use_approval_request. El request.type anidado es de dos tipos:

• browser_origin_access: muestre origin y reason, luego envíe approve, deny o cancel.
• browser_authentication: un formulario de inicio de sesión con fields, options de inicio de sesión opcionales y un credential_origin. Envíe action: "submit" con los valores del usuario, o action: "cancel".

Ambas respuestas vuelven a través del punto final de eventos:

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

El trabajo del navegador aparece como elementos computer_use_call con id, turn_id, title, status y output, que contiene una captura de pantalla JPEG base64 cuando include_screenshots está activado y hay una disponible. Mantenga las capturas de pantalla fuera de los registros; pueden mostrar datos de la cuenta.

La guía de uso de la computadora señala estas advertencias:

• La aprobación de origen no es una confirmación de acción. Aprobar un sitio no hace que el agente pregunte antes de cada compra o eliminación. Si necesita eso, restrinja el navegador a recursos que no puedan realizar esas acciones, o use un tiempo de ejecución del navegador que usted controle.
• El inicio de sesión cubre correo electrónico, contraseñas y códigos de verificación. Las claves de acceso y el inicio de sesión con código QR no son compatibles.
• Solo el agente principal puede solicitar autenticación. Los subagentes no pueden.
• Deshabilite los reintentos automáticos en el envío de credenciales (maxRetries: 0 en el SDK, --retry 0 en curl).
• Un 202 significa aceptado, no que la navegación o el inicio de sesión tuvieron éxito. Las solicitudes de autenticación expiran después de cinco minutos.
• La aprobación de origen no anula la política de red. Permita también el sitio y sus dominios de redirección en network.

El resumen dice que el uso de la computadora se envía "a través de la API y en Codex y ChatGPT Work en Pro 500 y Enterprise". Para pruebas impulsadas por UI con el mismo modelo, consulte uso de computadora GPT-6 Astra para pruebas de API.

Dé al agente su API, no su interfaz de usuario

Un navegador es el recurso de respaldo para software sin una API. Si el sistema es suyo, encapsúlelo en un servidor MCP: herramientas tipadas, sin avisos de origen, resultados verificables. Uso de computadora vs. APIs estructuradas cubre la compensación, y el Servidor MCP de Apidog alimenta su especificación de API al asistente de codificación que escribe el envoltorio.

Pruebe la API de Agents en Apidog antes de escribir código

La API está en beta, así que confirme la forma de cada llamada manualmente en Apidog primero:

1. Cree un entorno de Apidog con OPENAI_API_KEY, VAULT_ID y SESSION_ID. Envíe Bearer {{OPENAI_API_KEY}} y OpenAI-Beta: agents=v1 en cada solicitud.
2. Envíe la solicitud de creación de sesión sin stream, afirme un estado 2xx y un id no vacío, y extraiga id en SESSION_ID.
3. Abra el flujo de eventos como una solicitud SSE, envíe la entrada desde una segunda solicitud y observe la llegada de los eventos.
4. Guarde las cargas útiles de aprobación y cancelación como solicitudes para reproducir cada caso de required_actions.
5. Encadénelos en un escenario de prueba y ejecútelo en CI con Apidog CLI.

La guía de prueba de API de agentes de IA tiene patrones de aserción para salida no determinista. Descargue Apidog para seguir el ejemplo.

Preguntas frecuentes

¿Es gratuita la API de OpenAI Agents? No hay tarifa de plataforma, pero usted paga por los tokens del modelo, las llamadas a herramientas y el tiempo del contenedor alojado.

¿Qué modelos funcionan con la API de Agents? Los ejemplos de la documentación, incluyendo todos los ejemplos de uso de la computadora, usan gpt-6-astra. Las páginas no enumeran otros modelos compatibles, así que pruebe los suyos primero.

¿La API de Agents admite la Retención de Datos Cero (ZDR)? No. Solo admite la residencia de datos en EE. UU. y no es elegible para ZDR, incluso con un sandbox autoalojado.

¿En qué se diferencia del SDK de Agents o de la API de Responses? El SDK ejecuta el bucle dentro de su aplicación; la API de Responses es la llamada al modelo en torno a la cual usted construye un bucle. Vea la comparación completa.

Comience con una sesión de solo lectura

Comience con una sesión que solo lee, agregue un servidor MCP, luego agregue el uso de la computadora detrás de un controlador de aprobación que deniega por defecto. Cuando ChatGPT deba reaccionar a eventos de su propio servidor en su lugar, MCP Events es la pieza que coincide.