OpenAI Agents SDK: Multi-Agent en Python (Guía 2026)

📋 TL;DR

El OpenAI Agents SDK es el framework oficial de OpenAI para construir aplicaciones agénticas en Python: ligero, con pocas abstracciones y listo para producción. En esta guía aprenderás a instalar el OpenAI Agents SDK, crear agentes con handoffs y agents-as-tools, usar Ollama como backend local y comparar el SDK con AutoGen y CrewAI para elegir la opción adecuada en tu homelab o proyecto.

Lo que conseguirás:

• ✅ Instalar el OpenAI Agents SDK y ejecutar tu primer agente en minutos
• ✅ Configurar handoffs (triage → especialistas) y agents as tools (manager + especialistas)
• ✅ Conectar Ollama o cualquier API compatible OpenAI con base_url
• ✅ Entender cuándo usar handoffs frente a agents-as-tools
• ✅ Resolver errores típicos (tracing, Responses API, Ollama)

Tiempo de lectura: ~20 minutos | Nivel: Intermedio (conocimientos básicos de Python y de APIs LLM recomendados)

—

Tabla de Contenidos

1. Introducción
2. ¿Qué es el OpenAI Agents SDK?
3. Instalación y primer agente
4. Patrones multi-agent: Handoffs y Agents as Tools
5. Integración con Ollama y LocalAI
6. MCP, tools y guardrails
7. Ejemplos prácticos
8. Comparativa OpenAI Agents SDK vs AutoGen vs CrewAI
9. Troubleshooting común
10. 📦 Descargar Ejemplos
11. Enlaces Relacionados
12. Preguntas Frecuentes
13. Conclusión

—

> 📅 Última actualización: Marzo 2026

> ✅ Verificado con: openai-agents 0.10.x, Ollama 0.x

> 🔄 Próxima revisión: Junio 2026

—

Introducción

Orquestar varios agentes de IA —decidir quién hace qué y cómo se pasan el control o los resultados— requiere un framework que equilibre simplicidad y potencia. Si ya usas AutoGen, CrewAI o MCP y quieres probar el enfoque oficial de OpenAI con pocas abstracciones y soporte para multi-agent, el OpenAI Agents SDK (paquete openai-agents en PyPI) es una opción sólida para 2026.

El problema: Coordinar múltiples agentes (un triage que enruta, especialistas que responden, o un manager que combina salidas de varios) implica gestionar flujo, estado y backend LLM. Hacerlo a mano con scripts propios puede ser frágil.

La solución: El OpenAI Agents SDK ofrece tres primitivas clave: Agents (LLMs con instrucciones y herramientas), Handoffs (delegar la conversación a un especialista que se convierte en el agente activo) y Agents as tools (un manager llama a especialistas como herramientas y mantiene el control). Además incluye guardrails, sesiones, tracing y soporte MCP. Funciona con la API de OpenAI y, configurando un cliente custom, con Ollama o cualquier endpoint compatible OpenAI.

En esta guía aprenderás:

• Qué es el OpenAI Agents SDK y en qué se diferencia de AutoGen y CrewAI
• Cómo instalar el SDK y ejecutar un agente (sync y async)
• Cómo definir handoffs (triage → especialistas) y agents-as-tools
• Cómo usar Ollama como backend con base_url y desactivar tracing
• Ejemplos prácticos: tools, handoffs, Ollama
• Comparativa OpenAI Agents SDK vs AutoGen vs CrewAI
• Troubleshooting: tracing 401, Responses API, structured outputs

Tanto si quieres multi-agent en la nube como en homelab con Ollama, esta guía te llevará de cero a tener flujos con el OpenAI Agents SDK operativos.

—

¿Qué es el OpenAI Agents SDK?

El OpenAI Agents SDK es un framework ligero y orientado a producción para construir aplicaciones agénticas en Python. Sustituye conceptualmente a Swarm (experimental) y se instala con pip install openai-agents. Está diseñado con dos principios: funcionar bien out of the box y exponer pocas primitivas para aprender rápido.

Primitivas principales

1. Agents: Un agente es un LLM con nombre, instrucciones y opcionalmente herramientas (function tools, MCP, u otros agentes como tools).
2. Handoffs: Un agente puede “pasar” la conversación a otro; el agente de destino se convierte en el activo para el resto del turno. Ideal para triage → especialistas.
3. Agents as tools: Un agente manager invoca a otros agentes vía Agent.as_tool(). El manager conserva el control y combina resultados; los especialistas no toman la conversación.
4. Guardrails: Validación de entradas y salidas en paralelo a la ejecución; fallo rápido si no pasan.
5. Sessions: Capa de memoria persistente dentro del loop del agente.
6. Tracing: Integrado para visualizar y depurar flujos en el OpenAI Dashboard (o desactivarlo con Ollama).

Handoffs vs Agents as tools

Puedes combinar ambos: un triage hace handoff a un especialista, y ese especialista usa a su vez otros agentes como tools para subtareas. La documentación oficial incluye ejemplos de routing (handoffs) y de manager con agents-as-tools en el quickstart y en la sección de multi-agent.

—

Instalación y primer agente

Requisito: Python 3.10+. Se recomienda usar un entorno virtual para no mezclar dependencias con el resto del sistema; el SDK instala openai y otras dependencias necesarias para tracing y modelos (por ejemplo, requests, Pydantic).

python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
pip install openai-agents

Para usar la API de OpenAI necesitas OPENAI_API_KEY. Para Ollama no hace falta (más adelante verás el cliente custom).

Hello world

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.")
print(result.final_output)

Agente con function_tool

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."

agent = Agent(
    name="History Tutor",
    instructions="Answer history questions. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)

async def main():
    result = await Runner.run(agent, "Tell me something surprising about ancient life.")
    print(result.final_output)

asyncio.run(main())

El SDK genera el esquema de la herramienta a partir del tipo de retorno y el docstring; puedes usar Pydantic para validación más estricta. Las function tools se invocan automáticamente cuando el LLM decide usarlas; el resultado se devuelve al agente y el loop continúa hasta que el agente produce la respuesta final sin más llamadas a tools.

—

Patrones multi-agent: Handoffs y Agents as Tools

Handoffs: triage → especialistas

Defines agentes especialistas con handoff_description (el LLM de triage usa esto para enrutar) y un agente triage con handoffs=[...]. El Runner ejecuta el triage; cuando decide hacer handoff, el especialista pasa a ser el agente activo.

from agents import Agent, Runner

history_tutor = Agent(
    name="History Tutor",
    handoff_description="Specialist for historical questions",
    instructions="Answer history questions clearly and concisely.",
)
math_tutor = Agent(
    name="Math Tutor",
    handoff_description="Specialist for math questions",
    instructions="Explain math step by step with a short worked example.",
)
triage = Agent(
    name="Triage Agent",
    instructions="Route each question to the right specialist: history or math.",
    handoffs=[history_tutor, math_tutor],
)

result = Runner.run_sync(triage, "Who was the first president of the United States?")
print(result.final_output)
print(f"Answered by: {result.last_agent.name}")

Agents as tools (manager + especialistas)

En lugar de handoff, el manager puede invocar agentes como herramientas. El manager mantiene la conversación y combina las respuestas; útil cuando quieres una única respuesta sintética o guardrails en un solo lugar. Consulta la documentación de Tools para Agent.as_tool().

—

Integración con Ollama y LocalAI

El OpenAI Agents SDK usa por defecto la API de OpenAI. Para Ollama u otros backends compatibles con la API Chat Completions de OpenAI, configuras un cliente con base_url y opcionalmente lo fijas como cliente por defecto.

from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_client, set_tracing_disabled

set_tracing_disabled(True)  # Ollama no usa API key de OpenAI; evita errores de tracing

client = AsyncOpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)
set_default_openai_client(client)

agent = Agent(
    name="Local",
    instructions="You are a helpful assistant.",
    model="llama3.2",  # nombre de ollama list
)
result = Runner.run_sync(agent, "Say hello in one sentence.")
print(result.final_output)

Requisitos: Ollama en marcha (ollama serve) y el modelo descargado (ollama pull llama3.2). Para LocalAI, cambia base_url (por ejemplo http://localhost:8080/v1) y el nombre del modelo.

Alternativa con LiteLLM: Si prefieres no configurar el cliente a mano, puedes instalar pip install "openai-agents[litellm]" y usar el prefijo litellm/ para el modelo, por ejemplo model="litellm/ollama/llama3.2". LiteLLM traduce las llamadas al backend que elijas (Ollama, Anthropic, etc.). Sigue siendo recomendable set_tracing_disabled(True) si no usas API key de OpenAI.

Nota: Muchos backends solo soportan Chat Completions, no la Responses API. Si ves 404 u otros errores, usa OpenAIChatCompletionsModel con tu cliente o set_default_openai_api("chat_completions") si configuras todo por variables de entorno.

—

MCP, tools y guardrails

• MCP (Model Context Protocol): El OpenAI Agents SDK integra servidores MCP como herramientas; se configuran y se usan igual que las function tools. Así puedes exponer a tus agentes contexto (archivos, bases de conocimiento) o acciones (APIs, scripts) definidas en servidores MCP. Si ya usas MCP con Cursor u otras herramientas, reutilizar esos servidores en el SDK es directo. En el blog tienes una guía dedicada a MCP para conectar herramientas con IA.

• Guardrails: Permiten validar entradas y salidas en paralelo a la ejecución del agente; si un check falla, el flujo puede detenerse (fail fast). Útil para cumplir políticas de contenido, formato o seguridad sin mezclar esa lógica con las instrucciones del agente. Revisa la documentación de Guardrails.

• Sessions: Para mantener contexto entre turnos (multi-turn conversation), puedes usar la capa de sesiones del SDK o pasar explícitamente result.to_input_list() al siguiente Runner.run. Las sesiones simplifican el estado de la conversación cuando el usuario hace varias preguntas seguidas. Ver Sessions y Running agents.

—

Ejemplos prácticos

Varios modelos en un mismo flujo

Puedes asignar un modelo distinto a cada agente (por ejemplo triage con un modelo barato y especialistas con uno más capaz), pasando model="nombre" o un RunConfig(model=...) a nivel de ejecución:

from agents import Agent, RunConfig, Runner

agent = Agent(name="Assistant", instructions="You're helpful.")
result = Runner.run_sync(
    agent,
    "Explain recursion in one paragraph.",
    run_config=RunConfig(model="gpt-4.1"),
)

Con Ollama, cada agente puede usar un modelo distinto (por ejemplo llama3.2 para triage y mistral para un especialista) si defines un modelo por agente. Ver Models y “Advanced model selection and mixing”.

Agents as tools (manager que combina especialistas)

Cuando quieres que un único agente “manager” posea la respuesta final y aplique guardrails en un solo lugar, usa agents-as-tools en lugar de handoffs. El manager recibe la pregunta del usuario, llama a uno o más agentes especialistas como herramientas (por ejemplo un agente “buscador” y otro “resumidor”), y sintetiza la respuesta. La documentación en Tools explica cómo convertir un agente en herramienta con Agent.as_tool() y pasarlo en la lista tools del manager.

Orquestación por código

Además de dejar que el LLM decida (handoffs, tools), puedes orquestar por código: ejecutar agentes en paralelo con asyncio.gather, encadenar salidas de uno como entrada del siguiente, o usar un loop con un agente evaluador hasta que se cumplan criterios. El repositorio incluye ejemplos en examples/agent_patterns/ (por ejemplo parallel agents, portfolio collaboration). Esta opción hace el flujo más determinista en coste, latencia y comportamiento.

—

Comparativa OpenAI Agents SDK vs AutoGen vs CrewAI

Elige el OpenAI Agents SDK cuando quieras el stack oficial de OpenAI, pocas abstracciones y handoffs/agents-as-tools claros. AutoGen encaja si valoras una interfaz no-code (AutoGen Studio) y conversación multi-agente con UserProxy. CrewAI es ideal para workflows con roles y tareas (Crew) bien definidos. Puedes usar el OpenAI Agents SDK en homelab con Ollama igual que AutoGen o CrewAI. En la práctica, muchos equipos combinan: el SDK para prototipar y probar flujos multi-agent con modelos locales, y luego refinar prompts o añadir memoria (por ejemplo con Mem0) según el caso de uso.

—

Troubleshooting común

Tracing 401 con Ollama

Al usar un cliente custom (Ollama) sin API key de OpenAI, el envío de traces puede fallar. Solución: set_tracing_disabled(True) al inicio del script.

404 o errores con proveedores no-OpenAI

El SDK usa por defecto la Responses API; muchos backends solo soportan Chat Completions. Usa OpenAIChatCompletionsModel con tu cliente o set_default_openai_api("chat_completions") si usas OPENAI_BASE_URL por entorno.

Structured outputs no soportados

Algunos backends no admiten response_format con json_schema y devuelven 400. Usa proveedores que sí lo soporten o evita structured outputs para ese modelo.

Handoff no ocurre

Revisa que cada especialista tenga un handoff_description claro y que las instrucciones del triage indiquen cuándo enrutar a cada uno.

Ollama: Connection refused

Comprueba que Ollama esté en marcha: curl http://localhost:11434/api/tags. En Docker, usa la IP del host en lugar de localhost si el script corre dentro del contenedor.

Model not found con Ollama

Usa el nombre exacto que devuelve ollama list (por ejemplo llama3.2 o llama3.2:latest). No uses espacios ni rutas; solo el identificador del modelo.

Respuestas lentas con Ollama

En homelab, usar una GPU acelera mucho la inferencia. Si no tienes GPU, prueba modelos más pequeños (phi3, tinyllama) o reduce el contexto máximo que envías al modelo.

Error de structured outputs (400)

Algunos backends no admiten response_format con json_schema. El mensaje puede mencionar que response_format.type no está permitido. En ese caso usa un proveedor que sí soporte JSON schema o evita structured outputs para ese modelo.

—

📦 Descargar Ejemplos

Scripts de ejemplo (agente simple, handoffs, Ollama) están en el repositorio:

🔗 Repositorio: https://github.com/ziruelen/learningaiagents/tree/main/ia/openai-agents-sdk-multi-agent-python-guia-2026

Incluye:

• requirements.txt — openai-agents y openai
• single_agent.py — Primer agente (sync)
• handoffs_example.py — Triage → History / Math tutor
• ollama_example.py — Cliente custom con base_url a Ollama

—

Enlaces Relacionados

• MCP (Model Context Protocol): Guía para Conectar Herramientas con IA
• AutoGen: Multi-Agent en Homelab con Ollama
• CrewAI: Framework de Agentes Autónomos para Homelab
• LocalAI: Cliente OpenAI Compatible 100% Local
• Mem0: Memoria Persistente para Agentes de IA

—

Preguntas Frecuentes

¿Qué es el OpenAI Agents SDK?

Es el framework oficial de OpenAI para construir aplicaciones agénticas en Python: agentes con instrucciones y herramientas, handoffs entre agentes, agents-as-tools, guardrails, sesiones y tracing. Se instala con pip install openai-agents.

¿El OpenAI Agents SDK es gratuito?

El paquete es open source. El coste depende del uso de la API de OpenAI (modelos, tokens). Si usas Ollama u otro backend local con cliente custom, no pagas a OpenAI por las llamadas al modelo.

¿Puedo usar el OpenAI Agents SDK solo con Ollama, sin API de OpenAI?

Sí. Configura un cliente OpenAI(base_url="http://localhost:11434/v1", api_key="ollama") y set_default_openai_client(client). Desactiva tracing con set_tracing_disabled(True).

¿Qué diferencia hay entre handoffs y agents as tools?

En handoffs, un agente (p. ej. triage) delega en otro; el especialista se convierte en el agente activo y responde al usuario. En agents as tools, un manager llama a especialistas como herramientas y combina sus salidas; el manager mantiene el control de la conversación.

¿El OpenAI Agents SDK soporta MCP?

Sí. Los servidores MCP se integran como herramientas; la documentación describe cómo usarlos igual que las function tools.

¿Qué versión de Python necesito?

Python 3.10 o superior. Se recomienda un entorno virtual (venv o conda).

¿Puedo usar varios modelos en el mismo flujo del OpenAI Agents SDK?

Sí. Puedes asignar un model distinto a cada agente o usar RunConfig(model=...) a nivel de ejecución. Con Ollama, todos pueden usar el mismo cliente custom con distintos nombres de modelo.

¿Cómo desactivo el tracing cuando uso Ollama?

Llama a set_tracing_disabled(True) antes de ejecutar agentes. Así no se intenta subir traces al Dashboard de OpenAI.

¿El OpenAI Agents SDK funciona con LocalAI?

Sí. LocalAI expone una API compatible con OpenAI. Usa un cliente con base_url apuntando a tu instancia LocalAI (por ejemplo http://localhost:8080/v1) y el nombre del modelo correspondiente.

¿Puedo combinar handoffs y agents as tools?

Sí. Por ejemplo, un agente triage hace handoff a un especialista, y ese especialista puede invocar a su vez a otros agentes como tools para subtareas acotadas.

¿Qué hago si obtengo 404 con Ollama o LocalAI?

Muchos backends solo soportan la API Chat Completions. Configura el SDK para usar Chat Completions (p. ej. OpenAIChatCompletionsModel con tu cliente o set_default_openai_api("chat_completions")).

¿El OpenAI Agents SDK tiene memoria entre conversaciones?

El SDK incluye Sessions para mantener contexto dentro del loop del agente. Para memoria persistente entre sesiones de usuario, puedes integrar un sistema externo (por ejemplo Mem0).

¿Dónde veo la documentación oficial del OpenAI Agents SDK?

En https://openai.github.io/openai-agents-python/ (quickstart, multi_agent, models, tools, handoffs, sessions, guardrails). El código está en https://github.com/openai/openai-agents-python.

¿Puedo usar el OpenAI Agents SDK con voice o realtime?

Sí. El SDK incluye soporte para agentes de voz (speech-to-text, agente, text-to-speech) y para la Realtime API, con detección de interrupciones y gestión de contexto. Consulta la documentación de Voice pipeline y Realtime agents en el sitio oficial.

—

Conclusión

El OpenAI Agents SDK te permite montar flujos multi-agent en Python con pocas abstracciones: handoffs para triage y especialistas, agents-as-tools para managers que combinan resultados, y soporte para Ollama o cualquier API compatible OpenAI. Es una opción sólida si buscas el stack oficial de OpenAI o quieres integrar multi-agent en homelab con modelos locales.

Próximos pasos:

1. Instala con pip install openai-agents y ejecuta el ejemplo “Hello world”.
2. Añade un agente con handoffs (triage + dos especialistas) y prueba una pregunta.
3. Configura Ollama con set_default_openai_client y set_tracing_disabled(True).
4. Revisa los ejemplos en GitHub para scripts listos para copiar y pegar.
5. Si expones tu flujo como API (por ejemplo con FastAPI), puedes integrarlo con n8n u otras herramientas del homelab usando el nodo HTTP Request.

¿Ya usas el OpenAI Agents SDK en tus proyectos? Cuéntanos en los comentarios.