El agente¶
agente/agente.py es el bucle que responde. Esta página explica qué hace en cada paso y qué se
puede cambiar en cada uno.
Cómo se crea¶
Para cada respuesta se crea un agente de LangChain con
create_agent:
agent = create_agent(
model=cliente(usable), # el modelo del turno (modelos/clientes.py)
tools=tools, # agente/herramientas/__init__.py
middleware=[
*historial, # resumir, vaciar y recortar (agente/middlewares.py)
ToolPermissionMiddleware(user_permissions=user_permissions),
# con asistente.sugerencias.activas
*([SugerenciasMiddleware(self.config.sugerencias_cuantas, describir_error)] if sugerir else []),
HerramientasMiddleware(describir_error=describir_error),
SinPermisoMiddleware(),
MedirConsumoMiddleware(describir_error=describir_error),
],
system_prompt=self.prompt, # asistente.prompt de config.yaml
checkpointer=checkpointer, # la memoria, en el schema `context`
context_schema=Contexto, # quién pregunta (agente/contexto.py)
)
y se ejecuta con el mensaje, la conversación como hilo de la memoria y el contexto del usuario:
contexto = Contexto(token=access_token, modelo=cliente(usable))
async for token, meta in agent.astream(
{"messages": [msg]},
config={
"configurable": {"thread_id": chat_id},
"recursion_limit": limite_de_pasos(self.config.max_agent_iterations, regenerar),
},
stream_mode="messages",
context=contexto,
):
... # cada trozo de texto va al WebSocket; cada herramienta, al registro
Crear el agente es barato: es un grafo pequeño. El cliente del modelo, que sí es caro —abre conexiones con el proveedor—, se construye una vez por configuración y se reutiliza.
El bucle¶
El agente alterna dos pasos:
flowchart LR
I([mensaje]) --> M[modelo]
M -- pide herramientas --> H[herramientas]
H -- resultados --> M
M -- contesta --> F([respuesta])
- El modelo recibe el prompt del sistema, el historial y la descripción de las herramientas que puede usar. Contesta con texto, o pide una o varias herramientas con sus argumentos.
- Las herramientas se ejecutan, y lo que devuelven vuelve al modelo como un mensaje más.
LangGraph no cuenta vueltas sino pasos del grafo, y cada vuelta son tres: el del resumen del historial
(que va delante de cada llamada al modelo, aunque no resuma), el modelo y las herramientas. El límite
lo calcula limite_de_pasos() (agente/middlewares.py) a partir de asistente.max_iteraciones de
config.yaml, el número de veces que el agente puede ir a las herramientas y volver, para que pare
donde paraba cuando cada vuelta eran dos pasos (2 × max_iteraciones + 1). Al pasarse, se contesta:
Lo siento, no pude completar la consulta tras varios intentos. Por favor, reformula tu pregunta.
Cuántas iteraciones
Una pregunta sobre datos suele resolverse en una o dos vueltas: buscar, quizá pedir un detalle, y contestar. Con 6 hay margen para encadenar herramientas sin dejar que un modelo atascado gaste sin fin. Si un caso necesita muchas vueltas, suele ser mejor darle una herramienta que haga más de una vez, o un sub-agente con su propio límite.
La memoria¶
El historial que ve el modelo lo guarda el checkpointer de LangGraph (AsyncPostgresSaver) en el
schema context, que crea tai-chat db push. El hilo es el id de la conversación: cada una tiene su
memoria, y en cada turno solo se manda el mensaje nuevo.
Se guarda a cada paso, no al final: el mensaje del usuario, cada llamada al modelo y cada
resultado de una herramienta. El checkpointer trabaja sobre un pool de conexiones con autocommit:
cada paso toma una conexión unos milisegundos, guarda y la devuelve, y ninguna se queda ocupada
mientras el modelo escribe. Por eso unas pocas conexiones atienden muchas respuestas a la vez, y lo
que se llegó a hacer en una respuesta cortada (cancelada, o con un error) queda en la memoria, igual
que en la pantalla.
La memoria no es la tabla de mensajes. Guarda todo lo que vio el modelo, también las llamadas a herramientas y sus resultados: si en un turno buscó las averías de una máquina, en el siguiente puede contestar sobre ellas sin volver a buscarlas.
Ocultar una conversación borra su memoria; si está respondiendo, primero se para la respuesta, que si no seguiría escribiendo en ella. Regenerar una respuesta borra la de la última pregunta, la quita también de la memoria (con sus herramientas) y vuelve a preguntar: el modelo no la vuelve a ver. Si la última pregunta no tiene respuesta guardada (falló), no borra nada: la de la pregunta anterior se queda.
Lo que se envía de la memoria¶
agente/historial.py decide qué parte de la memoria llega al modelo en cada llamada, y los middlewares
de agente/middlewares.py lo aplican. El historial
es lo anterior a la pregunta en curso, y es lo único que acota asistente.max_tokens_contexto
(100000 tokens aproximados en la plantilla): la pregunta y lo que va detrás en ese turno van siempre
enteros, y el prompt y las definiciones de las herramientas no cuentan.
| Paso | Qué hace | ¿Cambia la memoria? |
|---|---|---|
Resumir (ResumirHistorialMiddleware) |
Cuando el historial llega al presupuesto, al empezar un turno, el modelo de la respuesta resume lo antiguo (en torno al 70 %); lo más reciente (contexto.conservar, 30 %) se queda entero. El resumen ocupa como mucho contexto.resumen (5 %), y el siguiente resumen absorbe el anterior: tras resumir, el historial queda en torno al 35 % |
Sí: queda [resumen, lo conservado] |
Vaciar (VaciarResultadosMiddleware) |
Los resultados de herramientas de turnos cerrados se envían como un hueco que dice qué herramienta era, salvo los de los últimos contexto.turnos_con_resultados (1). La llamada y la respuesta se quedan: el modelo ya resumió esos datos al contestar, y puede volver a pedirlos |
No |
Recortar (RecortarHistorialMiddleware) |
Si aun así el historial no cabe (el resumen falló), se quita lo más antiguo, empezando siempre por un mensaje del usuario | No |
- Vaciar siempre, y resumir por tramos, hace que de una llamada a la siguiente se repita casi todo el principio de la petición, que es lo que OpenAI y Gemini cachean y cobran más barato. Una ventana que se desliza turno a turno lo cambiaría en cada uno.
- Lo que cuesta el resumen se apunta con origen
resumen, colgando del mensaje de esa respuesta: ver el consumo. - Si el resumen falla, se registra, la memoria no cambia y la respuesta sigue, recortada.
- Lo resumido deja de estar en la memoria, y el modelo ya no puede volver a ello; lo que ve el
usuario no cambia, porque sale de la tabla de mensajes. En el schema
contextsiguen los checkpoints anteriores de la conversación (LangGraph guarda uno por paso), hasta que se oculta. - Herramientas que no se vacían nunca: las que devuelven poco y se consultan a menudo, en
CONSERVARdeVaciarResultadosMiddleware:
class VaciarResultadosMiddleware(ContextEditingMiddleware):
CONSERVAR: set[str] = {"estado_de_la_maquina"}
Los middlewares¶
Un middleware se mete entre el agente y el modelo, o entre el agente y las herramientas, y puede cambiar lo que pasa por ahí. Los del historial están arriba; los demás:
| Middleware | Dónde se mete | Qué hace | Si falla |
|---|---|---|---|
ToolPermissionMiddleware |
Antes de cada llamada al modelo | Quita las herramientas que el usuario no puede usar, y añade al prompt instrucciones según sus permisos | Cae la respuesta, a propósito: un fallo de permisos no es silencioso |
SugerenciasMiddleware |
Alrededor de cada llamada al modelo, con las sugerencias activas | Pide al modelo que acabe con sus sugerencias y las quita de lo que se guarda | Lo registra y la respuesta sigue: ya está pagada |
HerramientasMiddleware |
Alrededor de cada herramienta, por fuera del siguiente | Apunta cada herramienta que se llama, también las de un sub-agente (ver abajo) | Lo registra y sigue; el error de la herramienta sube igual |
SinPermisoMiddleware |
Alrededor de cada herramienta | Si una herramienta dice que el usuario no tiene permiso, se lo cuenta al modelo en vez de tumbar la respuesta | Solo captura ese error |
MedirConsumoMiddleware |
Alrededor de cada llamada al modelo, la última | Mide de qué se compone la petición: el desglose del consumo | Lo registra y sigue |
Una excepción que se escapa de un middleware tumba la respuesta entera: sube por los de fuera hasta
el agente, que apunta lo gastado y avisa del error. Por eso cada uno decide qué hace si falla su propia
lógica (la columna de la derecha, que está también en la cabecera de agente/middlewares.py), y uno
propio también tiene que decidirlo: lo que es secundario lo registra y deja seguir la respuesta.
Herramientas según los permisos del usuario¶
ToolPermissionMiddleware decide qué herramientas ve el modelo para cada usuario. Sus reglas
están en RULES, que la plantilla trae vacío: sin reglas, todas las herramientas valen para todos.
import re
class ToolPermissionMiddleware(AgentMiddleware):
RULES: list[dict] = [
{
# las herramientas de costes, solo para quien puede leer la tabla de costes
"permission": "coste-read",
"tool_pattern": re.compile(r"^coste_"),
"prompt": "Puedes consultar los costes de mantenimiento con las herramientas coste_*.",
},
{
# estas dos, solo para quien puede escribir en la tabla de órdenes
"permission": "orden-update",
"tool_names": ["cerrar_orden", "reabrir_orden"],
},
]
| Clave | Qué es |
|---|---|
permission |
El permiso que exige, como viene en el token: uno de API (coste-read). Uno de aplicación (app-lab) no vale: tai-api no los mete en el token (van en la respuesta del login, para el front), y la herramienta se quedaría sin nadie que la pudiera usar |
tool_pattern |
Una expresión regular: las herramientas cuyo nombre casa exigen el permiso |
tool_names |
O los nombres exactos |
prompt |
Instrucciones que se añaden al prompt cuando el usuario tiene el permiso. Mejor en positivo: describen lo que puede hacer |
Una herramienta que no cubre ninguna regla vale para todos. Una que cubren varias, para quien tenga cualquiera de sus permisos.
Ocultar herramientas evita que el modelo intente usar lo que no debe, y ahorra tokens: la descripción de cada herramienta se manda en cada llamada. Pero no es lo que protege los datos: eso lo hace la herramienta al leer, con el permiso y las reglas del usuario. Ver Herramientas que leen datos.
Un middleware propio¶
Un middleware es una clase con los métodos de los puntos en los que se mete. Por ejemplo, para que el modelo sepa qué día es y con quién habla —el modelo no lo sabe, y sin ello «las averías de esta semana» no tiene respuesta—:
from datetime import date
class FechaYUsuarioMiddleware(AgentMiddleware):
"""Le dice al modelo qué día es y quién pregunta."""
def _con_fecha(self, request: ModelRequest) -> ModelRequest:
quien = request.runtime.context.username
nota = f"Hoy es {date.today():%d/%m/%Y}. Hablas con el usuario {quien}."
base = request.system_message.content if request.system_message else ""
return request.override(system_message=SystemMessage(content=f"{base}\n\n{nota}"))
def wrap_model_call(self, request, handler):
return handler(self._con_fecha(request))
async def awrap_model_call(self, request, handler):
return await handler(self._con_fecha(request))
Y se añade a la lista de create_agent en agente/agente.py:
middleware=[
*historial,
ToolPermissionMiddleware(user_permissions=user_permissions),
*([SugerenciasMiddleware(self.config.sugerencias_cuantas, describir_error)] if sugerir else []),
HerramientasMiddleware(describir_error=describir_error),
SinPermisoMiddleware(),
FechaYUsuarioMiddleware(),
MedirConsumoMiddleware(describir_error=describir_error),
],
request.runtime.context es el Contexto de la respuesta: el usuario, su
token y sus reglas. Los puntos de enganche (wrap_model_call, wrap_tool_call, before_model…) son
los de LangChain: ver su
guía de middlewares.
Siempre las dos versiones
El agente se ejecuta en asíncrono (astream), así que lo que se usa es awrap_model_call y
awrap_tool_call. La versión síncrona se escribe igualmente para que el middleware sirva también
en pruebas o en un sub-agente invocado sin await.
Los modelos¶
modelos/clientes.py convierte un modelo del catálogo en un cliente de LangChain:
proveedor |
Cliente |
|---|---|
openai |
ChatOpenAI |
azure-openai |
AzureChatOpenAI |
google |
ChatGoogleGenerativeAI |
Todos con streaming y con el uso de tokens en el streaming (stream_usage), que es de donde sale el
consumo. Cada cliente se construye la primera vez que se usa y se guarda por su configuración entera:
si el modelo cambia en la tabla, se construye otro.
El modelo se fija al empezar la respuesta: el que pide el front, el de la conversación o el de por defecto, por ese orden. Si el que se pide ya no está disponible, se usa el de por defecto en vez de dejar el chat sin contestar.
Lo que se apunta de cada respuesta¶
Mientras el agente responde, tres trackers apuntan lo que pasa (los dos primeros en
agente/trackers.py; el de los tokens, que usan también el título y los informes, en modelos/contador.py):
| Tracker | Qué apunta | Dónde acaba |
|---|---|---|
ToolCallTracker |
Cada herramienta: su nombre, sus argumentos, su resultado, cuánto tardó y si falló. También las de un sub-agente, con padre: el call_id de la herramienta que lo creó |
La tabla tool_call, colgando del mensaje |
ReasoningTracker |
El texto que el modelo escribe entre herramientas, y las vueltas que da | mensaje.reasoning y mensaje.agent_iterations |
TokenUsageTracker |
Los tokens de entrada y salida de cada llamada al modelo | token_usage, con la tarifa con la que se valora |
ToolCallTracker no lee el stream de la respuesta: lo alimenta HerramientasMiddleware al ejecutarse
cada herramienta, en el agente principal y en cada sub-agente, y vive en el Contexto, que comparten.
Leyendo el stream, las herramientas de un sub-agente no se apuntaban: su resultado no llega a él.
Con el permiso app-lab, el front enseña todo esto debajo de cada respuesta, con las herramientas de un
sub-agente sangradas debajo de la que lo creó.
El WebSocket¶
La respuesta llega por /assistant/ws, un socket por sesión (por pestaña), por el que llegan las
respuestas de todas las conversaciones del usuario. Se autentica como el resto de la API —el token va
en el subprotocolo tai.bearer, nunca en la URL—, y solo recibe lo suyo: los eventos se mandan a las
conexiones de su dueño, que sale del token. Cada evento lleva su chat_id, y el front lo reparte:
se puede preguntar en una conversación, pasar a otra y preguntar allí, y las dos siguen llegando.
La ruta de antes, /assistant/ws/chat/{id}, sigue para los front ya copiados: recibe solo lo de su
conversación, y una ajena se cierra con 4004. Los eventos son los mismos en las dos:
| Evento | Cuándo |
|---|---|
connection_established |
Al conectar |
message_received |
Se ha guardado el mensaje del usuario |
assistant_response_start |
El agente empieza a responder |
AIMessageChunk |
Un trozo de la respuesta, con su texto |
assistant_response_complete |
Ha terminado: la respuesta entera, su id, el modelo y la duración |
assistant_response_cancelled |
El usuario la ha parado |
assistant_response_error |
Ha fallado. El detalle se queda en el log |
assistant_response_regenerating |
Se está regenerando la última |
chat_title |
El modelo le ha puesto título a la conversación, en data.title |
chat_suggestions |
Qué se podría preguntar después de una respuesta: data.mensaje_id y data.sugerencias |
chat_report_start, chat_report_complete, chat_report_error |
El informe de la conversación, que se prepara en segundo plano: data.informe (la fila, sin su contenido) y, al completarse, data.mensaje, el mensaje de sistema que lo entrega |
ping / pong |
Para mantener viva la conexión |
Lo que escribe el modelo entre herramientas también llega como AIMessageChunk: el usuario ve
al agente pensar en voz alta.
Varias a la vez. Cada conversación responde una vez: un segundo mensaje mientras responde es un
422 con reason: chat_respondiendo. Y un usuario tiene como mucho
asistente.max_respuestas_simultaneas (5) conversaciones
respondiendo a la vez: una más es un 422 con reason: demasiadas_respuestas. El hueco se aparta
antes de guardar el mensaje, así que no queda ninguno sin contestar. La respuesta sigue aunque se
cierre el socket: se guarda igual, y se ve al volver a la conversación.
Cuando algo falla¶
| Qué pasa | Qué ve el usuario |
|---|---|
| No hay modelo con tarifa, se pasó de su límite o no queda saldo | El motivo, como una respuesta. No se llama al proveedor |
El agente se pasa de max_iteraciones |
Que no pudo completar la consulta |
| El usuario la para | «La respuesta fue cancelada por el usuario», guardada como respuesta |
| La clave del proveedor se ha quedado sin crédito | Que se han agotado los créditos del proveedor |
Una herramienta dice que no hay permiso (SinPermiso) |
Nada raro: el modelo lo recibe como resultado y se lo explica |
Una herramienta lanza ToolException |
Lo mismo, si la herramienta lo permite: ver errores |
| Cualquier otra excepción | Que no se pudo completar la respuesta. La traza, en el log |
Ningún error enseña al usuario la configuración del modelo ni sus claves: el mensaje que se guarda en
el log pasa por describir_error, que tapa los valores de las variables de las claves.
El título¶
Al primer mensaje de una conversación sin título, el back se lo pone en paralelo con la
respuesta: le pasa al modelo los asistente.titulo.mensajes primeros mensajes y le pide un título
corto, recortado a asistente.titulo.max_caracteres, y lo manda por el WebSocket como chat_title
en cuanto lo tiene. Suele llegar antes de que termine la respuesta. Usa el modelo de ese
mensaje, el mismo que la respuesta, sin herramientas: el título va ligado al mensaje y se cobra a su
tarifa. Pero sin razonar (o con el mínimo que admite el modelo): seis palabras no necesitan
pensar, y en un modelo que razona eso era casi todo lo que costaba. Si el usuario la renombra
mientras tanto, lo suyo no se pisa. El front lo escribe letra a letra; uno puesto a mano sale entero.
POST /assistant/chat/{id}/generate-title sigue para los front de antes de este cambio, que lo
pedían al terminar la primera respuesta. Si la conversación ya tiene título, lo devuelve sin llamar
al modelo.
Lo que cuesta se apunta como el resto del consumo del usuario, con la conversación y sin colgar de ningún mensaje: ver el consumo de una respuesta.
Las sugerencias¶
Con asistente.sugerencias.activas, el modelo acaba su respuesta con hasta
asistente.sugerencias.cuantas formas de seguir: lo que el usuario querría preguntar o pedir a
continuación, escrito como lo diría él, una por línea y con la marca SUGERENCIA:. Se lo pide
SugerenciasMiddleware, que lo añade al prompt del sistema. Salen del mismo razonamiento que la
respuesta, con las herramientas que ese usuario puede usar, y no cuestan otra llamada: unos pocos
tokens más de salida.
- Esas líneas no son de la respuesta: no se le enseñan al usuario mientras se escribe (el back las retiene aunque la marca llegue partida), no se guardan en el mensaje y no quedan en la memoria del agente.
- Llegan por el WebSocket (
chat_suggestions) justo después de la respuesta, y se guardan con el mensaje (en la tablasugerencia, que cuelga de él): al recargar siguen ahí, sin volver a llamar al modelo. - Si el modelo no las escribe, no hay: no hay una llamada de respaldo.
- El front las enseña solo bajo la última respuesta, una debajo de otra y con el estilo de sus burbujas, como botones que envían su texto. Al enviar cualquier mensaje se pliegan. La primera es además el texto de ayuda del cajón, y Tab la escribe en él.
- No hay tras un error, una cancelación, el límite de vueltas ni un aviso de límite o de saldo. Con
asistente.sugerencias.activas: falseni se piden ni se ven, tampoco las que ya estaban guardadas.