OpenAI Agents SDK
Índice de contenidos
- Puntos clave
- ¿Qué es el Agents SDK y de dónde viene?
- ¿Cómo se instala y cómo es un agente mínimo?
- ¿Qué son las herramientas, los handoffs y las guardrails?
- ¿Cómo funciona el trazado integrado?
- ¿SDK o construir el bucle a mano?
- Preguntas frecuentes
- ¿El OpenAI Agents SDK solo funciona con modelos de OpenAI?
- ¿En qué se diferencia de Swarm?
- ¿Necesito saber async para usarlo?
- Conclusión
- Fuentes
Escribir un agente desde cero significa montar a mano el bucle que llama al modelo, lee qué herramienta quiere usar, la ejecuta y vuelve a llamar: el OpenAI Agents SDK te da ese bucle ya hecho con muy pocas piezas. Es un framework de Python ligero para construir agentes y sistemas de varios agentes sin abstracciones raras, apoyándose en el propio lenguaje. En esta guía instalarás el paquete, escribirás un agente mínimo con el Runner, y verás sus cuatro ideas centrales (herramientas, traspasos, barreras de seguridad y trazado) y cuándo compensa frente a escribir el bucle por tu cuenta. La misma explicación está disponible en inglés.
Puntos clave
- El OpenAI Agents SDK es un framework de Python para construir agentes de IA con un conjunto muy pequeño de primitivas: agentes, herramientas, traspasos, barreras y sesiones.
- Se instala con
pip install openai-agentse importas todo desde el móduloagents; la versión 0.18.2 salió el 11 de julio de 2026 y requiere Python 3.10 a 3.14. - Es la versión lista para producción de Swarm, el experimento de octubre de 2024 de menos de 1.000 líneas que acumuló unas 20.000 estrellas pese a llevar escrito "no apto para producción".
- No te ata a OpenAI: admite la API de Responses y de Chat Completions, y es compatible con más de 100 LLMs a través de LiteLLM, incluidos modelos que ejecutas en tu propia máquina.
- Trae trazado integrado: cada ejecución del agente se registra con sus pasos, herramientas y traspasos, sin que tengas que añadir una biblioteca aparte.
¿Qué es el Agents SDK y de dónde viene?
El OpenAI Agents SDK es una biblioteca de Python para construir aplicaciones agénticas con muy pocas abstracciones. La documentación oficial lo define como "un conjunto muy pequeño de primitivas" que, combinadas con Python, bastan "para construir aplicaciones reales sin una curva de aprendizaje pronunciada". La idea es no reinventar un lenguaje de flujos: usas funciones, clases y async/await de siempre para orquestar los agentes.
Su origen es Swarm, un framework educativo que OpenAI publicó en octubre de 2024. Swarm cabía en menos de 1.000 líneas, su README avisaba de que no era para producción y aun así reunió cerca de 20.000 estrellas, porque sus abstracciones eran buenas y la alternativa era escribir a mano la lógica de traspaso sobre Chat Completions. El Agents SDK recoge esas ideas y las convierte en una biblioteca mantenida y estable: a mediados de 2026 el repositorio openai/openai-agents-python ronda las 28.000 estrellas y publica versiones con frecuencia, como la 0.18.2 del 11 de julio de 2026.
El SDK se apoya en dos principios explícitos: reunir "suficientes prestaciones para merecer la pena, pero pocas primitivas para aprenderlo rápido", y "funcionar bien de fábrica, pero dejándote personalizar exactamente qué ocurre". Ese equilibrio lo sitúa entre un framework pesado y escribir el bucle a mano, un punto medio que también busca el SDK de agentes de Anthropic.
¿Cómo se instala y cómo es un agente mínimo?
La instalación es un solo comando. Conviene crear antes un entorno virtual y fijar tu clave de API en una variable de entorno:
python -m venv .venv && source .venv/bin/activate
pip install openai-agents
export OPENAI_API_KEY="tu-clave"
Un agente mínimo son dos objetos: un Agent con nombre e instrucciones, y el Runner que lo ejecuta. El Runner es quien monta el bucle por dentro: llama al modelo, mira si pide una herramienta o un traspaso, actúa y repite hasta que el agente produce una salida final.
from agents import Agent, Runner
agente = Agent(
name="Asistente",
instructions="Eres un asistente claro y conciso en español.",
)
resultado = Runner.run_sync(agente, "Escribe un haiku sobre la recursión.")
print(resultado.final_output)
run_sync es la variante síncrona; también existen Runner.run (asíncrona, con await) y Runner.run_streamed para recibir la respuesta a medida que se genera. El objeto resultado no solo trae final_output: guarda toda la traza de pasos, llamadas a herramientas y traspasos, que es justo lo que alimenta el trazado del que hablamos más abajo.
¿Qué son las herramientas, los handoffs y las guardrails?
Sobre ese esqueleto, el SDK añade tres primitivas que convierten un chat en un agente útil.
Una herramienta es una función de Python que decoras con @function_tool. El SDK genera el esquema de argumentos a partir de tu firma de tipos (usa Pydantic por dentro), así que el modelo sabe cómo llamarla y con qué parámetros. Un traspaso o handoff deja que un agente ceda el turno a otro más especializado: un agente de triaje decide y pasa la conversación entera, sin que tú escribas el enrutado. Y una barrera de seguridad o guardrail valida la entrada o la salida en paralelo, y corta la ejecución si algo incumple una regla (por ejemplo, una petición fuera de tema o un dato personal en la respuesta).
from agents import Agent, Runner, function_tool
@function_tool
def clima(ciudad: str) -> str:
return f"En {ciudad} hace 22 grados y está despejado."
soporte = Agent(name="Soporte", instructions="Ayudas con incidencias.")
triaje = Agent(
name="Triaje",
instructions="Deriva al agente adecuado o responde con el tiempo.",
tools=[clima],
handoffs=[soporte],
)
print(Runner.run_sync(triaje, "¿Qué tiempo hace en Madrid?").final_output)
Estas piezas se combinan sin fricción: un mismo agente puede tener varias herramientas, ceder el control a otros agentes y quedar envuelto por barreras de entrada y de salida. Con los traspasos construyes desde un simple triaje hasta los patrones de sistemas multiagente más complejos, como orquestador-trabajadores.
¿Cómo funciona el trazado integrado?
La observabilidad no es un añadido: viene de serie. Cada ejecución genera una traza con sus spans (llamadas al modelo, ejecuciones de herramientas, traspasos, comprobaciones de barreras), que puedes ver en el panel de trazas de la plataforma de OpenAI. Esto importa porque depurar un agente a ciegas es desesperante: sin la traza no sabes por qué eligió una herramienta o entró en bucle.
El trazado es extensible mediante procesadores, así que puedes enviar esos mismos datos a herramientas externas. Si prefieres una solución que ejecutes en tu propia máquina, encaja bien con Langfuse para la observabilidad de agentes, que ingiere trazas por OpenTelemetry. Junto al trazado, en abril de 2026 OpenAI amplió el SDK con ejecución en un sandbox nativo y un harness pensado para empresa, disponible primero en Python y con TypeScript previsto después.
¿SDK o construir el bucle a mano?
Escribir el bucle agéntico por tu cuenta sobre la API de Chat Completions es perfectamente viable y educativo: entiendes cada paso. El coste aparece cuando llegan los detalles: reintentos, esquemas de herramientas, streaming, traspasos, límites de pasos y trazas. El SDK resuelve todo eso con primitivas probadas y te deja escribir el resto en Python normal. Frente a alternativas más tipadas como Pydantic AI, el Agents SDK apuesta por la mínima ceremonia y por atarse poco al proveedor.
| Enfoque | Ventaja | Inconveniente |
|---|---|---|
| Bucle a mano | Control total, sin dependencias | Reescribes reintentos, herramientas y trazas |
| OpenAI Agents SDK | Pocas primitivas, trazado de serie, más de 100 LLMs | Otra dependencia y sus convenciones |
| Framework pesado | Muchas prestaciones listas | Curva de aprendizaje y abstracciones propias |
La regla práctica: empieza a mano para aprender, y adopta el SDK en cuanto necesites herramientas, varios agentes o depurar en serio.
Preguntas frecuentes
¿El OpenAI Agents SDK solo funciona con modelos de OpenAI?
No. Aunque está pensado para la API de Responses y de Chat Completions de OpenAI, es compatible con más de 100 LLMs a través del proveedor LiteLLM, incluidos modelos abiertos que ejecutas en tu propia máquina con Ollama o vLLM. Cambias el modelo de un agente sin tocar el resto del código, así que puedes prototipar con un modelo potente y luego mover parte del trabajo a uno más barato o local.
¿En qué se diferencia de Swarm?
Swarm era un experimento educativo de octubre de 2024, con menos de 1.000 líneas y un aviso de que no era apto para producción. El Agents SDK toma sus ideas (agentes y traspasos) y las convierte en una biblioteca mantenida, con barreras de seguridad, sesiones de memoria, trazado integrado, soporte multiproveedor y versiones publicadas con regularidad. Si usabas Swarm, el SDK es su sucesor recomendado.
¿Necesito saber async para usarlo?
No para empezar. Runner.run_sync ejecuta el agente de forma síncrona y basta para scripts y pruebas. Cuando montes un servicio que atienda varias peticiones a la vez, te interesará Runner.run con await y Runner.run_streamed para respuestas en streaming, pero son el mismo API con la variante asíncrona.
Conclusión
El OpenAI Agents SDK acierta al ofrecer pocas primitivas bien elegidas (agentes, herramientas, traspasos, barreras, sesiones y trazado) sobre Python normal, en lugar de un lenguaje de flujos que memorizar. Es la evolución seria de Swarm, no te ata a OpenAI y trae observabilidad de fábrica, lo que lo hace un buen punto de entrada para construir agentes reales. El siguiente paso natural es escribir el agente mínimo de esta guía y, cuando quieras coordinar varios, pasar a los patrones de sistemas multiagente.
