Sistemas multi agente

Arquitectura multi agente

Los sistemas multi agente representan una evolución natural cuando un agente único se vuelve demasiado complejo. En lugar de construir un agente monolítico que gestione decenas de herramientas y domine múltiples dominios, la arquitectura multi agente divide la responsabilidad entre agentes especializados que colaboran para resolver problemas.

Esta aproximación resulta especialmente útil en tres escenarios:

• Un agente tiene demasiadas herramientas y toma decisiones pobres sobre cuál utilizar
• El contexto o memoria crece tanto que un solo agente no puede gestionarlo eficazmente
• Las tareas requieren especialización en dominios distintos (planificación, investigación, cálculo)

LangChain ofrece dos patrones principales para orquestar múltiples agentes: Tool Calling y Handoffs. Cada uno responde a necesidades arquitectónicas diferentes.

Patrón Tool Calling (supervisor)

En el patrón Tool Calling, un agente principal actúa como controlador y trata a otros agentes como herramientas que puede invocar. El controlador gestiona la orquestación completa, mientras que los agentes subordinados ejecutan tareas específicas y devuelven resultados.

El flujo de ejecución sigue esta secuencia:

[Usuario] → [Agente controlador] → [Subagente especialista] → [Resultado] → [Controlador] → [Respuesta]

Los subagentes no conversan directamente con el usuario. Su rol es realizar una tarea concreta y devolver el resultado al controlador, que decide el siguiente paso o finaliza la interacción.

Implementación básica

Para convertir un agente en herramienta de otro, envolvemos su invocación en una función decorada con @tool:

from langchain.agents import create_agent
from langchain.tools import tool

# Creamos un agente especializado en cálculos
agente_matematico = create_agent(
    model="gpt-5.1",
    tools=[],
    prompt="Eres un experto en matemáticas. Resuelve cálculos de forma precisa."
)

@tool("calcular", description="Resuelve operaciones matemáticas complejas")
def invocar_matematico(consulta: str) -> str:
    """Delega cálculos al agente matemático especializado."""
    resultado = agente_matematico.invoke({
        "messages": [{"role": "user", "content": consulta}]
    })
    return resultado["messages"][-1].content

# El agente principal usa al matemático como herramienta
agente_principal = create_agent(
    model="gpt-5.1",
    tools=[invocar_matematico]
)

El agente principal decide cuándo invocar al subagente basándose en el nombre y descripción de la herramienta. Por ello, es fundamental elegir nombres descriptivos y escribir descripciones claras que guíen correctamente las decisiones del controlador.

Personalizar la entrada al subagente

Cuando necesitamos que el subagente reciba más contexto que la simple consulta generada por el controlador, utilizamos ToolRuntime para acceder al estado completo del agente principal:

from langchain.agents import AgentState, create_agent
from langchain.tools import tool, ToolRuntime

class EstadoPersonalizado(AgentState):
    idioma_preferido: str

@tool("traducir", description="Traduce texto al idioma preferido del usuario")
def invocar_traductor(texto: str, runtime: ToolRuntime[None, EstadoPersonalizado]) -> str:
    """Traduce considerando el idioma configurado en el estado."""
    idioma = runtime.state.get("idioma_preferido", "español")
    
    # Construimos un prompt enriquecido con contexto del estado
    prompt_completo = f"Traduce al {idioma}: {texto}"
    
    resultado = agente_traductor.invoke({
        "messages": [{"role": "user", "content": prompt_completo}]
    })
    return resultado["messages"][-1].content

El parámetro runtime permanece oculto para el modelo, que solo ve texto en el esquema de la herramienta. Esto permite inyectar contexto adicional sin complicar la interfaz visible para el LLM.

Patrón Handoffs

El patrón Handoffs permite que los agentes transfieran el control entre sí de forma descentralizada. A diferencia del Tool Calling, aquí el agente activo cambia y el usuario puede continuar interactuando directamente con el nuevo agente.

Este patrón es adecuado cuando:

• Los agentes necesitan conversar directamente con el usuario
• Se requieren transiciones fluidas entre dominios especializados
• La conversación puede derivar hacia temas que otro agente maneja mejor

El flujo típico sería:

[Usuario] → [Agente A] → [Handoff a Agente B] → [Usuario interactúa con B] → [Handoff a A] → ...

Ejemplo práctico: asistente personal

Un caso de uso habitual es un asistente que coordina especialistas para calendario y correo electrónico. El supervisor delega tareas a cada especialista según la naturaleza de la petición:

from langchain.agents import create_agent
from langchain.tools import tool

# Herramientas específicas de cada dominio
@tool
def crear_evento(titulo: str, fecha: str, hora: str) -> str:
    """Crea un evento en el calendario."""
    return f"Evento '{titulo}' creado para {fecha} a las {hora}"

@tool
def enviar_correo(destinatario: str, asunto: str, cuerpo: str) -> str:
    """Envía un correo electrónico."""
    return f"Correo enviado a {destinatario} con asunto: {asunto}"

# Subagentes especializados
agente_calendario = create_agent(
    model="gpt-5.1",
    tools=[crear_evento],
    prompt="Gestionas el calendario del usuario. Crea y consulta eventos."
)

agente_correo = create_agent(
    model="gpt-5.1",
    tools=[enviar_correo],
    prompt="Gestionas el correo del usuario. Redactas y envías mensajes."
)

# Herramientas que envuelven a los subagentes
@tool("gestionar_calendario", description="Programa reuniones y gestiona eventos")
def llamar_calendario(solicitud: str) -> str:
    """Delega tareas de calendario al especialista."""
    resultado = agente_calendario.invoke({
        "messages": [{"role": "user", "content": solicitud}]
    })
    return resultado["messages"][-1].content

@tool("gestionar_correo", description="Redacta y envía correos electrónicos")
def llamar_correo(solicitud: str) -> str:
    """Delega tareas de correo al especialista."""
    resultado = agente_correo.invoke({
        "messages": [{"role": "user", "content": solicitud}]
    })
    return resultado["messages"][-1].content

# Supervisor que coordina ambos especialistas
supervisor = create_agent(
    model="gpt-5.1",
    tools=[llamar_calendario, llamar_correo],
    prompt="Eres un asistente personal. Delega tareas de calendario y correo a los especialistas."
)

Al invocar al supervisor con una petición como "Programa una reunión mañana a las 10 y envía la invitación por correo", este coordinará automáticamente ambos subagentes en la secuencia apropiada.

Criterios para elegir patrón

La elección entre Tool Calling y Handoffs depende de las necesidades específicas del sistema:

| Criterio | Tool Calling | Handoffs | |:---|:---|:---| | Control centralizado del flujo | Sí | No | | Subagentes conversan con usuario | No | Sí | | Conversaciones complejas entre especialistas | Limitado | Adecuado | | Orquestación de tareas estructuradas | Adecuado | Limitado |

Ambos patrones pueden combinarse: usar Handoffs para cambiar el agente activo según el dominio, y que cada agente activo utilice Tool Calling para invocar subagentes auxiliares en tareas específicas.