TL;DR
La OpenAI Agents API es una plataforma gestionada para crear agentes de IA que razonan, usan herramientas, ejecutan código y completan tareas multietapa. Está diseñada para aplicaciones que necesitan continuar el trabajo a lo largo de varios turnos, ejecutar herramientas y recuperarse de interrupciones sin implementar por sí mismas todo el bucle del agente. Esta guía ayuda a los desarrolladores a evaluar sus capacidades, opciones de integración y costos.
A diferencia de una API LLM convencional, OpenAI Agents API admite sesiones persistentes, entornos de ejecución gestionados, coordinación multiagente, eventos en streaming y artefactos. Los desarrolladores pueden usar los endpoints nativos de OpenAI Agents API para ejecución gestionada, o integrar los modelos compatibles de OpenAI a través de CometAPI para crear flujos de trabajo de agentes personalizados. Estas son vías de integración distintas.
Key Takeaways
- OpenAI Agents API gestiona sesiones persistentes y ejecución multietapa, reduciendo la orquestación que los desarrolladores deben operar.
- Sus capacidades principales incluyen ejecución de código en sandbox, herramientas y conexiones MCP, subagentes y artefactos guardados.
- Los costos de OpenAI Agents API combinan tokens de modelo, herramientas elegibles y cómputo alojado opcional; evalúe el costo por tarea completada.
- Los beneficios reportados por clientes ofrecen evidencia específica por carga de trabajo, en lugar de un benchmark estandarizado para todas las aplicaciones.
- La ejecución gestionada nativa y los agentes personalizados usando CometAPI son opciones de integración separadas con diferentes responsabilidades de infraestructura.
What Is the OpenAI Agents API?
OpenAI Agents API es un servicio de ejecución gestionada para aplicaciones que realizan tareas multietapa usando modelos de razonamiento y herramientas externas. Expone el arnés de agente de Codex como servicio. En lugar de gestionar manualmente las llamadas al modelo, la ejecución de herramientas, el estado de sesión y la recuperación de tareas, los desarrolladores pueden delegar gran parte de esa coordinación en el runtime.
Un chatbot convencional genera una respuesta; un agente puede planificar pasos, ejecutar código en un entorno autorizado, inspeccionar errores, reintentar y entregar archivos generados. Esto hace que la API sea adecuada para flujos operativos, no solo para chat.
OpenAI Agents API Workflow
Un flujo de trabajo de agente reúne cuatro partes: el agente define el modelo, las instrucciones y las herramientas disponibles; el entorno proporciona cómputo y acceso a archivos; la sesión preserva el contexto y el trabajo guardado; y los eventos y elementos exponen el progreso y los resultados. Conjuntamente, estos componentes permiten que su aplicación envíe una tarea, siga su ejecución y continúe el trabajo en turnos posteriores. Consulte la Descripción general de OpenAI Agents API para los conceptos subyacentes.
Flujo típico: crear una sesión; enviar un objetivo; permitir que el modelo razone y elija las herramientas permitidas; ejecutar esas herramientas; inspeccionar resultados intermedios; y hacer streaming del progreso y de los artefactos finales. La sesión puede continuarse según sea necesario.
El diagrama oficial muestra la aplicación intercambiando entrada y eventos con el arnés y el sandbox gestionados. Diagrama de arquitectura de la documentación de arquitectura de OpenAI Agents API; obra original de OpenAI.
What Are the Main OpenAI Agents API Features?
Las capacidades del arnés gestionado abarcan ejecución de código, gestión de contexto, conexiones de herramientas, steering y delegación. La disponibilidad también depende del entorno y las herramientas configuradas.
Persistent Sessions and Context Management
Las sesiones preservan la configuración, el contexto de la conversación y el trabajo guardado a lo largo de los turnos. Los desarrolladores pueden enviar una nueva instrucción a una sesión existente; la gestión del contexto ayuda a sostener tareas extendidas mientras reduce la necesidad de escribir lógica personalizada de compresión de transcripciones.
Sandboxed Code Execution
| Environment | Infrastructure | Best use |
|---|---|---|
| none |
Los entornos alojados pueden ejecutar programas de Python, Node.js y de línea de comandos en un espacio de trabajo aislado. Un entorno autoalojado permite que el agente gestionado use cómputo controlado por el desarrollador. Los desarrolladores operan y aseguran ese entorno, mientras que Agents API continúa gestionando el arnés del agente y el estado de la sesión.
Multi-Agent Collaboration
Un agente coordinador puede delegar tareas independientes a subagentes especialistas. Agentes de investigación podrían examinar fuentes separadas mientras un agente principal concilia la evidencia. El paralelismo puede mejorar el rendimiento, pero llamadas adicionales al modelo y la coordinación pueden incrementar el costo. La API admite concurrencia configurable y ajustes de subagentes.
OpenAI Agents API vs Agents SDK vs Responses API vs AgentKit
Agents API proporciona ejecución gestionada; Agents SDK se adapta a aplicaciones que poseen su pila de orquestación; Responses API es apropiada para inferencia y flujos de herramientas más ligeros; AgentKit suministra componentes de desarrollo complementarios en lugar de otro runtime de agentes alojado equivalente.
How to Get Started With the OpenAI Agents API
Step 1: Configure API Access
Use una clave de proyecto de OpenAI Platform con los permisos de agente e inferencia requeridos por los prerrequisitos del inicio rápido. Los ejemplos con curl apuntan a una shell compatible con Bash con curl instalado; el ejemplo de PowerShell solo establece la variable de entorno. Mantenga las claves fuera del control de versiones.
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
export OPENAI_API_KEY="your-openai-api-key"
PowerShell code example: Establezca la clave de API en el proceso actual de PowerShell.
$env:OPENAI_API_KEY="your-openai-api-key"
Step 2: Create Your First Agent
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write reliable Python code, execute it, and report observed results."
},
"environment": {"type": "openai_hosted", "container_size": "small"},
"input": "Calculate the mean and standard deviation of [12,15,19,20,24] in Python.",
"stream": true
}'
La sesión inicia su primer turno y hace streaming de eventos de estado mientras el agente ejecuta herramientas y prepara una respuesta.
Step 3: Enable Multi-Agent Execution
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
curl --no-buffer --fail-with-body \
https://api.openai.com/v1/agents/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Delegate independent analyses and reconcile the results.",
"multi_agent": {"enabled": true, "max_concurrent_subagents": 2}
},
"environment": {"type": "none"},
"input": "Compare two release changes: date filtering in search and export URL behavior.",
"stream": true
}'
Step 4: Continue an Existing Session
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Summarize the findings in an executive report."}]}]}]}'
Guarde los identificadores de sesión, aplique salvaguardas de reintento y distinga nuevas instrucciones de los mensajes usados para orientar el trabajo activo.
Step 5: Inspect Results and Clean Up
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID/items?order=asc&limit=100" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
curl --fail-with-body -X DELETE \
"https://api.openai.com/v1/agents/sessions/$SESSION_ID" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"
Recupere los artefactos antes de eliminar los recursos gestionados. Desconectarse de un stream no necesariamente cancela el trabajo en curso.
Session Configuration Parameters
Cree una sesión con POST https://api.openai.com/v1/agents/sessions. Los ejemplos beta a continuación usan OpenAI-Beta: agents=v1, siguiendo el inicio rápido oficial de Agents API.
El esfuerzo de razonamiento afecta la latencia, el consumo de tokens y la profundidad de planificación. Seleccione el esfuerzo admitido por el modelo y la interfaz elegidos usando la guía oficial de GPT-6; no debe asumirse que la configuración a nivel de modelo se aplica de forma idéntica a todos los endpoints.
How to Build an AI Agent With CometAPI?
CometAPI puede suministrar inferencia de modelos para una aplicación de agente personalizada. Su aplicación sigue siendo responsable del bucle del agente, la ejecución de herramientas, el estado de sesión, la recuperación y cualquier enrutamiento entre modelos compatibles. Esto le da control sobre la orquestación, a la vez que convierte esa infraestructura en su responsabilidad operativa.
Elija la integración nativa de Agents API cuando desee que OpenAI gestione la ejecución del agente y el estado de la sesión. Elija una aplicación basada en CometAPI cuando quiera construir y operar su propia orquestación alrededor de APIs de modelos compatibles. El acceso a un modelo a través de CometAPI no establece por sí mismo compatibilidad con los endpoints de sesión nativos de Agents API; verifique la interfaz que pretende usar. Los costos también siguen vías diferentes: el uso nativo se factura por OpenAI, mientras que una aplicación personalizada combina cargos de CometAPI con sus costos de infraestructura.
Step 1: Connect to CometAPI
Bash code example: Ejecute los siguientes comandos en una terminal compatible con Bash.
pip install --upgrade openai
export COMETAPI_KEY="your-cometapi-key"
Python code example: Envíe una solicitud de inferencia de modelo e imprima la respuesta.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.responses.create(
model="gpt-6-astra",
input=(
"Analyze an API latency spike after a database migration. "
"Identify possible causes and prioritize diagnostic steps."
),
)
print(response.output_text)
Los desarrolladores pueden acceder a la API GPT-6 Astra en CometAPI. El ejemplo anterior realiza inferencia de modelo; implementar el bucle de herramientas descrito a continuación es una responsabilidad separada de la aplicación.
Step 2: Add a Tool-Execution Layer
Un controlador personalizado puede solicitar al modelo, inspeccionar solicitudes de llamadas a herramientas, autorizar y ejecutar acciones, devolver resultados y repetir hasta la finalización o un límite predefinido. Establezca límites en turnos, llamadas a herramientas, tiempo de ejecución y gasto; requiera confirmación independiente para operaciones destructivas.
What Are the Best OpenAI Agents API Applications?
- Ingeniería de software: Analizar incidencias, generar cambios de código, ejecutar pruebas y preparar revisiones, con aprobación antes de fusionar o desplegar cambios.
- Análisis de datos e informes: Procesar conjuntos de datos cargados, ejecutar cálculos en Python, crear gráficos y convertir los resultados en informes que respalden decisiones.
- Respuesta a incidentes de TI: Inspeccionar alertas, correlacionar logs, consultar runbooks y recomendar remediación, con autorización humana para acciones arriesgadas.
- Automatización de soporte al cliente: Recuperar registros relevantes, resumir tickets, redactar respuestas y enrutar casos no resueltos mediante acceso permitido al CRM.
- Comparar documentos, verificar afirmaciones, extraer hechos y preparar hallazgos con citas de apoyo.
Evaluate Your Workflow
Comience con una tarea representativa de su propia carga de trabajo y defina qué significa una finalización exitosa. Compare el agente con su proceso actual usando las mismas entradas y criterios de aceptación. Incluya solicitudes de seguimiento y fallos de herramientas para que la evaluación pruebe la recuperación además del camino ideal.
Lea estas medidas en conjunto. Un flujo que completa más tareas puede seguir siendo una mala opción si requiere correcciones manuales frecuentes o excede sus límites de tiempo y costo. Use los resultados para decidir dónde automatizar, dónde mantener revisión humana y qué fallos abordar antes de ampliar el uso.
How Much Does the OpenAI Agents API Cost?
No existe una tarifa separada para la plataforma del arnés gestionado. Los tokens de modelo, las llamadas a herramientas elegibles y el cómputo alojado opcional determinan el costo total de uso. Las tarifas de modelo a continuación están en USD por millón de tokens para procesamiento Standard con prompts de contexto corto (hasta 272K tokens de entrada), verificadas el 21 de octubre de 2026. Prompts más largos, otros niveles de procesamiento, escrituras de caché y procesamiento regional pueden cambiar la tarifa aplicable.
Para el acceso a modelos a través de CometAPI, los desarrolladores pueden usar GPT-6.1 Sol y GPT-6 Luna. La tabla anterior muestra tarifas de OpenAI; la facturación de CometAPI sigue sus propias tarifas aplicables.
Example: Estimating a Task Cost
Este total ilustrativo de $1.05 asume los volúmenes de tokens mostrados, dos búsquedas, un período de 20 minutos con contenedor pequeño y sin tokens de contenido de búsqueda adicionales facturables ni escrituras de caché. El costo real también depende de reintentos, uso de subagentes, comportamiento de caché y las reglas de facturación del sandbox que apliquen a la sesión. Haga un seguimiento del costo por tarea correctamente completada en una carga de trabajo representativa.
What Are the Limitations of the OpenAI Agents API?
Límites de datos. Agents API actualmente admite residencia de datos solo en Estados Unidos y no admite Zero Data Retention (ZDR). Un sandbox autoalojado no cambia su elegibilidad para ZDR. Antes de enviar material sensible, verifique si los términos de retención y residencia del servicio satisfacen sus requisitos.
Compatibilidad de API y modelo. Las interfaces en beta pública pueden cambiar, y las funciones compatibles pueden variar según el modelo. Pruebe el modelo exacto, endpoint, ajustes de razonamiento y herramientas que usa su aplicación. Repita las comprobaciones de integración cuando cambie un modelo o adopte una actualización de la API.
Control de ejecución. Las tareas multietapa pueden acumular tokens, tomar tiempos variables y encontrar fallos en herramientas. Establezca presupuestos y límites de turnos y tiempo de ejecución, conceda solo los permisos que la tarea necesita y supervise el trabajo de larga duración de forma asíncrona. Planifique cómo recuperarse de llamadas a herramientas interrumpidas y exija aprobación humana para acciones con consecuencias significativas.
FAQ
How should OpenAI Agents API clients retry follow-up messages?
Reuse la misma clave de envío al reintentar el mismo mensaje lógico, siguiendo el patrón de entrada de sesión y reintento. Mantenga juntos el ID de sesión y la clave de envío en el estado de la aplicación. Una instrucción de usuario separada debe usar su propia clave; una respuesta HTTP perdida no debe tratarse automáticamente como una nueva instrucción.
Can an OpenAI Agents API session change models?
El endpoint de configuración de sesión admite actualizar el modelo, el esfuerzo de razonamiento y el nivel de servicio. Las actualizaciones afectan a turnos posteriores; un turno activo conserva su configuración existente. Confirme que la configuración resultante esté admitida por el modelo seleccionado, y cree una nueva sesión cuando necesite cambiar ajustes que este endpoint no acepta.
How does OpenAI Agents API restrict sandbox network access?
Los entornos alojados por OpenAI admiten acceso saliente habilitado, deshabilitado o restringido. El modo restringido usa listas de permitidos explícitas de hosts, y redirecciones o subdominios pueden requerir sus propias entradas. Configure la política de red del sandbox para los servicios que necesita una tarea; el acceso a red y las credenciales de la aplicación son controles separados.
Conclusion
Evalúe Agents API con una tarea representativa que requiera varias llamadas a herramientas y al menos un turno de seguimiento. Mida la tasa de finalización, el comportamiento de recuperación, la latencia y el costo por tarea exitosa. Estos resultados mostrarán si la ejecución gestionada satisface los requisitos de su aplicación.