Tools en Laravel AI SDK: un asistente que consulta tus facturas

Hola, bienvenido. En esta lección vamos a darle al asistente de invoices acceso a las facturas. En Laravel AI SDK, una tool es una clase de tu aplicación que el modelo puede pedir que se ejecute: el modelo recibe su nombre, su descripción y los argumentos que acepta, y cuando la necesita para responder, pide la llamada. Vamos a crear 2 tools, ListInvoices y GetInvoice, a hacer que el agente recuerde las conversaciones en la base de datos y a montar la página del asistente, con un límite de preguntas por minuto y sus tests.

Al terminar, un usuario de invoices podrá preguntar en lenguaje natural por sus facturas, desde el navegador, y el asistente le contestará con los datos de la aplicación. Si quieres ver más casos de uso de la IA dentro de una aplicación Laravel, los tienes en el artículo Integrar IA en Laravel en 2026: Guía Práctica con Casos Reales↗ (se abre en una pestaña nueva).

En la lección anterior, el asistente se inventaba lo que sabía hacer, porque no tenía ningún dato de la aplicación: solo sus instrucciones. Una tool resuelve eso, y lo hace sin que el modelo toque tu aplicación. ¿Cómo? El modelo nunca ejecuta código ni toca la base de datos. Lo que hace es contestar con una petición: "llama a ListInvoices con el estado sent". El SDK recibe esa petición, ejecuta el método handle() de la tool dentro de tu aplicación y le devuelve al modelo el resultado, que el modelo usa para escribir la respuesta. Si le hace falta otra tool, vuelve a pedirla, y así hasta que tiene lo que necesita:

Cada tool tiene 3 partes, y las 3 las escribes tú. La descripción le dice al modelo para qué sirve, y es lo que usa para decidir si la llama. El schema define los argumentos que acepta, con su tipo, y el SDK se lo manda al modelo en formato JSON Schema. Y handle() es el código que se ejecuta cuando el modelo la pide, con los argumentos que ha elegido el modelo.

Vamos a crear 2 tools de solo lectura. ListInvoices devuelve las últimas facturas del usuario, con un filtro opcional por estado, y sirve para preguntas como "¿qué facturas tengo enviadas?". GetInvoice devuelve el detalle de una factura, notas incluidas, y sirve para preguntar por una factura concreta. Además, el asistente va a recordar lo que se ha hablado: el SDK guarda cada conversación en 2 tablas, y así el usuario puede preguntar "¿y qué notas tiene la primera?" sin repetir de qué facturas hablaba.