OpenAI Agents SDK: Construyendo Sistemas Multi-Agente en Python

¿Qué es el OpenAI Agents SDK?

El OpenAI Agents SDK es un framework ligero y listo para producción en Python para construir flujos de trabajo multi-agente. Evolucionó de Swarm, el prototipo experimental de orquestación multi-agente de OpenAI lanzado a finales de 2024, y se graduó a un toolkit de grado producción en marzo 2025. El SDK proporciona un conjunto mínimo de primitivos -- Agents, Handoffs y Guardrails -- que se componen en sistemas multi-agente sofisticados sin la sobrecarga de abstracciones de frameworks más pesados.

La filosofía de diseño central es abstracciones mínimas, composabilidad máxima. Un Agent es un LLM equipado con instrucciones y herramientas. Un Handoff transfiere el control entre agentes explícitamente, llevando el contexto de la conversación a través de la transición. Un Guardrail valida entradas y salidas en paralelo con la ejecución del agente. Un Runner gestiona el ciclo del agente: invoca herramientas, envía resultados al LLM y continúa hasta completar la tarea. Esta superficie pequeña significa que el SDK es rápido de aprender pero lo suficientemente potente para orquestación multi-agente en producción.

El SDK es agnóstico de proveedor en su capa de herramientas pero optimizado para modelos OpenAI. Soporta las APIs de Responses y Chat Completions de OpenAI nativamente, y a través de integraciones comunitarias puede trabajar con 100+ otros LLMs. La Responses API es la primitiva recomendada en adelante -- combina lo mejor de Chat Completions y Assistants APIs, con la Assistants API programada para deprecación el 26 de agosto de 2026 (anunciado en agosto 2025, sunset de un año). Las herramientas hosted integradas incluyen WebSearchTool para búsqueda web en tiempo real, FileSearchTool para RAG sobre archivos subidos y ComputerTool para automatización de escritorio. El SDK se distribuye en Python (openai-agents) y TypeScript (openai-agents-js), aunque las capacidades de harness y sandbox de abril 2026 son Python-first con ports a TypeScript planeados.

15 de Abril, 2026: Harness Nativo del Modelo y Ejecución en Sandbox

El 15 de abril de 2026, OpenAI lanzó la actualización más significativa del Agents SDK desde su lanzamiento inicial. La actualización introduce dos capacidades centrales: un harness nativo del modelo y ejecución nativa en sandbox. Juntas, transforman el SDK de una herramienta de orquestación ligera a una plataforma completa para tareas de agentes de largo plazo que involucran archivos, código y operaciones de sistema.

El harness nativo del modelo da a los agentes memoria configurable, orquestación consciente del sandbox y herramientas de sistema de archivos tipo Codex como primitivos estandarizados. Los agentes ahora pueden inspeccionar archivos, ejecutar comandos, editar código y trabajar en tareas multi-paso dentro de entornos controlados -- capacidades que antes requerían infraestructura personalizada construida sobre el SDK. El harness se alinea con los patrones que impulsan el producto Codex de OpenAI, llevando esos mismos primitivos al SDK abierto.

La capa de ejecución en sandbox proporciona a los agentes espacios de trabajo persistentes y aislados. Cada sandbox incluye un manifiesto de workspace (describiendo archivos, dependencias y directorios de salida), capacidades nativas del sandbox (lectura/escritura de archivos, ejecución de comandos, instalación de dependencias), soporte de snapshots y reanudación para tareas de larga duración, e integración con proveedores de almacenamiento (AWS S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2). Los desarrolladores pueden traer su propio sandbox o usar el soporte integrado para siete proveedores: Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel.

v0.18.3 (17 de julio de 2026) es la versión actual, con versiones recientes endureciendo la capa de sandbox (aislamiento de credenciales, errores de sandbox reintentables), agregando soporte de voces personalizadas en Realtime, cambiando el modelo por defecto del agente Realtime a gpt-realtime-2.1 y añadiendo spans de tracing configurables para tasks y turns. El SDK ahora funciona con más de 100 LLMs no-OpenAI via la API de Chat Completions, haciéndolo genuinamente agnóstico de proveedor. Los subagentes (agentes hijo operando bajo un agente principal para descomposición de tareas) ya están disponibles en beta para Python, mientras que el modo código (agentes que escriben y ejecutan código como parte de su flujo de trabajo) sigue planeado para Python y TypeScript.

Definición de Herramientas y Llamado de Funciones

El Agents SDK convierte cualquier función Python en herramienta de agente con generación automática de esquema. Las anotaciones de tipo definen el esquema de parámetros, el docstring se convierte en la descripción de la herramienta y Pydantic maneja la validación. Este enfoque elimina el trabajo repetitivo de escribir manualmente definiciones de JSON Schema para cada herramienta.

from agents import Agent, Runner, function_tool

@function_tool
def lookup_customer(customer_id: str) -> str:
    """Look up a customer by their ID and return their profile."""
    # Your database query logic here
    return f"Customer {customer_id}: Premium tier, active since 2024"

@function_tool
def create_ticket(title: str, priority: str = "medium") -> str:
    """Create a support ticket with the given title and priority."""
    return f"Ticket created: {title} (priority: {priority})"

support_agent = Agent(
    name="Support Agent",
    instructions="You help customers with account issues.",
    tools=[lookup_customer, create_ticket],
)

result = Runner.run_sync(support_agent, "My account is locked, ID: C-12345")

El SDK también se integra nativamente con servidores MCP. Cualquier servidor compatible con MCP puede conectarse como fuente de herramientas, permitiendo a los agentes usar el ecosistema completo de herramientas MCP (bases de datos, APIs, sistemas de archivos, servicios cloud) sin código de integración personalizado. Combinado con las function tools, esto da a los agentes acceso tanto a la lógica de negocio personalizada como al ecosistema MCP más amplio.

from agents import Agent
from agents.mcp import MCPServerStdio

# Connect to an MCP server as a tool source
mcp_server = MCPServerStdio(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
    env={"GITHUB_TOKEN": "ghp_..."}
)

agent = Agent(
    name="Code Review Agent",
    instructions="Review pull requests and provide feedback.",
    mcp_servers=[mcp_server],
)

Tracing y Depuración

El Agents SDK incluye tracing integrado habilitado por defecto. Cada ejecución de agente registra automáticamente un trace completo de generaciones LLM, llamadas de herramientas, handoffs, evaluaciones de guardrails y eventos personalizados. Estos traces se visualizan en el dashboard de Traces de OpenAI, donde puedes inspeccionar el grafo de ejecución completo de cualquier corrida de agente -- desde el mensaje inicial del usuario, a través de cada llamada de herramienta y handoff, hasta la respuesta final.

El tracing soporta personalización a múltiples niveles. Usa add_trace_processor() para agregar procesadores personalizados que reciben traces y spans para tu propio pipeline de analítica. Integra con plataformas de observabilidad de terceros como Langfuse, Arize y Datadog para monitoreo en producción. Para workers en segundo plano, llama flush_traces() al final de cada unidad de trabajo para asegurar una exportación inmediata. El tracing se puede deshabilitar globalmente vía la variable de entorno OPENAI_AGENTS_DISABLE_TRACING=1 o por ejecución vía RunConfig.tracing_disabled.

from agents import Agent, Runner, RunConfig
from agents.tracing import add_trace_processor

# Custom trace processor for your analytics
class MetricsProcessor:
    def on_trace_start(self, trace):
        print(f"Agent run started: {trace.trace_id}")

    def on_span_end(self, span):
        if span.span_type == "tool_call":
            print(f"Tool: {span.name}, latency: {span.duration_ms}ms")

add_trace_processor(MetricsProcessor())

# Disable tracing for a specific run
config = RunConfig(tracing_disabled=True)
result = Runner.run_sync(agent, "Hello", run_config=config)

Patrones Multi-Agente: Handoffs y Delegación

Los handoffs son el mecanismo principal para coordinación multi-agente. Cuando un agente define otros agentes en su lista handoffs, esos agentes quedan disponibles como herramientas que el LLM puede invocar. El modelo decide cuándo delegar basado en sus instrucciones y el contexto de la conversación. Cuando ocurre un handoff, el agente destino recibe el historial completo de la conversación y toma el control de la ejecución. Esto crea grafos de colaboración explícitos donde cada agente es un especialista.

Los patrones multi-agente comunes incluyen enrutamiento de triaje (un agente router clasifica la solicitud y hace handoff a un especialista), delegación en pipeline (los agentes hacen handoff en secuencia, cada uno agregando a la conversación) y agentes-como-herramientas (un agente llama a otro como herramienta para obtener un sub-resultado sin transferir el control). El SDK soporta los tres patrones nativamente.

from agents import Agent

# Specialist agents
billing_agent = Agent(
    name="Billing Specialist",
    instructions="Handle billing inquiries, refunds, and payment issues.",
    tools=[lookup_invoice, process_refund],
)

technical_agent = Agent(
    name="Technical Support",
    instructions="Handle technical issues, bugs, and feature questions.",
    tools=[search_docs, create_bug_report],
)

# Triage agent routes to specialists
triage_agent = Agent(
    name="Customer Support Triage",
    instructions="""You are the first point of contact.
    Route billing questions to the Billing Specialist.
    Route technical issues to Technical Support.
    Handle general inquiries yourself.""",
    handoffs=[billing_agent, technical_agent],
)

# The triage agent decides when to hand off
result = Runner.run_sync(triage_agent, "I was charged twice for my subscription")

Para orquestación más compleja involucrando sistemas multi-agente con estado compartido, el SDK proporciona RunContextWrapper -- un objeto de contexto mutable que persiste entre ejecuciones y es accesible para todas las herramientas y agentes en el pipeline. Esto permite a los agentes compartir estado, acumular resultados y coordinarse sin depender únicamente del historial de conversación. Para comunicación inter-agente entre diferentes frameworks o servicios, el protocolo A2A proporciona un estándar complementario.

Ejecución Nativa en Sandbox

La actualización de abril 2026 introdujo Sandbox Agents -- una superficie beta para ejecutar agentes en espacios de trabajo persistentes y aislados. Cada sandbox le da al agente un sistema de archivos donde puede leer y escribir archivos, instalar dependencias, ejecutar comandos y ejecutar código. Esto elimina la necesidad de que los desarrolladores construyan capas de ejecución personalizadas para agentes que trabajan con código, documentos u operaciones de sistema.

La arquitectura del sandbox usa una abstracción Manifest para describir el workspace del agente. Un manifiesto especifica qué archivos locales montar, dónde escribir salidas y cómo traer datos de proveedores de almacenamiento (S3, GCS, Azure Blob, Cloudflare R2). Los clientes de sandbox manejan el ciclo de vida: crear un workspace, montar archivos, ejecutar corridas de agente, tomar snapshots y reanudar desde snapshots para tareas de larga duración.

Siete proveedores de sandbox están soportados de fábrica: Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop y Vercel. Los desarrolladores también pueden traer su propio sandbox implementando la interfaz de cliente sandbox. El precio sigue las tarifas estándar de la API basadas en tokens y uso de herramientas -- no hay tarifas de sandbox separadas por parte de OpenAI (los costos del proveedor de sandbox aplican por separado).

Comparación: OpenAI Agents SDK vs Claude Agent SDK vs Google ADK vs LangGraph

El panorama de frameworks de agentes AI en 2026 incluye cuatro jugadores principales, cada uno con fortalezas y compromisos distintos. La elección correcta depende de tus preferencias de modelo, complejidad de orquestación y requisitos de producción.

El OpenAI Agents SDK sobresale en desarrollo rápido con abstracciones mínimas -- puedes ir de cero a un sistema multi-agente funcional en menos de 50 líneas. El Claude Agent SDK tiene el acceso más profundo al SO con herramientas integradas de archivos y shell, lo que lo convierte en la opción más fuerte para agentes de uso de computadora en dominios críticos para la seguridad. Google ADK ofrece el soporte de lenguajes más amplio e integra firmemente con Vertex AI para despliegue gestionado. LangGraph proporciona la mayor preparación para producción con checkpointing, time travel y observabilidad LangSmith, a costa de abstracciones más complejas basadas en grafos.

Patrones de Despliegue en Producción

Desplegar flujos de trabajo del Agents SDK a producción requiere abordar confiabilidad, observabilidad, gestión de costos y seguridad. El SDK provee varios mecanismos integrados, pero los despliegues en producción típicamente combinan estos con infraestructura externa.

Persistencia de Sesiones

Usa SQLiteSession con una base de datos basada en archivo para despliegues de un solo servidor, o implementa un backend de sesión personalizado (Redis, PostgreSQL) para sistemas distribuidos. OpenAIConversationsSession delega la gestión de estado a la API de OpenAI. Para conversaciones largas, habilita OpenAIResponsesCompactionSession para compactar automáticamente el historial y mantenerte dentro de los límites de tokens.

Estrategia de Guardrails

Combina en capas guardrails de entrada para aplicación de políticas de contenido (detección de PII, detección de inyección de prompts, restricción de temas) y guardrails de salida para calidad de respuesta (validación de formato, fundamentación factual, verificaciones de seguridad). Los guardrails corren en paralelo con la ejecución del agente y fallan rápidamente, minimizando el impacto en la latencia mientras aseguran la seguridad.

Control de Costos

Monitorea el uso de tokens a través de spans de tracing. Establece límites máximos de turnos en el Runner para prevenir ciclos descontrolados. Usa modelos más baratos para agentes de triaje y reserva modelos caros para agentes especialistas que necesitan máxima capacidad. La compactación de sesiones reduce el tamaño del contexto y los costos por solicitud en conversaciones largas.

Ejecución Durable con Temporal

Para flujos de trabajo críticos, integra con Temporal para ejecución durable. La integración oficial OpenAI Agents SDK + Temporal envuelve las ejecuciones de agentes en workflows de Temporal, proporcionando reintentos automáticos, manejo de timeouts y recuperación de crashes. Cada llamada de herramienta se convierte en una actividad de Temporal con su propia política de reintentos, asegurando que las tareas de agente de larga duración sobrevivan a fallos de infraestructura.

Seguridad de Sandbox

Al usar ejecución en sandbox, trata cada sandbox como un entorno no confiable. Monta solo los archivos que el agente necesita vía el manifiesto de workspace. Usa montajes de solo lectura para datos de referencia. Establece límites de recursos (CPU, memoria, disco) a nivel del proveedor de sandbox. Captura todas las salidas del sandbox para el registro de auditoría. Los snapshots habilitan checkpoint/restauración para tareas de largo plazo sin dejar estado en sandboxes en ejecución.

Primeros Pasos

El OpenAI Agents SDK requiere Python 3.10 o más reciente. Instala con pip y crea tu primer agente en pocas líneas.

# Install the SDK
pip install openai-agents

# Optional: voice support
pip install openai-agents[voice]

# Optional: Redis session backend
pip install openai-agents[redis]

# minimal_agent.py -- Your first agent
from agents import Agent, Runner

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

result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # "Paris"

Para uso en producción, configura la variable de entorno OPENAI_API_KEY y configura el tracing para exportar a tu plataforma de observabilidad. La documentación del SDK en openai.github.io/openai-agents-python cubre todos los primitivos, patrones y guías de integración en profundidad.