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:
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
Contextodel 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 entool_callcon la respuesta, debajo de la que creó el sub-agente (padre, unido por clave a sucall_id: el CRUD da el árbol conincludes=["tool_calls", "tool_calls.hijas"], o confind_many(tree_mode="descendants", tree_root=(mensaje, call_id))desde la llamada que se quiera). Las ventai-chat feedback,tai-chat consumoy 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 + 1que 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:
"""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:
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) apareceinvestigar_averiascon 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:
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.