Desglosando el Agents SDK de OpenAI: una guía

OpenAI está presentando varias ofertas nuevas: Responses API, herramientas integradas para búsqueda web y de archivos, una herramienta de uso del ordenador y el Agents SDK de código abierto. Mientras que la Responses API permite a los desarrolladores crear agentes sobre su tecnología, el Agents SDK puede ayudarlos a enlazar agentes con otras herramientas y procesos web, realizando “flujos de trabajo” que hacen, de manera autónoma, lo que el usuario o la empresa desea.

A 2025 a menudo se le celebra como el “Año de los agentes”, y el movimiento de OpenAI se considera un paso clave para la industria. El Agents SDK permite a los desarrolladores aprovechar fácilmente los últimos avances de OpenAI (como razonamiento mejorado, interacciones multimodales y nuevas técnicas de seguridad) en escenarios del mundo real y de múltiples pasos. Para desarrolladores de LLM y constructores de agentes de IA, el Agents SDK ofrece un conjunto de “bloques de construcción” para crear y gestionar sus propios sistemas de IA autónomos.

La importancia del Agents SDK radica en su capacidad para abordar los retos de desplegar agentes de IA en entornos de producción. Tradicionalmente, traducir las potentes capacidades de los LLM a flujos de trabajo de varios pasos ha sido laborioso, requiriendo mucha escritura de reglas personalizadas, diseño secuencial de prompts y prueba y error sin herramientas adecuadas de observabilidad. Con el Agents SDK y las nuevas herramientas de API relacionadas, como la Responses API, OpenAI busca simplificar significativamente este proceso, permitiendo a los desarrolladores construir agentes más complejos y fiables con menos esfuerzo.

What is Agents SDK

OpenAI está regresando al código abierto en gran medida con el lanzamiento de su Agents SDK, un conjunto de herramientas diseñado para ayudar a los desarrolladores a gestionar, coordinar y optimizar flujos de trabajo de agentes, incluso creando agentes impulsados por otros modelos que no son de OpenAI, como los de competidores Anthropic y Google, o modelos de código abierto de DeepSeek, Qwen, Mistral y la familia Llama de Meta.

Why use the Agents SDK

El SDK se guía por dos principios de diseño:

1. Suficientes funciones para que valga la pena usarlo, pero pocas primitivas para que sea rápido de aprender.
2. Funciona muy bien desde el primer momento, pero puedes personalizar exactamente lo que ocurre.

Estas son las funciones principales del SDK:

• Bucle del agente: Bucle integrado del agente que gestiona las llamadas a herramientas, envía resultados al LLM y repite hasta que el LLM haya terminado.
• Python-first: Usa funciones del lenguaje integradas para orquestar y encadenar agentes, en lugar de tener que aprender nuevas abstracciones.
• Handoffs: Una función potente para coordinar y delegar entre múltiples agentes.
• Guardrails: Ejecuta validaciones y comprobaciones de entrada en paralelo a tus agentes, cortando de forma anticipada si las comprobaciones fallan.
• Herramientas de funciones: Convierte cualquier función de Python en una herramienta, con generación automática de esquemas y validación impulsada por Pydantic.
• Tracing: Trazabilidad integrada que te permite visualizar, depurar y monitorizar tus flujos de trabajo, así como usar el conjunto de herramientas de evaluación, ajuste fino y destilación de OpenAI.

How to use Openai Agents SDK

1. Configura tu entorno de Python

python -m venv env
source env/bin/activate

2. Instala Agents SDK

pip install openai-agents

3. establece la variable de entorno OPENAI_API_KEY

Configura libremente la API OPENAI_API_KEY desde CometAPI

• Inicia sesión en cometapi.com. Si aún no eres usuario, regístrate primero.
• Obtén la clave de API de credenciales de acceso de la interfaz. Haz clic en “Add Token” en el token de API del centro personal, obtén la clave del token: sk-xxxxx y envíala.
• Obtén la URL de este sitio: https://api.cometapi.com/
• Selecciona el endpoint OPENAI_API_KEY para enviar la solicitud a la API y configura el cuerpo de la solicitud. El método y el cuerpo de la solicitud se obtienen de la documentación de la API en nuestro sitio web. Nuestro sitio también ofrece pruebas en Apifox para tu comodidad.

4. Configura tu agente

Define qué herramientas puede usar tu IA. Supongamos que queremos habilitar búsqueda web y recuperación de archivos:

from agent_sdk import Agent, WebSearchTool, FileRetrievalTool

search_tool = WebSearchTool(api_key="your_api_key")
file_tool = FileRetrievalTool()

agent = Agent(tools=)

Ahora tu agente sabe cómo buscar en la web y recuperar documentos.

5. ejecuta

A diferencia de los chatbots tradicionales, esta IA decide qué herramienta usar en función de la entrada del usuario:

def agent_task(query):
    result = agent.use_tool("web_search", query)
    return result

response = agent_task("Latest AI research papers")
print(response)

Sin intervención manual: solo ejecución autónoma.

El bucle del agente

Cuando llamas a Runner.run(), el SDK ejecuta un bucle hasta obtener una salida final:

1. Se llama al LLM usando el modelo y la configuración del agente, junto con el historial de mensajes.
2. El LLM devuelve una respuesta, que puede incluir llamadas a herramientas.
3. Si la respuesta tiene una salida final, el bucle termina y la devuelve.
4. Si la respuesta incluye un handoff, el agente pasa a ser el nuevo agente y el bucle continúa desde el paso 1.
5. Se procesan las llamadas a herramientas (si las hay) y se añaden los mensajes de respuesta de herramientas. Luego, el bucle continúa desde el paso 1.

Puedes usar el parámetro max_turns para limitar el número de ejecuciones del bucle.

​Resultado final

La salida final es lo último que produce el agente en el bucle:

• Si estableces un output_type en el agente, la salida final se produce cuando el LLM devuelve algo de ese tipo usando salidas estructuradas.
• Si no hay output_type (es decir, respuestas de texto sin formato), entonces la primera respuesta del LLM sin llamadas a herramientas ni handoffs se considera la salida final.

Ejemplo Hola mundo

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,

# Functions calling themselves,
# Infinite loop's dance.

Estructura técnica

“El OpenAI Agents SDK pretende ser un marco conceptual que demuestre cómo diferentes agentes, como un ‘Triage Agent’ o un ‘CRM Agent’, pueden colaborar para completar tareas mediante interacciones con herramientas y mecanismos de delegación.”

Componentes principales y arquitectura de Agents SDK

El OpenAI Agents SDK se construye sobre un conjunto de principios concisos pero sólidos. En su núcleo está el concepto de Agent, que representa una instancia de un modelo de lenguaje adaptada con instrucciones específicas y equipada para usar diversas herramientas. Los agentes comienzan recibiendo solicitudes de usuario —como preguntas o definiciones de tareas—, luego descomponen estas tareas en subtareas que pueden implicar el uso de herramientas predefinidas, y finalmente entregan una respuesta completa. Estas Tools se describen funcionalmente como funciones invocables; aprovechando el Agents SDK, cualquier función de Python puede servir sin fricción como herramienta, con validación de esquemas automática para entradas y salidas proporcionada mediante Pydantic. Por ejemplo, funciones de Python que representan una herramienta de consulta de base de datos o una herramienta de búsqueda web pueden integrarse directamente en el conjunto de herramientas de un agente.

Otra pieza central del Agents SDK es el Agent Loop, que define el proceso iterativo de resolución de tareas. Comenzando con un intento inicial de responder a una consulta, un agente evalúa si dispone de información suficiente o si necesita realizar acciones externas. Cuando es necesario, el agente invoca la herramienta pertinente, procesa la salida y reevalúa la tarea. Este ciclo se repite hasta que el agente indica finalización con una respuesta de “He terminado”. Agents SDK gestiona este proceso de forma autónoma, simplificando el desarrollo al automatizar tareas recurrentes como la invocación de herramientas, el manejo de resultados y los reintentos iterativos. Esto permite a los desarrolladores centrarse más en definir flujos de trabajo y capacidades de los agentes sin preocuparse por la mecánica subyacente. OpenAI describe este enfoque como Python-first, enfatizando el uso de construcciones familiares de Python —como bucles, condicionales y llamadas a funciones— en lugar de lenguajes específicos de dominio (DSL). Con esta flexibilidad, los desarrolladores pueden orquestar agentes interconectados confiando en la sintaxis nativa de Python.

Handoff y arquitectura multiagente

Las capacidades del SDK van más allá de los agentes individuales. A través de una función conocida como Handoff, las tareas pueden transferirse entre múltiples agentes, permitiéndoles colaborar sin fricciones. Por ejemplo, un “Triage Agent” puede determinar la naturaleza de una consulta entrante y delegarla a otro agente especializado, o la salida de un agente puede actuar como entrada para otro. Este sistema admite flujos de trabajo en los que agentes especializados ejecutan partes distintas de una tarea más amplia, potenciando arquitecturas multiagente complejas. OpenAI ha diseñado el conjunto de herramientas para aplicaciones escalables, como automatización de soporte al cliente, procesos de investigación, proyectos de múltiples pasos, creación de contenidos, operaciones de ventas o incluso revisiones de código. Además, Guardrails mejora la fiabilidad imponiendo reglas de validación sobre entradas o salidas del agente. Por ejemplo, los guardrails pueden hacer cumplir el cumplimiento del formato de parámetros o terminar el bucle de forma anticipada cuando se detectan anomalías, reduciendo riesgos como ejecuciones ineficientes o comportamientos no deseados en operaciones del mundo real.

Orquestación y supervisión

Más allá de la ejecución de tareas, el Agents SDK incluye sólidas funciones de orquestación, encargándose de la ejecución de herramientas, los flujos de datos y la gestión del bucle. A pesar del alto nivel de automatización, OpenAI prioriza la transparencia, equipando a los desarrolladores con herramientas para monitorizar la actividad del agente en tiempo real. Mediante la función de Tracing integrada y accesible en el panel de OpenAI, los desarrolladores pueden visualizar los flujos de trabajo paso a paso, observando cuándo se llaman las herramientas, qué entradas usan y qué salidas devuelven. La plataforma utiliza la infraestructura de monitorización de OpenAI para desglosar la ejecución de la lógica del agente en trazas y spans, ofreciendo información granular sobre el comportamiento del agente. Esto permite a los desarrolladores diagnosticar cuellos de botella, depurar problemas, optimizar flujos de trabajo y seguir el rendimiento. Además, la arquitectura de tracing admite evaluaciones sofisticadas, posibilitando el ajuste fino y la mejora del rendimiento del agente a lo largo del tiempo.

Ventajas

El OpenAI Agents SDK no es solo para desarrolladores individuales; también ofrece ventajas significativas a las empresas que construyen productos basados en agentes de IA. Comencemos con las ventajas:

Prototipado rápido y producción: Agents SDK implementa comportamientos complejos de agentes con un código y configuración mínimos, acortando el ciclo de la idea al producto. Por ejemplo, la plataforma cripto de referencia Coinbase utiliza el SDK para prototipar y desplegar rápidamente sistemas de soporte multiagente. De manera similar, en áreas como asistentes de búsqueda empresarial, las empresas pueden integrar las herramientas de búsqueda web y de archivos del SDK para ofrecer valor rápidamente. Al descargar los detalles de orquestación, los desarrolladores pueden centrarse en funciones específicas del producto.

Reducción de costes de desarrollo: Construir un sistema de agentes desde cero requiere una inversión de ingeniería significativa. Agents SDK reduce costes proporcionando soluciones listas para necesidades comunes: gestión del bucle, sincronización de llamadas a API, manejo de errores y salidas de herramientas formateadas para LLM. Al ser de código abierto, también permite la personalización para satisfacer las necesidades de la empresa. Esto es una ventaja para startups, permitiéndoles crear potentes productos impulsados por agentes con recursos limitados.

Trazabilidad y depuración: El panel de seguimiento integrado del SDK transforma las aplicaciones empresariales. Las preocupaciones del sector sobre la IA como “caja negra” ahora permiten que cada paso del agente se registre y audite. Si un agente de soporte al cliente da una respuesta incorrecta, la traza muestra qué llamada a herramienta o paso falló. La pantalla de registros/traeas de la plataforma de OpenAI mejora la auditabilidad de los agentes, lo cual es crítico en industrias sujetas a regulación o auditorías internas. Esto permite a las empresas integrar IA con mayor confianza, sabiendo que pueden explicar los resultados cuando sea necesario.

Acceso a los últimos modelos y herramientas de OpenAI: Usar el Agents SDK significa aprovechar los mejores modelos de OpenAI (p. ej., GPT-4) y las herramientas actuales (búsqueda web, ejecución de código). Esto proporciona una ventaja de calidad frente a alternativas que pueden depender de modelos más débiles. Para aplicaciones que requieren alta precisión o información actualizada (p. ej., asistentes de investigación, agentes de análisis financiero), el rendimiento de los modelos de OpenAI es una gran ventaja. A medida que OpenAI añade herramientas (insinuando más integraciones por venir), los usuarios del SDK pueden adoptarlas fácilmente.

CometAPI es totalmente compatible con el protocolo de la interfaz de OpenAI para garantizar una integración sin fricciones. Puedes evitar dependencias de modelos y servicios (riesgo de bloqueo), reducir las preocupaciones de privacidad y seguridad de los datos y reducir costes. Aprovechar los potentes modelos y herramientas de OpenAI puede ser costoso y a veces limitar el rendimiento. CometAPI ofrece precios más bajos.

Conclusión

OpenAI está comprometida con el avance de las capacidades de la IA mediante ofertas innovadoras como la Responses API. Al introducir estas herramientas, las empresas y los desarrolladores obtienen la oportunidad de crear soluciones de IA más inteligentes, adaptables y altamente fiables. Estos desarrollos apuntan a un futuro en el que la inteligencia artificial siga impulsando cambios impactantes y desbloqueando nuevas posibilidades en todas las industrias.