Descripción general

La API de agentes está disponible en versión beta. Permite a los desarrolladores crear aplicaciones con un agente de Codex gestionado por OpenAI que puede trabajar en varios pasos y continuar en la misma sesión.

Tu aplicación proporciona la tarea, las herramientas y la configuración. OpenAI gestiona la sesión del agente y la coordinación entre su modelo y sus herramientas.

¿Qué puede hacer un agente?

Según sus herramientas y su entorno de ejecución, un agente puede ejecutar código, editar archivos, usar conexiones MCP y generar archivos para tu aplicación. Puedes enviar instrucciones adicionales o continuar con otra tarea en la misma sesión.

Consulta la descripción general de la API de agentes para conocer las capacidades disponibles y ver ejemplos.

¿Cómo empiezo?

1. Crea una clave de API de aplicación en tu proyecto de la plataforma de OpenAI. Concede los permisos api.agents.read y api.agents.write para las sesiones, además de api.responses.write para las solicitudes al modelo.

2. Sigue la guía de inicio rápido para configurar un agente, crear una sesión y enviar una tarea.

3. Sigue los eventos de la sesión para revisar el progreso y los resultados. Guarda el ID de la sesión si quieres continuar el trabajo.

Mantén tu clave de API fuera del entorno aislado del agente. Las solicitudes requieren la cabecera OpenAI-Beta: agents=v1. Los SDK de OpenAI añaden esta cabecera automáticamente.

¿Mi agente necesita un entorno aislado?

Elige el entorno que se adapte a la tarea:

• Sin entorno: el agente responde a preguntas o usa herramientas externas sin necesitar comandos de shell integrados ni archivos del espacio de trabajo.

• Entorno aislado alojado en OpenAI: el agente necesita ejecutar scripts o trabajar con archivos, y quieres que OpenAI gestione su entorno aislado.

• Entorno aislado en tu propia infraestructura: necesitas usar tu propia infraestructura, tu software o tu red privada. Tu aplicación gestiona el ciclo de vida del entorno.

Consulta la arquitectura de la API de agentes para obtener más información sobre la configuración.

¿Dónde puedo revisar una sesión?

Abre Registros en el panel de la plataforma, selecciona Agentes y busca el ID de la sesión. Puedes examinar los turnos, las llamadas a herramientas y la actividad de los subagentes.

La guía de observabilidad también explica cómo revisar el consumo de tokens registrado.

¿Qué pasa si se desconecta el flujo de eventos?

Recupera la sesión existente y sus elementos guardados antes de volver a intentarlo. Así podrás comprobar qué ha ocurrido antes de enviar más trabajo.

Que un turno se haya completado no significa que todas las herramientas se hayan ejecutado correctamente. Revisa el resultado indicado. Que una sesión esté inactiva no basta para confirmar que la tarea haya finalizado correctamente.

¿Cómo se factura el consumo?

A las solicitudes al modelo se les aplican las tarifas de API del modelo seleccionado. A las herramientas de OpenAI y los entornos aislados alojados en OpenAI se les aplican las tarifas correspondientes de herramientas y contenedores.

Consulta los precios de la API para conocer las tarifas vigentes.

¿Cómo se gestionan los datos y los archivos de las sesiones?

La API de agentes conserva el estado de la sesión para que el trabajo pueda continuar de un turno a otro. Puedes eliminar las sesiones y los artefactos publicados cuando ya no los necesites. Guarda los archivos que necesites antes de eliminar una sesión.

Actualmente, la API de agentes solo admite la residencia de datos en Estados Unidos. No admite la opción sin retención de datos, ni siquiera cuando usas un entorno aislado alojado en tu propia infraestructura. Consulta la documentación de la API de agentes para obtener más información sobre los controles de datos.