Descripción general

La API de agentes está disponible en versión beta. Permite a los desarrolladores crear aplicaciones con un agente de Codex administrado 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 administra 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 para tu aplicación en tu proyecto de la plataforma de OpenAI. Otorga 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 el encabezado OpenAI-Beta: agents=v1. Los SDK de OpenAI agregan este encabezado automáticamente.

¿Mi agente necesita un entorno aislado?

Elige el entorno adecuado para la tarea:

• Sin entorno: el agente responde preguntas o usa herramientas externas sin necesidad de 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 administre su entorno aislado.

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

Consulta la arquitectura de la API de agentes para obtener detalles 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 inspeccionar los turnos, las llamadas a herramientas y la actividad de los subagentes.

La guía de observabilidad también explica cómo revisar el uso 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. Esto te ayuda a verificar qué ocurrió 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 informado. Que una sesión esté inactiva no demuestra por sí solo que la tarea se haya completado correctamente.

¿Cómo se factura el uso?

Las solicitudes al modelo se facturan según 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 actuales.

¿Cómo se manejan los datos y 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 retención cero de datos, ni siquiera cuando usas un entorno aislado autoalojado. Consulta la documentación de la API de agentes para obtener detalles sobre los controles de datos.