Saltar a contenido

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])
  1. 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.
  2. 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 context siguen 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 CONSERVAR de VaciarResultadosMiddleware:
agente/middlewares.py
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.

agente/middlewares.py
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—:

agente/middlewares.py
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 tabla sugerencia, 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: false ni se piden ni se ven, tampoco las que ya estaban guardadas.