Saltar a contenido

Cómo funciona el asistente

El asistente es la parte del chatbot que habla con el LLM: recibe un mensaje, deja que el modelo decida qué herramientas usar, ejecuta las herramientas en nombre del usuario, manda la respuesta al front mientras se escribe y apunta lo que ha costado.

Vive en la API, en routers/custom/assistant/: el punto de extensión que tai-api reserva para el código propio. init lo copia una vez y desde ahí es tuyo: se cambia como cualquier otro código del proyecto. Está construido sobre LangChain 1.x y LangGraph.

Lo que hay dentro

api/api/routers/custom/assistant/
├── __init__.py            assistant_router: todo cuelga de /assistant
├── routers/               la superficie HTTP y WebSocket, fina: valida, llama y responde
│   ├── conversaciones.py    crear, renombrar, ocultar, cambiar de modelo, valorar
│   ├── mensajes.py          enviar (que lanza el título), regenerar
│   ├── websocket.py         el de la sesión: por donde llegan las respuestas mientras se escriben
│   ├── consumo.py           lo que lleva gastado el usuario
│   └── informes.py          pedir el informe de una conversación y descargarlo
├── agente/                responder: el agente
│   ├── agente.py            el bucle: crea el agente, lo ejecuta y emite la respuesta
│   ├── herramientas/        ← las herramientas: aquí es donde más se trabaja
│   │   ├── __init__.py        la lista `tools` que recibe el agente
│   │   ├── toolfuncs.py       las funciones
│   │   └── schemas.py         sus argumentos, en Pydantic
│   ├── contexto.py          quién pregunta: el token del usuario, sus permisos y sus reglas
│   ├── subagente.py         herramientas que construyen su propio agente
│   ├── middlewares.py       lo que se mete entre el agente y el modelo o las herramientas
│   ├── historial.py         qué parte de la memoria llega al modelo
│   ├── memoria.py           la memoria del agente, en el schema `context`
│   ├── sugerencias.py       qué preguntar después, escrito al final de la respuesta
│   ├── entrega.py           guardar esas sugerencias y enviarlas
│   └── trackers.py          lo que se apunta de cada respuesta: herramientas y razonamiento
├── titulo/                titular: el título de una conversación, en paralelo con la primera respuesta
├── informes/              resumir: el informe de una conversación, en DOCX o PDF
├── modelos/               lo común a los tres: llamar a un modelo y pagarlo
│   ├── clientes.py          un cliente de LangChain por proveedor
│   ├── ajustes.py           una copia del cliente para una llamada: sin razonar, con más salida
│   ├── desglose.py          de qué se compone lo gastado
│   ├── contador.py          los tokens de una llamada, o de una respuesta con varias
│   └── precios.py           el catálogo de modelos, las tarifas, los límites, las bolsas y el apunte
├── acceso.py              la conversación, si es del usuario: la regla de owner()
├── conexiones.py          los WebSocket abiertos
├── config.py              lee .config.json, el derivado de config.yaml
└── tipos.py               los cuerpos de las peticiones y los eventos del WebSocket

Para la mayoría de los proyectos, lo único que hay que tocar es agente/herramientas/ y el prompt de config.yaml. El resto está para entender qué pasa, y para cambiarlo si hace falta.

El camino de un mensaje

sequenceDiagram
    autonumber
    participant F as Front
    participant R as /assistant
    participant A as Agente
    participant M as Modelo (LLM)
    participant H as Herramientas
    participant B as Base de datos

    F->>R: WebSocket /assistant/ws (uno por sesión)
    F->>R: POST /assistant/chat/send
    R->>B: ¿es suya? guarda el mensaje
    R-->>F: 200: recibido
    opt la conversación no tiene título
        R->>M: el título (en segundo plano, con el modelo por defecto)
        M-->>F: chat_title
    end
    R->>A: start_streaming (en segundo plano)
    A->>B: ¿tarifa? ¿límite? ¿saldo?
    A->>B: la memoria de la conversación
    loop hasta max_iteraciones
        A->>M: prompt, historial y herramientas
        M-->>F: el texto, trozo a trozo
        M->>A: o pide una herramienta
        A->>H: la ejecuta como el usuario
        H->>B: lee con su permiso y sus reglas
        H->>A: el resultado, para el modelo
    end
    A->>B: la respuesta, sus herramientas y sus tokens
    A-->>F: assistant_response_complete
  1. El front abre un WebSocket por sesión, por el que llegan las respuestas de todas sus conversaciones, cada evento con su chat_id, y manda el mensaje por HTTP. La ruta comprueba que la conversación es del usuario —la de otro es un 404— y que no está ya respondiendo, guarda el mensaje y contesta enseguida: la respuesta llega después, por el WebSocket. Si la conversación no tiene título, se le pone a la vez, y llega por el mismo socket (chat_title).
  2. El agente arranca en segundo plano. Antes de llamar al proveedor comprueba que hay un modelo con tarifa, que el usuario no ha pasado su límite y, con bolsas, que queda saldo. Si algo falla, contesta el motivo sin gastar nada.
  3. Fija el modelo del turno: el que pide el front, o el de la conversación, o el de por defecto.
  4. Crea el agente de LangChain con el modelo, las herramientas, los middlewares y la memoria de la conversación, y lo ejecuta con el contexto del usuario.
  5. El modelo escribe o pide herramientas. Lo que escribe llega al front trozo a trozo. Lo que pide se ejecuta y su resultado vuelve al modelo, que sigue. Así hasta que contesta, o hasta max_iteraciones.
  6. Al terminar se guarda la respuesta con todo lo que la explica —qué herramientas usó, con qué argumentos y qué devolvieron, cuánto tardó, cuántas vueltas dio, cuántos tokens gastó y con qué tarifa se valora— y se avisa al front.

Las ideas que importan

El agente responde en nombre de un usuario. No tiene permisos propios: lo que una herramienta lee, lo lee como lo leería ese usuario por la API, con su permiso y sus reglas de fila. Es la diferencia entre un asistente que se puede desplegar y uno que filtra datos. Herramientas que leen datos lo explica.

Cada conversación tiene su memoria. El historial que ve el modelo no se lee de la tabla de mensajes: lo guarda el checkpointer de LangGraph, en el schema context, con el id de la conversación como hilo. Por eso el modelo recuerda también lo que devolvieron las herramientas en turnos anteriores. Ocultar una conversación borra su memoria.

Todo se apunta. Cada respuesta queda guardada con sus llamadas a herramientas y su consumo. Quien tenga el permiso app-lab lo ve en el front, debajo de cada respuesta.

Todo se cobra. Cada llamada al modelo —también las de los sub-agentes— suma a la respuesta. El consumo de una respuesta lo explica.

Por dónde seguir

Quiero… Página
Entender el bucle, la memoria, los límites y los middlewares El agente
Darle al asistente una herramienta Herramientas
Que una herramienta lea los datos de la empresa sin saltarse los permisos Herramientas que leen datos
Que una herramienta resuelva su tarea con su propio agente Sub-agentes
Saber qué se cobra y cómo El consumo de una respuesta