Saltar a contenido

Sub-agentes: herramientas con su propio agente

Una herramienta puede resolver su tarea con un agente propio, con su prompt y sus propias herramientas: un investigador que hace varias consultas y saca una conclusión, un redactor que escribe un informe. Para el agente principal es una herramienta más: le pasa una pregunta y recibe una respuesta. Lo que pasa dentro no lo ve.

flowchart TB
    U([pregunta del usuario]) --> P[agente principal]
    P -- "investigar_averias(pregunta)" --> I
    I -- conclusión --> P
    P --> R([respuesta al usuario])
    subgraph I["investigador: su propio agente"]
        direction LR
        B[buscar_averias] <--> M[modelo] <--> D[detalle_averia]
        M <--> H[historial_maquina]
    end

Cuándo merece la pena

Herramientas sueltas en el agente principal Una herramienta con su sub-agente
El principal encadena las consultas El sub-agente las encadena por su cuenta
Cada consulta gasta una de sus max_iteraciones Gasta una sola: la del sub-agente entero
Los resultados intermedios llenan su memoria, y se mandan en cada llamada siguiente A su memoria solo llega la conclusión
Un prompt para todo Un prompt especializado para la tarea
Más barato y más simple Más llamadas al modelo: cuesta más

Un sub-agente compensa cuando la tarea necesita varias consultas que dependen unas de otras y lo que importa es la conclusión, no los datos intermedios: investigar por qué falla una máquina, comparar líneas, preparar un informe. Para «¿qué averías tengo abiertas?» basta una herramienta.

Las dos funciones

agente/subagente.py trae lo necesario para que un sub-agente se porte como el principal:

from ..subagente import crear_subagente, preguntar

crear_subagente(runtime, tools, system_prompt) crea un agente de LangChain:

  • con el modelo de la respuesta, el que eligió el usuario, que es el de la tarifa con la que se cobra la respuesta;
  • con el mismo contexto: sus herramientas reciben el Contexto del usuario que pregunta y leen como él, con su permiso y sus reglas;
  • con SinPermisoMiddleware: si una de sus herramientas no tiene permiso, el sub-agente lo sabe y sigue, como el principal;
  • con HerramientasMiddleware: sus herramientas se apuntan en tool_call con la respuesta, debajo de la que creó el sub-agente (padre, unido por clave a su call_id: el CRUD da el árbol con includes=["tool_calls", "tool_calls.hijas"], o con find_many(tree_mode="descendants", tree_root=(mensaje, call_id)) desde la llamada que se quiera). Las ven tai-chat feedback, tai-chat consumo y el laboratorio del front.

preguntar(subagente, pregunta, runtime, max_iteraciones=4) le pasa la pregunta y devuelve su respuesta final, en texto:

  • suma lo que gastó al consumo de la respuesta, que el agente principal apunta al terminar con su tarifa;
  • tiene su propio límite de vueltas (4 por defecto, con la misma cuenta 2N + 1 que el principal). Si se le acaba, no corta la respuesta: devuelve que no llegó a una conclusión, y el principal decide qué hacer con eso. Lo gastado hasta ahí se apunta igual;
  • no tiene memoria: cada llamada empieza de cero. Lo que tenga que saber va en la pregunta.

El ejemplo: un investigador de averías

Sobre las herramientas de Herramientas que leen datos —buscar_averias, detalle_averia e historial_maquina—, una herramienta que las usa a través de su propio agente:

agente/herramientas/investigador.py
"""Herramientas que construyen su propio agente."""
from langchain.tools import ToolRuntime
from langchain_core.tools import tool

from ..contexto import Contexto
from ..subagente import crear_subagente, preguntar
from .averias import buscar_averias, detalle_averia, historial_maquina

INVESTIGADOR = """Eres un analista de mantenimiento industrial. Investigas una pregunta sobre averías
con tus herramientas y respondes con una conclusión breve, apoyada en datos: ids de avería, máquinas,
fechas e importes. Si los datos no bastan para responder, dilo. No inventes nada."""


@tool(parse_docstring=True)
async def investigar_averias(pregunta: str, runtime: ToolRuntime[Contexto]) -> str:
    """Investiga una pregunta sobre averías que necesita varias consultas: comparar líneas,
    buscar patrones, explicar por qué una máquina falla. Devuelve una conclusión con datos.

    Args:
        pregunta: La pregunta, completa y con todo el contexto que haga falta: el
            investigador no ve la conversación.
    """
    investigador = crear_subagente(
        runtime,
        tools=[buscar_averias, detalle_averia, historial_maquina],
        system_prompt=INVESTIGADOR,
    )
    return await preguntar(investigador, pregunta, runtime)

Y en la lista del agente principal, en lugar de las tres herramientas o junto a ellas:

agente/herramientas/__init__.py
from .toolfuncs import *
from .averias import buscar_averias
from .investigador import investigar_averias

tools = [
    contar_mis_conversaciones,
    buscar_averias,          # para lo directo: «¿qué tengo abierto?»
    investigar_averias,      # para lo que hay que investigar
]

Con las dos, el modelo elige: la descripción de cada una le dice para qué sirve.

Lo que pasa

Ana pregunta «¿por qué falla tanto la prensa P-01?»:

sequenceDiagram
    autonumber
    participant F as Front
    participant P as Agente principal
    participant I as Investigador
    participant T as Herramientas

    F->>P: ¿por qué falla tanto la prensa P-01?
    Note over P: el modelo pide investigar_averias
    P->>I: preguntar("¿Por qué falla la prensa P-01? Busca su historial…")
    Note over I: el modelo pide historial_maquina(1)
    I->>T: historial_maquina(1), como Ana
    T-->>I: 1 cerrada, rodamiento, 320,5 €
    Note over I: el modelo pide buscar_averias(linea="L1")
    I->>T: buscar_averias(linea="L1"), como Ana
    T-->>I: 1 abierta: fuga hidráulica, prioridad 1
    Note over I: el modelo escribe la conclusión
    I-->>P: «Tuvo un rodamiento cambiado hace un mes (320,5 €) y ahora una fuga…»
    Note over P: el modelo contesta con la conclusión
    P-->>F: la respuesta, trozo a trozo
  • Las herramientas del investigador leen como Ana. No ve la avería de Luis en la misma máquina: sus reglas de fila son las de Ana, porque el contexto es el mismo.
  • El usuario solo ve la respuesta del principal. Lo que escribe el investigador mientras trabaja no llega al WebSocket.
  • En el registro de la respuesta (app-lab) aparece investigar_averias con su pregunta y la conclusión. Las consultas internas del investigador no se registran una a una.
  • Se cobran las cinco llamadas al modelo: dos del principal (pedir la herramienta y contestar) y tres del investigador (dos herramientas y la conclusión), todas con la tarifa del modelo de la respuesta.

Cómo escribirlo bien

La descripción de la herramienta es para el principal: le dice cuándo usarla. Que se distinga de las herramientas sueltas: «necesita varias consultas», «comparar», «explicar por qué».

El argumento pregunta es lo único que sabe el investigador. No ve la conversación: si el usuario dijo antes «hablo de la L1», el principal tiene que ponerlo en la pregunta. Dilo en la descripción del argumento, como en el ejemplo.

El prompt del sub-agente es para la tarea: qué tiene que conseguir, con qué herramientas y qué forma tiene la respuesta. Una conclusión breve con datos es lo que mejor usa el principal; una respuesta larga se paga dos veces, al escribirla y al leerla.

Las herramientas del sub-agente son herramientas normales, con su permiso y sus reglas: no hay nada especial que hacer para que lean como el usuario.

Sub-agentes dentro de sub-agentes

Una herramienta de un sub-agente puede ser, a su vez, un sub-agente. Un redactor de informes que, para escribir, le pregunta al investigador:

agente/herramientas/investigador.py
REDACTOR = """Eres el redactor de los informes de mantenimiento. Para escribir un informe, pide al
investigador lo que necesites saber, en preguntas concretas, y redacta con lo que te conteste:
un párrafo de resumen y una lista de las averías que hay que atender primero."""


@tool(parse_docstring=True)
async def informe_de_linea(linea: str, runtime: ToolRuntime[Contexto]) -> str:
    """Redacta el informe de mantenimiento de una línea de producción, listo para enviar.

    Args:
        linea: La línea de producción, por ejemplo 'L2'.
    """
    redactor = crear_subagente(runtime, tools=[investigar_averias], system_prompt=REDACTOR)
    return await preguntar(
        redactor, f"Escribe el informe de mantenimiento de la línea {linea}.", runtime,
        max_iteraciones=3,
    )
agente principal
└── informe_de_linea          → redactor (hasta 3 vueltas)
    └── investigar_averias    → investigador (hasta 4 vueltas)
        ├── buscar_averias
        ├── detalle_averia
        └── historial_maquina

Todo sigue igual en cada nivel: el mismo usuario, el mismo modelo, y el consumo de todos sumado a la respuesta. Una respuesta así son, como poco, seis llamadas al modelo: dos de cada agente.

Los límites se multiplican

El principal puede dar 6 vueltas, el redactor 3 en cada una y el investigador 4 en cada una de esas. En el peor caso, más de un centenar de llamadas al modelo para una pregunta. Ajusta max_iteraciones a lo que la tarea necesita de verdad, y anida solo cuando cada nivel aporta algo que el de arriba no puede hacer.

Errores

Dentro de un sub-agente, los errores se portan como en el principal, un nivel más abajo:

En una herramienta del sub-agente Qué pasa
SinPermiso El sub-agente recibe el motivo y sigue
ToolException con handle_tool_error El sub-agente recibe el mensaje y sigue
Sus argumentos no cumplen el schema El sub-agente recibe el error y se corrige
Se le acaban las vueltas preguntar devuelve que no llegó a una conclusión, y el principal sigue
Cualquier otra excepción Sube hasta el principal y corta la respuesta, como si fallara en él

Otro modelo para el sub-agente

crear_subagente usa el modelo de la respuesta a propósito: el consumo del sub-agente se suma al de la respuesta y se valora con su tarifa. Un sub-agente con otro modelo —uno más barato para consultar, uno más caro para redactar— se cobraría a un precio que no es el suyo.

Si hace falta, el camino es construir el agente a mano con create_agent y el cliente de ese modelo, y apuntar su consumo por separado. Hoy la plantilla no lo trae.

Una herramienta que llama al modelo sin agente

Para una sola llamada —resumir un texto, clasificar una incidencia— no hace falta un agente: basta con el modelo del contexto. Lo que gaste se suma a mano, como hace preguntar:

from langchain_core.messages import HumanMessage


@tool
async def resumir_intervenciones(averia_id: int, runtime: ToolRuntime[Contexto]) -> str:
    """Resume en tres líneas las notas de las intervenciones de una avería."""
    notas = await notas_de(averia_id, runtime)          # leídas como el usuario
    respuesta = await runtime.context.modelo.ainvoke(
        [HumanMessage(content=f"Resume en tres líneas estas notas:\n\n{notas}")]
    )
    runtime.context.consumo.sumar(respuesta.usage_metadata or {})
    return respuesta.text

Sin la línea de sumar, la llamada se haría y no se cobraría. Se apunta junto a la respuesta, como lo de un sub-agente sin nombre: sumar lleva también el razonamiento y la caché que dé el proveedor. El consumo de una respuesta lo explica.