¿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.

Prueba Apidog hoy

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

Elemento	Valor
Estado	Beta pública desde el 10 de septiembre de 2026; uso de computadora añadido el 29 de septiembre
Crear una sesión	POST /v1/agents/sessions
Encabezado Beta	OpenAI-Beta: agents=v1 (los SDK de OpenAI lo añaden)
Permisos clave	api.agents.read, api.agents.write, api.responses.write
Precios	Sin tarifa de API de Agents; tokens de modelo a tarifas de API, herramientas a tarifas estándar (búsqueda web $10 por 1000 llamadas)
Contenedores alojados	$0.03 (small, 1 GB), $0.12 (medium, 4 GB), $0.48 (large, 16 GB) por sesión de 20 minutos
Entornos	none, openai_hosted, self_hosted
Modelo en los ejemplos de la documentación	gpt-6-astra
Controles de datos	Solo residencia de datos en EE. UU.; sin Retención de Datos Cero (ZDR)
Tamaño máximo de solicitud	4 MiB

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. Ejecute codex exec-server en una computadora portátil, contenedor o sandbox remoto, y conéctese 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: el resto del ciclo de vida utiliza el mismo recurso.

Acción	Solicitud
Seguimiento o dirección	POST /v1/agents/sessions/{id}/events con un evento agent.session.input.message
Cancelar el turno activo	Mismo endpoint, tipo de evento agent.session.input.cancel
Leer el trabajo guardado	GET /v1/agents/sessions/{id}/items?order=asc&limit=100
Limpiar	DELETE /v1/agents/sessions/{id}

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. Supervise estos eventos:

• 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 del turno.
• 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.

Evite estas trampas:

1. agent.session.idle no significa que el turno haya tenido éxito.
2. Un turno completado puede contener llamadas a herramientas fallidas.
3. Cerrar el flujo no detiene la tarea.
4. Los flujos no reproducen eventos perdidos. 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, mientras que el webhook dice action_required. Las cargas útiles omiten los detalles de la llamada, por lo que su manejador debe recuperar la sesión y leer required_actions.

Verifique cada firma con un flujo de verificación de firma de webhook. Para tareas de varios minutos, consulte operaciones de API de larga duración de agentes de IA.

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.
• Utilice stdio para iniciar un servidor en el sandbox.
• Para 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. Si tiene muchas herramientas de función, añada {"type": "tool_search"} y marque las funciones con defer_loading: true.

Llamada programática de herramientas

Está activada por defecto: el agente obtiene una herramienta exec que ejecuta JavaScript en un entorno de ejecución V8 aislado. Esto permite recorrer llamadas a herramientas y recortar resultados grandes antes de que lleguen al contexto.

Para desactivarla:

{
  "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. Cuando reciba agent.session.requires_action:

1. Recupere la sesión.
2. Busque las entradas computer_use_approval_request.
3. Procese el request.type anidado.

Los dos tipos de solicitud son:

• browser_origin_access: muestre origin y reason, luego envíe approve, deny o cancel.
• browser_authentication: presenta 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 endpoint 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. Cuando include_screenshots está activado y hay una disponible, output contiene una captura JPEG en base64.

No guarde estas capturas en sus 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 ese control, 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 y --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 y resultados verificables.

Uso de computadora vs. APIs estructuradas cubre esta 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, incluidos 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 y 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.