Cómo construir un sistema multi-agente: guía práctica del patrón supervisor

Una vez que has comprendido el concepto de "coordinar varias IA" en ¿Qué es un sistema multi-agente?, la siguiente pregunta es cómo construir uno de verdad. Este artículo recorre un proceso práctico de 5 pasos para principiantes, usando el estándar de facto de 2026: el patrón supervisor.

Antes de hablar de frameworks, el principio más importante: "construye primero con un solo agente y añade agentes de forma mínima solo cuando choques con un límite". Empezar con muchos agentes suele ser sobreingeniería. En la segunda mitad verás código mínimo y legible que sigue la documentación oficial de Claude Agent SDK y OpenAI Agents SDK, además de cómo repartir los roles y los fallos que de verdad aparecen. La misma lógica vale si conectas herramientas con MCP.

Nota: el código sigue la documentación oficial de Claude Agent SDK y OpenAI Agents SDK (revisada el 4 de octubre de 2026). Estos SDK cambian rápido, así que confirma los nombres de los parámetros en cada documentación oficial antes de ejecutar nada. Cada cifra del artículo indica su fuente.

1. Antes de construir: ¿de verdad necesitas multi?

La primera barrera no es técnica, es una cuestión de criterio. Multi-agente es potente, pero no sirve para cualquier trabajo. Si no se cumple ninguna de las siguientes condiciones, construye primero con un solo agente.

Como vimos en el artículo anterior, usar multi-agente en un proceso lineal sale caro. En un estudio de Google Research (publicado en enero de 2026, con 180 configuraciones comparadas), todas las variantes multi-agente probadas rindieron entre un 39 y un 70% peor que un solo agente en una tarea de razonamiento estrictamente secuencial (PlanCraft). El coste también sube: en su explicación de su propio agente de investigación, Anthropic indica que los agentes usan unas 4 veces más tokens que un chat, y los sistemas multi-agente unas 15 veces más. Parte de la premisa de que más agentes no significa más inteligencia.

2. La forma base: el patrón supervisor

Si dudas qué patrón usar, empezar por el patrón supervisor es la opción segura. Los principales SDK lo documentan como patrón básico. En Claude Agent SDK, el agente principal llama a subagentes con la herramienta Agent; en OpenAI Agents SDK, el equivalente es "agents as tools", donde un agente gestor llama a agentes especialistas como si fueran herramientas.

El funcionamiento es simple. El supervisor recibe la tarea global, la divide en subtareas, las delega en workers especializados y agrega los resultados. El supervisor no necesita saber cómo hace su trabajo un worker, solo a qué worker llamar y en qué formato de salida. La experticia vive en los workers.

Ojo: en OpenAI Agents SDK, un handoff significa algo más concreto que el traspaso general del paso 4: un agente de triaje traspasa la conversación misma a un especialista, que pasa a responder directamente al usuario. No queda ningún supervisor, así que trátalo como un patrón distinto (la sección 6 explica cuándo usar cada uno).

3. Constrúyelo en 5 pasos

Monta una configuración de supervisor mínima en cinco pasos. La regla práctica: empieza con 2-3 workers y añade más solo cuando la medición lo justifique.

4. Código mínimo ①: Claude Agent SDK (Python)

Primero, monta un supervisor y dos workers (un investigador y un revisor) con Claude Agent SDK de Anthropic. La preparación es solo pip install claude-agent-sdk y la variable de entorno ANTHROPIC_API_KEY (guía rápida oficial; el SDK no carga archivos .env automáticamente). El código sigue la página oficial de Subagents. Para el SDK en general, consulta nuestra guía de Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # el supervisor (agente principal)
    system_prompt=(
        "Coordinas un informe de investigación. Delega la investigación en researcher y la "
        "verificación en reviewer, y redacta tú el texto final. Al delegar, indica siempre "
        "el objetivo, el formato de salida y el alcance."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # herramientas que se ejecutan sin pedir permiso
    agents={
        "researcher": AgentDefinition(
            description="Reúne fuentes primarias. Úsalo cuando hagan falta datos o cifras.",
            prompt="Busca fuentes primarias para la pregunta y devuelve viñetas con la URL de cada fuente. No rellenes huecos con suposiciones.",
            tools=["WebSearch", "WebFetch"],  # las únicas herramientas de este rol
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Verifica borradores. Úsalo siempre antes de cerrar el texto.",
            prompt="Contrasta cada afirmación del borrador con su fuente y enumera las frases que no tengan respaldo.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # límite de idas y vueltas de toda la ejecución
    max_budget_usd=5.0,   # límite de gasto (estimación del SDK)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # los workers no crean subagentes propios
)


async def main():
    try:
        async for message in query(
            prompt="Reúne tres estadísticas oficiales sobre el uso de la IA generativa en el trabajo y escribe un informe breve",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Se detuvo antes de terminar: {error}")  # alcanzar un límite también acaba aquí


asyncio.run(main())

Cinco puntos clave:

• Los workers van en agents como entradas AgentDefinition. El supervisor lee la description de cada worker para decidir a quién llamar y cuándo, así que describe con precisión qué hace el rol y cuándo usarlo.
• Si enumeras tools, el rol solo tiene esas herramientas. Por eso el revisor no tiene herramientas de escritura. En cambio, allowed_tools enumera las herramientas que se ejecutan sin pedir permiso; no restringe nada (referencia oficial de Python).
• Pon límites en tres sitios. Un maxTurns por rol, un max_turns global y un límite de gasto con max_budget_usd. Al alcanzar un límite global, el subtipo del resultado pasa a ser error_max_turns o error_max_budget_usd y la ejecución se detiene (documentación del bucle del agente).
• Corta el anidamiento. Los subagentes pueden crear sus propios subagentes. Con la variable de entorno CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH en 1, los workers hacen el trabajo ellos mismos. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (20 por defecto) limita cuántos se ejecutan a la vez.
• Los campos de AgentDefinition van en camelCase. Escribir max_turns en lugar de maxTurns provoca un TypeError al crearlo (nota oficial). El supervisor usa el modelo actual claude-opus-5-5 y los workers el alias "sonnet", así el código sigue funcionando cuando sale una versión nueva.

La documentación oficial señala que Opus 5 delega en subagentes con más facilidad que los modelos anteriores y recomienda fijar límites de profundidad, concurrencia y gasto, además de las instrucciones en el prompt. Una instrucción solo cambia cómo pide ayuda Claude; solo los límites detienen una ejecución con seguridad.

5. Código mínimo ②: OpenAI Agents SDK (Python)

En el Agents SDK de OpenAI, la misma forma convierte a los agentes especialistas en herramientas con as_tool() y los pasa a las tools del supervisor ("agents as tools" oficial). La preparación es pip install openai-agents y la variable de entorno OPENAI_API_KEY (guía rápida oficial). Si omites model, se usa el modelo por defecto del SDK; ese valor cambia entre versiones, así que compruébalo en la página de Models.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Busca fuentes primarias para la pregunta y devuelve viñetas con la URL de cada fuente. No rellenes huecos con suposiciones.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Contrasta cada afirmación del borrador recibido con su fuente y enumera las frases que no tengan respaldo.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "Coordinas un informe de investigación. Delega la investigación en research y la "
        "verificación en review, y redacta tú el texto final."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Reunir fuentes primarias con citas",
            max_turns=10,  # límite de idas y vueltas de este rol
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Verificar un borrador",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Reúne tres estadísticas oficiales sobre el uso de la IA generativa en el trabajo y escribe un informe breve",
        max_turns=10,  # si se supera, lanza MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

Lo que comparten los dos SDK y en qué se diferencian:

• Los workers no conocen la conversación del padre. Un agente llamado con as_tool() no hereda automáticamente el estado de la conversación de la ejecución padre (documentación oficial). Claude Agent SDK funciona igual: lo único que un subagente recibe del padre es el prompt de la herramienta Agent. Escribe en el propio encargo las rutas de archivo, los mensajes de error y las decisiones tomadas.
• El límite es Runner.run(..., max_turns=). Si se supera, lanza MaxTurnsExceeded. Con error_handlers={"max_turns": ...} puedes devolver una respuesta controlada en lugar de una excepción (Running agents).
• Con handoffs escribirías Agent(..., handoffs=[billing_agent, refund_agent]). El agente receptor toma el control de la conversación y, por defecto, ve todo el historial anterior. Si hay información que no debe recibir, restríngela con un input_filter.

6. Cómo repartir los roles: buenas y malas divisiones

Repartir los roles es más difícil que el código. Anthropic escribe que cada subagente necesita un objetivo, un formato de salida, indicaciones sobre qué herramientas y fuentes usar y límites claros de la tarea (misma explicación). Estas son divisiones que cumplen esas cuatro condiciones y otras que no.

La misma explicación da una guía de cuántos agentes usar. Anthropic incluyó reglas de escala en el prompt de su supervisor de investigación: una búsqueda simple de datos necesita 1 agente con 3 a 10 llamadas a herramientas, una comparación directa 2 a 4 subagentes con 10 a 15 llamadas cada uno, y una investigación compleja puede usar más de 10 subagentes. Son cifras para trabajo de investigación, así que en tu caso empieza por lo pequeño y amplía solo después de medir.

Para elegir entre supervisor y handoff, la documentación de OpenAI da un criterio claro. Si quieres que un agente sea dueño de la respuesta final o combinar los resultados de varios especialistas, usa el supervisor (agents as tools). Si el enrutamiento es el propio trabajo y el especialista elegido debe responder directamente al usuario (por ejemplo, clasificar solicitudes de soporte), usa un handoff. Puedes combinar ambos.

7. Fallos frecuentes y soluciones

Los tropiezos son previsibles. Aquí van los fallos que Anthropic dice que ocurrieron de verdad con su agente de investigación y los puntos sobre los que advierte la documentación oficial de ambos SDK.

La lección compartida: "los prompts, el diseño de herramientas y el arnés de evals deciden el éxito más que el framework." La documentación de OpenAI también enumera invertir en buenos prompts, monitorizar e iterar, usar agentes especializados e invertir en evals. Por encima de una arquitectura llamativa, la disciplina de construir pequeño, medir y ampliar solo cuando compensa es lo más rápido al final.

Resumen

Construir un sistema multi-agente no da miedo si empiezas con el patrón supervisor desde una configuración mínima. Recapitulemos.

"Construye pequeño, mide y luego amplía." Mantén esa disciplina y un sistema multi-agente se convierte en un socio potente para el trabajo complejo. Para el concepto, consulta ¿Qué es un sistema multi-agente?; para construir uno solo, Cómo construir un agente de IA.

FAQ