Introducción al OpenAI Agents SDK

Qué es el OpenAI Agents SDK

El OpenAI Agents SDK es una biblioteca oficial de Python, publicada por OpenAI en 2025 y estabilizada en 2026, pensada para construir agentes que combinan un modelo de lenguaje con instrucciones, herramientas y orquestación entre agentes. Se apoya sobre el cliente oficial de OpenAI y encapsula patrones habituales como el bucle agéntico, el manejo de tool calls, los handoffs entre agentes y la observabilidad con tracing.

No sustituye por completo a las APIs de chat o responses "planas". Donde encaja bien es en escenarios donde el modelo necesita decidir cuándo llamar a una herramienta, cuándo delegar el control a otro agente especializado y cuándo terminar con una respuesta final. La API unifica estos patrones con abstracciones claras: Agent, Runner, Tool, Handoff y Guardrail.

El bucle agéntico gestionado por Runner permite que el modelo llame a herramientas, transfiera el control a otro agente o emita la respuesta terminal. El SDK itera hasta llegar a la salida final sin que el desarrollador tenga que orquestarlo a mano.

Instalación y configuración inicial

La biblioteca se distribuye en PyPI bajo el nombre openai-agents. La instalación en un entorno virtual es el paso recomendado:

python -m venv .venv
source .venv/bin/activate
pip install openai-agents

El SDK necesita una API key de OpenAI válida. El cliente la detecta automáticamente si está en la variable de entorno OPENAI_API_KEY. En aplicaciones profesionales se gestiona con dotenv en local y con secretos del orquestador (Kubernetes Secrets, Azure Key Vault, AWS Secrets Manager) en los entornos desplegados.

export OPENAI_API_KEY="sk-proj-..."

Primer agente mínimo

La clase central es Agent. Sus argumentos principales son:

• name: identificador legible, útil en logs y en tracing.
• instructions: comportamiento esperado, equivalente a un system prompt reforzado.
• model: modelo que ejecutará las llamadas, por ejemplo gpt-5.1 en 2026.

La ejecución síncrona más simple llama a Runner.run_sync pasando el agente y el input del usuario:

from agents import Agent, Runner

agent = Agent(
    name="Asistente de soporte",
    instructions=(
        "Respondes en español de forma breve y profesional. "
        "Si la pregunta no es de soporte técnico, indica que derivas al equipo comercial."
    ),
    model="gpt-5.1",
)

result = Runner.run_sync(
    agent,
    "Explica qué es una API REST en una frase corta."
)

print(result.final_output)

El objeto result contiene final_output con la respuesta terminal, junto con metadatos del trazado: pasos intermedios, llamadas a herramientas, tokens consumidos y tiempos. En flujos con herramientas o handoffs, Runner.run_sync gestiona las iteraciones hasta alcanzar una respuesta terminal.

Para aplicaciones asíncronas (APIs FastAPI, workers) se utiliza Runner.run con await:

import asyncio
from agents import Agent, Runner

async def main():
    agent = Agent(
        name="Resumidor",
        instructions="Resumes textos tecnicos en tres frases.",
        model="gpt-5.1",
    )
    result = await Runner.run(agent, texto_largo)
    print(result.final_output)

asyncio.run(main())

El SDK incorpora tracing de serie. Cada ejecución deja un registro con los pasos del bucle agéntico que se puede inspeccionar en el dashboard de OpenAI o exportar a herramientas propias de observabilidad.

Dónde encaja en una arquitectura B2B

El Agents SDK brilla en tres tipos de casos dentro de arquitecturas empresariales:

• Asistentes internos con acceso a datos corporativos: un agente con herramientas que consultan CRM, ERP o catálogos internos puede responder preguntas operativas de empleados sin redirigirles a cada sistema.
• Pipelines multi-paso con agentes especializados: un agente investiga, otro redacta y un tercero revisa. El Runner orquesta los handoffs y el resultado final es de mayor calidad que con un agente monolítico.
• Automatización de procesos: un agente con tool calls conectadas a acciones (crear ticket, enviar email, actualizar registro) automatiza flujos donde el modelo necesita decidir qué hacer en cada paso.

En las lecciones siguientes se profundiza en handoffs para delegar entre agentes, guardrails para validar entradas y salidas, y el diseño de herramientas robustas que el modelo pueda invocar con seguridad.

Caso B2B: triage de incidencias en banca

Un banco digital mediano implementa con el Agents SDK un triage automático de las incidencias que llegan por el chat del área de clientes. Un agente de clasificación lee el mensaje inicial y decide si es consulta general, problema técnico o caso sensible; si es técnico, hace un handoff a un agente especializado con herramientas que consultan el estado del sistema interno; si es sensible (fraude o bloqueo de tarjeta), deriva a un agente con guardrails estrictos que genera un ticket de alta prioridad y escala a un agente humano. El tracing del SDK permite al equipo de cumplimiento auditar cada interacción y asegurar que los casos sensibles siempre terminan en manos de un operador.