OpenAI Agents SDK en Python: tutorial paso a paso para crear tu primer agente IA (2026)

Crear un agente de IA en 2026 ya no requiere semanas de trabajo. OpenAI publicó la Practical Guide to Building Agents en junio de 2026 y, junto con ella, el framework oficial OpenAI Agents SDK: una librería en Python pensada para construir agentes con GPT-5.5, GPT-5.4 y GPT-4o-mini en pocas líneas. Si conoces openai, conoces ya el 80% del SDK; lo demás son tres abstracciones nuevas (Agent, Runner y handoffs) y un dashboard de tracing que cambia la forma de depurar.

En este tutorial vas a crear, desde cero, tu primer agente con OpenAI Agents SDK: registro de API key, instalación con pip install openai-agents, primer Agent, tools con function calling, Runner para ejecutarlo, coordinación multi-agente con handoffs, guardrails y tracing en el dashboard de OpenAI. Todo el código está probado contra la versión publicada en junio de 2026 y orientado a producción real.

¿Qué es OpenAI Agents SDK y por qué usarlo en 2026?

OpenAI Agents SDK es el framework oficial de OpenAI para construir agentes con sus modelos GPT, lanzado en 2026 como evolución de los Assistants v3. Donde antes había una API REST con threads y runs, ahora hay una abstracción Python limpia con tres conceptos:

• Agent: un modelo (GPT-5.5, 5.4 o 4o-mini) con un system prompt, una lista de tools y un conjunto de handoffs.
• Runner: el motor que ejecuta el bucle agente (planificar, llamar tool, observar resultado, decidir siguiente paso).
• Handoffs: transferencias controladas entre agentes especializados.

OpenAI publicó la Practical Guide to Building Agents en junio de 2026, una guía oficial gratuita que recomienda este SDK como punto de entrada para cualquier equipo que quiera meter LLMs en producción sin reescribir el bucle de tool use cada vez. Compite directamente con la combinación Claude API + MCP de Anthropic y con Vertex AI Agents de Google.

¿Por qué adoptarlo en tu próximo proyecto?

• Setup en 30 segundos: pip install openai-agents y ya tienes el SDK funcional.
• Tracing built-in: cada ejecución aparece en el dashboard de OpenAI, con timeline de tool calls, tokens y latencias.
• Multi-agente nativo: handoffs declarativos sin tener que orquestar manualmente colas o eventos.
• Guardrails de fábrica: validaciones de input/output sin escribir código extra.
• 5 dólares gratis: OpenAI ofrece 5 dólares de créditos gratuitos al registrarse en platform.openai.com, suficientes para construir y probar varios agentes.

Requisitos previos

Antes de instalar nada, asegúrate de cumplir estos requisitos. Son mínimos pero innegociables:

• Python 3.10 o superior: el SDK usa tipado moderno y sintaxis match/case.
• Cuenta en platform.openai.com con API key y créditos (los 5 dólares gratuitos del registro sirven para todo el tutorial).
• Conocimientos básicos de Python: funciones, decoradores, async/await y manejo de errores.
• Editor con soporte de tipado: VS Code, Cursor o PyCharm. Te ahorrará muchos bugs.
• Terminal Unix-like: macOS, Linux o WSL2 en Windows.

Si todavía no tienes un flujo de desarrollo con LLMs, te recomiendo leer primero la guía de frameworks de agentes autónomos 2026 para contexto general antes de profundizar en este SDK concreto.

Paso 1: Crear cuenta OpenAI y obtener tu API key

1. Visita platform.openai.com y regístrate con tu email. Verifica el número de teléfono cuando te lo pida (necesario para activar la API).
2. Acepta el acreedito automático de 5 dólares de créditos gratuitos (válidos 3 meses).
3. Ve a Dashboard → API Keys → Create new secret key. Dale un nombre descriptivo, por ejemplo agentes-sdk-dev.
4. Copia la clave (empieza por sk-proj-). No volverás a verla. Guárdala en un gestor de secretos como 1Password o Bitwarden.
5. Exporta la clave como variable de entorno:

export OPENAI_API_KEY="sk-proj-tu-clave-aqui"

# Para persistirla en cada sesión añade la línea a tu shell:
echo 'export OPENAI_API_KEY="sk-proj-tu-clave-aqui"' >> ~/.zshrc
source ~/.zshrc

Paso 2: Instalar el SDK con pip install openai-agents

Crea un entorno virtual aislado para no contaminar el sistema. Después instala el SDK y dependencias auxiliares:

mkdir mi-agente-openai && cd mi-agente-openai
python3 -m venv .venv
source .venv/bin/activate

# Instalación principal
pip install openai-agents python-dotenv

# Verifica versión instalada
python -c "import agents; print(agents.__version__)"

El paquete openai-agents incluye internamente al cliente openai y expone los módulos agents (Agent, Runner, handoff, guardrail) y agents.tracing. No necesitas instalarlos por separado.

Crea un archivo .env en la raíz del proyecto y añádelo al .gitignore:

OPENAI_API_KEY=sk-proj-tu-clave-aqui
OPENAI_MODEL=gpt-5.5

Paso 3: Tu primer Agent

Crea el archivo primer_agente.py. Vamos a definir un Agent con system prompt claro y ejecutarlo. Por defecto recomienda GPT-5.5 para máxima potencia o GPT-4o-mini para coste reducido:

import os
import asyncio
from dotenv import load_dotenv
from agents import Agent, Runner

load_dotenv()

MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.5")

asistente = Agent(
    name="asistente-tecnico",
    model=MODEL,
    instructions=(
        "Eres un asistente experto en Python. "
        "Responde de forma concisa y didáctica, con ejemplos cortos."
    ),
)

async def main() -> None:
    resultado = await Runner.run(
        asistente,
        input="Explícame qué es un agente IA en tres frases.",
    )
    print(resultado.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Ejecuta con python primer_agente.py. En menos de 4 segundos verás la respuesta. Acabas de crear, ejecutar y consumir tu primer agente con OpenAI Agents SDK. Si quieres bajar coste para iterar, cambia OPENAI_MODEL a gpt-4o-mini: rapidísimo y barato.

Paso 4: Añadir tools con function calling

Un Agent aislado solo genera texto. La gracia llega cuando le das tools que puede invocar para actuar sobre el mundo. El SDK abstrae el JSON Schema gracias al decorador @function_tool: tipa la función con Python normal y el SDK genera el esquema automáticamente.

from agents import Agent, Runner, function_tool
import asyncio
import httpx

@function_tool
def obtener_clima(ciudad: str, unidad: str = "celsius") -> dict:
    """Devuelve el clima actual de una ciudad concreta.

    Args:
        ciudad: Nombre de la ciudad (ej. Bilbao).
        unidad: 'celsius' o 'fahrenheit'.
    """
    # En producción llamarías a OpenWeather u otra API real
    return {
        "ciudad": ciudad,
        "temperatura": 24 if unidad == "celsius" else 75,
        "unidad": unidad,
        "estado": "soleado",
    }

@function_tool
def buscar_wikipedia(termino: str) -> str:
    """Devuelve un resumen corto de Wikipedia en español."""
    url = f"https://es.wikipedia.org/api/rest_v1/page/summary/{termino}"
    r = httpx.get(url, timeout=10)
    r.raise_for_status()
    return r.json().get("extract", "Sin resultados.")

asistente = Agent(
    name="asistente-acciones",
    model="gpt-5.5",
    instructions="Usa las tools disponibles cuando necesites datos en tiempo real.",
    tools=[obtener_clima, buscar_wikipedia],
)

async def main() -> None:
    r = await Runner.run(asistente, input="¿Qué tiempo hace en Bilbao y qué es el Athletic Club?")
    print(r.final_output)

asyncio.run(main())

El SDK gestiona automáticamente el bucle: el modelo decide qué tool invocar, la ejecuta, le pasa el resultado al modelo y este redacta la respuesta final. No tienes que escribir while stop_reason == "tool_use" a mano como sí ocurre con la API REST cruda.

Paso 5: Ejecutar el agente con Runner

Runner es el motor del SDK. Soporta tres modos de ejecución:

• Runner.run(agent, input): asíncrono, devuelve RunResult al terminar. Ideal para scripts y backends async.
• Runner.run_sync(agent, input): síncrono, conveniente para notebooks Jupyter y scripts simples.
• Runner.run_streamed(agent, input): streaming de eventos (tokens, tool calls, handoffs) en tiempo real. Imprescindible para UIs de chat.

Ejemplo de streaming, perfecto para construir un chat:

from agents import Runner

async def chat_streaming(agent, prompt: str) -> None:
    async for event in Runner.run_streamed(agent, input=prompt):
        if event.type == "token":
            print(event.delta, end="", flush=True)
        elif event.type == "tool_call":
            print(f"\n[tool] {event.name} → ejecutando…")
        elif event.type == "final":
            print("\n[fin]")

Otros parámetros útiles: max_turns para limitar iteraciones del bucle agente (recomendado 12), context para inyectar datos del usuario y previous_response_id para mantener memoria entre ejecuciones.

Paso 6: Multi-agente con handoffs

Un agente monolítico no escala: a más tools, más confusión y más coste. La solución son los handoffs: agentes especializados a los que el agente principal puede delegar cuando detecta que la tarea les corresponde. Es la pieza estrella del SDK.

from agents import Agent, Runner, function_tool
import asyncio

@function_tool
def reembolso(pedido_id: str) -> str:
    return f"Reembolso emitido para pedido {pedido_id}."

@function_tool
def estado_envio(pedido_id: str) -> str:
    return f"Pedido {pedido_id}: en reparto, llega mañana."

agente_reembolsos = Agent(
    name="reembolsos",
    model="gpt-5.4",
    instructions="Procesa reembolsos. Pide siempre el ID del pedido.",
    tools=[reembolso],
)

agente_envios = Agent(
    name="envios",
    model="gpt-4o-mini",
    instructions="Consulta el estado de envío del pedido.",
    tools=[estado_envio],
)

triage = Agent(
    name="triage",
    model="gpt-5.5",
    instructions=(
        "Eres el primer contacto de soporte. "
        "Si el usuario pide un reembolso, haz handoff al agente 'reembolsos'. "
        "Si pregunta por estado de envío, haz handoff al agente 'envios'. "
        "En otros casos responde tú directamente."
    ),
    handoffs=[agente_reembolsos, agente_envios],
)

async def main() -> None:
    r = await Runner.run(triage, input="Necesito un reembolso del pedido A-1029.")
    print(r.final_output)
    print("agente final:", r.last_agent.name)

asyncio.run(main())

El triage detecta la intención, transfiere el control al agente reembolsos y este ejecuta su tool. El SDK registra la trazabilidad completa en el dashboard. Esta es la base de cualquier asistente multi-skill: triage + n especialistas.

Si quieres comparar este patrón con la arquitectura de Anthropic, lee el análisis de workflows dinámicos multi-agente de Claude Opus 4.8.

Paso 7: Añadir guardrails y tracing

Los guardrails son validaciones que se ejecutan antes y después del agente. Sirven para evitar prompt injection, contenidos no deseados o datos fuera de dominio. Ejemplo de input guardrail:

from agents import Agent, Runner, input_guardrail, GuardrailFunctionOutput
from pydantic import BaseModel
import asyncio

class ChequeoTopico(BaseModel):
    es_relevante: bool
    razon: str

clasificador = Agent(
    name="clasificador",
    model="gpt-4o-mini",
    instructions="Decide si la consulta trata sobre soporte de pedidos.",
    output_type=ChequeoTopico,
)

@input_guardrail
async def filtro_topico(ctx, agent, input_text):
    r = await Runner.run(clasificador, input=input_text)
    salida: ChequeoTopico = r.final_output
    return GuardrailFunctionOutput(
        output_info=salida.razon,
        tripwire_triggered=not salida.es_relevante,
    )

soporte = Agent(
    name="soporte",
    model="gpt-5.5",
    instructions="Atiende solo consultas sobre pedidos.",
    input_guardrails=[filtro_topico],
)

async def main() -> None:
    try:
        await Runner.run(soporte, input="¿Quién ganará el balón de oro 2026?")
    except Exception as e:
        print("Bloqueado por guardrail:", e)

asyncio.run(main())

Cuando el clasificador detecta que la consulta no pertenece al dominio, dispara la tripwire y el SDK aborta antes de gastar tokens del modelo caro. Es una técnica brutal para controlar coste y comportamiento.

El tracing, por su parte, viene activo por defecto. Cada ejecución de Runner.run aparece en platform.openai.com → Logs → Traces con todo el timeline: prompts, respuestas, tool calls, handoffs, latencias y tokens. Para añadir spans personalizados:

from agents import trace

with trace("flujo-completo"):
    r1 = await Runner.run(triage, input="Reembolso A-1029")
    r2 = await Runner.run(triage, input="Estado envío B-7755")

Si necesitas mandar trazas a una herramienta externa como Langfuse o Weights & Biases, el SDK exporta hooks BatchTraceProcessor compatibles con OpenTelemetry.

Comparativa: OpenAI Agents SDK vs Claude API+MCP vs Google Vertex AI Agents

¿Qué SDK elegir? Depende de modelo, coste, ecosistema y vendor lock-in. Esta tabla resume las diferencias clave en junio de 2026:

Resumen práctico: si ya pagas OpenAI, este SDK es el camino más rápido a producción. Si te importa interoperabilidad de tools, lee también la guía MCP. Y si quieres una visión global del mercado, no te pierdas la guía de frameworks de agentes 2026.

Casos de uso reales

Lo que ya están construyendo equipos con OpenAI Agents SDK en producción:

• Customer support multi-skill: triage + reembolsos + envíos + escalado humano, todo con handoffs.
• Code review automatizado: agente que lee diffs de GitHub, busca patrones problemáticos y comenta en el PR, similar a Cursor 3 Composer 2.
• Agentes de investigación: búsqueda web + lectura de PDFs + síntesis con citas. Útil para analistas y periodistas.
• Automatización ofimática: lectura de Gmail, creación de eventos en Calendar y resumen en Slack.
• Asistente de ventas: lookup en CRM + generación de propuestas + envío firmado por email.
• Tutor educativo: agente que adapta dificultad según respuestas del estudiante y entrega feedback en streaming.

En todos estos casos, el patrón es el mismo: triage en GPT-5.5, especialistas en GPT-5.4 o 4o-mini, tools acotadas y guardrails de dominio. La curva de complejidad la absorbe el SDK.

Errores comunes y debugging

• 401 Invalid API key: revisa echo $OPENAI_API_KEY y comprueba que la clave no haya sido revocada.
• InsufficientQuotaError: agotaste los 5 dólares iniciales. Recarga saldo en Billing.
• RateLimitError: alcanzaste el tier RPM del proyecto. Sube de tier o usa tenacity para reintentos exponenciales.
• Tool no se invoca nunca: revisa que la docstring describa claramente cuándo usarla. Los modelos deciden por descripción.
• Bucle infinito: define max_turns=12 en Runner.run y revisa el trace para detectar dónde se atasca.
• Handoff no transfiere: el system prompt del triage debe nombrar explícitamente al agente destino.
• Trace vacío: asegúrate de no haber desactivado tracing con RunConfig(tracing_disabled=True).

Material recomendado para programar con IA

Estos libros y equipos forman la base de un flujo serio de desarrollo de agentes con OpenAI Agents SDK. Enlaces de afiliado Amazon:

• Libro ChatGPT para Hackers y Programadores: patrones avanzados de uso de la API OpenAI aplicables directamente al SDK de agentes.
• Libro El arte de la Ingeniería de Prompts con ChatGPT: aprenderás a redactar system prompts y descripciones de tools eficaces.
• Libro ChatGPT: Tus primeros prompts con 100 ejemplos: ideal para iterar sobre el contenido de las instructions de tus agentes.
• Libro Aprende Claude Code CLI: aunque sea de Anthropic, los patrones de bucle agente y tool calling son universales y aplican al SDK de OpenAI.
• Mac mini M4 16GB/256 SSD: equipo silencioso y rápido para desarrollar agentes en local consumiendo solo la API.
• Mac mini M4 16GB/512 SSD: mismo equipo con más SSD para guardar datasets, traces y modelos locales de comparativa.
• BenQ RD280U: monitor 4K específico para programación, con modos de lectura ideales para revisar trazas extensas en el dashboard.
• Dell S2725QS: monitor 27" 4K 120Hz polivalente, gran opción para combinar código por la mañana y gaming por la tarde.

Conclusión

Con menos de 80 líneas de Python ya tienes un sistema multi-agente con GPT-5.5, tools auto-generadas, handoffs, guardrails y tracing en dashboard. Esto, en 2024, requería semanas. Hoy lo haces en una tarde con OpenAI Agents SDK.

El siguiente paso es elegir un caso de uso real y limitarlo: un solo dominio, dos o tres tools, un solo agente especialista. Mide latencia, coste y precisión, ajusta el system prompt, añade evaluaciones automatizadas con datasets y solo entonces escala a multi-agente. Y, sobre todo, lee la Practical Guide to Building Agents de OpenAI: es la mejor inversión de una hora que harás este mes.

Para profundizar, te recomendamos también nuestra guía análoga con Claude API y MCP, el tutorial de Claude Code CLI y la guía de GPT-5.5 Instant para reducir alucinaciones.

Preguntas frecuentes