Cómo funciona el asistente de IA: AI SDK, tools, el loop agéntico y MCP

El asistente de Legio no es un chatbot que "sabe de derecho de memoria". Es un agente: un modelo de lenguaje al que le dimos un conjunto de herramientas (buscar contactos, abrir un expediente, generar una demanda, consultar el Boletín Oficial) y la capacidad de decidir solo cuáles usar, en qué orden, hasta resolver el pedido del abogado. Este artículo abre esa caja: qué es el AI SDK, qué es una tool, cómo funciona el loop que encadena varios pasos, qué pinta el MCP en todo esto y cómo se consulta la base de datos sin romper la seguridad entre estudios.

El AI SDK de Vercel

Hablar con un modelo de IA "a mano" es incómodo: cada proveedor (Google, Anthropic, OpenAI) tiene su propio formato de mensajes, su forma de declarar herramientas y su forma de transmitir la respuesta. El AI SDK de Vercel (el paquete ai) es una capa que unifica todo eso: uno escribe el código una sola vez y puede cambiar de modelo cambiando una línea.

En Legio el backend usa cuatro piezas del SDK:

• streamText — el corazón. Recibe el modelo, los mensajes, el system prompt y las herramientas, y devuelve la respuesta en streaming (token por token), para que el abogado vea la respuesta escribirse en vivo en lugar de esperar a que termine.
• tool — declara una herramienta: su descripción y los parámetros que recibe.
• zodSchema — describe esos parámetros con Zod, una librería de validación. Así el modelo sabe exactamente qué forma tienen los datos que debe mandar.
• stepCountIs — define cuándo frenar el loop (más sobre esto abajo).

El proveedor se elige por pedido: por defecto Gemini 2.5 Flash (rápido y económico), con la opción de usar Claude de Anthropic. Cambiar de uno a otro es, literalmente, una condición en el código; el resto no se toca.

¿Qué es una "tool"?

Un modelo de lenguaje, solo, no puede leer tu base de datos ni crear un expediente: solo genera texto. Una tool (herramienta) es la forma de darle "manos". Cada tool tiene tres partes:

1. Un nombre y una descripción en lenguaje natural — esto es lo que el modelo lee para decidir si la herramienta sirve. La descripción es prompt: si dice "usá esto cuando el abogado pregunte si salió algo sobre un tema", el modelo la elegirá en ese caso.
2. Un esquema de parámetros (con Zod) — qué datos necesita. Por ejemplo, manage_contacts recibe una action (search, create, get, update) y los datos del contacto.
3. Una función execute — el código real que corre en el backend: consulta Supabase, llama a una API externa, genera un documento, etc.

Lo importante: el modelo no ejecuta nada. El modelo solo decide "quiero llamar a manage_cases con estos argumentos". El backend recibe esa decisión, corre la función de verdad, y le devuelve el resultado al modelo. El modelo nunca toca la base de datos directamente.

Las herramientas que tiene Legio

El asistente cuenta hoy con un set amplio, agrupado por dominio:

• CRM: manage_contacts, manage_cases, manage_documents (buscar, crear, leer y actualizar contactos, expedientes y plantillas/documentos).
• Web y lectura: read_url (leer un PDF o una página), search_web, research_legal, check_sisfe_expediente (consulta de expedientes en el sistema de Santa Fe).
• Legal argentino: audit_contract (detección de cláusulas riesgosas), search_argentine_law y search_jurisprudence (normativa y fallos en SAIJ), analyze_legal_deadlines (cálculo de plazos procesales por jurisdicción).
• Radar Legal: buscar_normativa_radar — la búsqueda semántica (RAG) sobre los boletines oficiales y la jurisprudencia ingeridos. (Cómo se construye ese índice está contado en el artículo sobre el Radar Legal.)
• Google Drive: manage_drive, disponible solo si el estudio conectó su Drive.

El loop agéntico

Acá está la magia. Cuando el abogado escribe "creá un expediente laboral para Juan Pérez y fijate si salió algo sobre indemnizaciones esta semana", no alcanza con una sola llamada. El asistente trabaja en pasos (steps):

1. El modelo lee el pedido y decide: "primero busco a Juan Pérez" → llama a manage_contacts con action: 'search'.
2. El backend ejecuta, devuelve el contacto. El modelo ahora sabe su ID.
3. El modelo decide: "creo el expediente" → llama a manage_cases con action: 'create'.
4. El backend lo crea y devuelve el resultado.
5. El modelo decide: "ahora la parte normativa" → llama a buscar_normativa_radar con query: 'indemnizaciones laborales'.
6. El backend devuelve las normas más relevantes por significado.
7. El modelo ya tiene todo: redacta la respuesta final en lenguaje natural, citando lo que hizo y lo que encontró.

Todo eso ocurre en una sola interacción, sin que el abogado tenga que pedir cada paso. Lo que lo hace posible es que streamText vuelve a llamar al modelo después de cada resultado de herramienta, alimentándolo con lo que acaba de obtener. Para que el loop no se descontrole, lo limitamos con stopWhen: stepCountIs(12): hasta 12 pasos por turno. Si en ese margen no resolvió, corta y responde con lo que tenga.

El system prompt: contexto que cambia solo

Antes de cada conversación, el backend arma un system prompt (las instrucciones madre del asistente) que no es fijo: se construye en el momento con:

• La fecha actual y el año en curso, para que el modelo no se confunda con plazos.
• Lo que el abogado está viendo en pantalla: si tiene abierto un contacto o un expediente, se le inyecta su ID y sus datos. Por eso uno puede decir "actualizá su teléfono" y el asistente sabe a quién se refiere, sin repetir el nombre.
• Un perfil jurídico según el tipo de caso (Laboral, Civil, Penal, Familia…), con pautas propias de esa materia.
• El estado de Google Drive (conectado o no), para habilitar o bloquear esas tools.

Es decir: dos abogados, en dos pantallas distintas, le hablan al "mismo" asistente pero con contextos completamente diferentes.

MCP: las mismas herramientas, dos puertas de entrada

Las tools de Legio están escritas una sola vez, en un formato neutral, y se exponen por dos caminos:

1. Vía el AI SDK, dentro del chat de la app — el camino que usa el abogado todos los días.
2. Vía MCP (Model Context Protocol), un estándar abierto para que cualquier cliente de IA compatible —como Claude de escritorio— se conecte y use esas mismas herramientas.

MCP es, en pocas palabras, un "USB para herramientas de IA": un protocolo común para que un modelo descubra y llame funciones externas sin que cada integración sea a medida. El backend de Legio levanta un servidor MCP que publica manage_contacts, manage_cases, search_jurisprudence y compañía sobre una conexión SSE. La ventaja: el mismo código de negocio sirve para el chat interno y para integraciones externas, sin duplicar lógica.

Cómo se consulta la base de datos (sin romper la seguridad)

Acá es donde la ingeniería se pone seria, porque Legio es multi-inquilino: muchos estudios, cada uno con sus contactos y expedientes, sobre la misma base de datos. Un abogado jamás debe ver datos de otro estudio.

Dos mecanismos lo garantizan:

• Inyección de contexto del lado del servidor. El modelo nunca decide de qué organización son los datos. Cuando pide ejecutar una tool, el backend le inyecta el user_id y el organization_id de la sesión autenticada antes de tocar la base. Aunque el modelo "quisiera" pedir datos de otro estudio, no puede: esos campos los pone el servidor, no el modelo.
• RLS (Row Level Security) en Supabase. Cada tabla tiene políticas que filtran las filas por organización a nivel de base de datos. Es la última línea de defensa: incluso si algo fallara arriba, la base solo devuelve lo que corresponde. La clave de servicio (la que saltea RLS) vive solo en el backend, nunca en el navegador.

Además, cada respuesta descuenta tokens de la cuenta del estudio: antes de procesar se verifica el saldo (si es cero, se corta), y al terminar se registra el consumo real. Así el costo de IA queda medido y atribuido a cada organización.

El recorrido completo de un mensaje

Juntando todo, esto pasa cuando el abogado aprieta Enter:

1. El frontend manda el historial del chat y el contexto de pantalla al backend.
2. El backend verifica el saldo de tokens del estudio.
3. Arma el system prompt dinámico (fecha + pantalla + perfil + Drive).
4. Convierte los mensajes al formato del modelo y mapea todas las tools.
5. Llama a streamText, que arranca el loop: el modelo piensa, llama herramientas, lee resultados, vuelve a pensar… hasta 12 pasos.
6. Cada tool corre en el backend con el user_id/organization_id inyectados y RLS activo.
7. La respuesta se transmite en streaming al navegador, que la muestra en vivo.
8. Al cerrar, se contabilizan y descuentan los tokens consumidos.

En resumen

El asistente de Legio es un agente construido sobre el AI SDK de Vercel: un modelo (Gemini o Claude) con un conjunto de tools que puede encadenar solo en un loop de hasta doce pasos, expuestas además por MCP para integraciones externas. La inteligencia no está en que el modelo "sepa" derecho, sino en darle las herramientas correctas, un contexto preciso de lo que el abogado tiene delante, y una arquitectura que consulta la base de datos en segundos sin jamás cruzar los datos entre estudios. Eso es lo que convierte un chat en un asistente que realmente trabaja.