libSQLRetrieverTool

libSQLRetrieverTool convierte una consulta a tu base de datos en una herramienta para un agente. Tú escribes la consulta una vez, con huecos para los valores que cambian, como el número de pedido o la ciudad del cliente. El agente rellena esos huecos con lo que le dice el usuario, la consulta se ejecuta y el agente responde con los resultados.

Así el agente solo puede hacer la consulta que tú has preparado, con los valores que tú has definido. Funciona con bases de datos libSQL / Turso y también con las demás conexiones que entregan Database Info, como SQLite.

Cuándo usarlo

Un asistente de atención al cliente tiene que consultar el estado de un pedido a partir de su número.
Quieres que un agente busque productos en tu catálogo por categoría o precio.
Necesitas que el agente lea datos de tu base de datos sin darle libertad para escribir sus propias consultas.
Quieres combinar una búsqueda por significado en tu base de datos con filtros fijos.

Configuración

Campo	Qué hace
Database Info (obligatorio)	La conexión a tu base de datos. Conecta aquí la salida Database Info de un componente de base de datos, como libSQL o SQLite.
SQL Query Template (obligatorio)	La consulta que se ejecuta. Debe devolver un campo llamado `text` con la información que leerá el agente. Escribe `{nombre}` donde vaya el valor de un argumento, por ejemplo `SELECT descripcion AS text FROM pedidos WHERE numero = {numero_pedido}`.
Metadata Schema	Los argumentos que el agente debe rellenar: para cada uno, su nombre, su tipo, una descripción que explique al agente qué poner, si es obligatorio y, si quieres, un valor por defecto. El nombre de cada argumento es el que usas entre llaves en la consulta.
Tool Name (obligatorio)	El nombre con el que el agente ve la herramienta, por ejemplo `consultar_pedido`.
Tool Description (obligatorio)	Lo que el agente lee para saber cuándo usarla, por ejemplo “Consulta el estado y la fecha de entrega de un pedido a partir de su número”.
Embedding	Opcional. Un modelo de embeddings para buscar por significado. Si la consulta incluye `{vector}`, se sustituye por la representación numérica de la búsqueda.

Los valores que rellena el agente se pasan a la base de datos como datos, nunca como parte de la consulta, así que el agente no puede cambiar lo que hace la consulta.

Resultado

Tool: la consulta lista para el agente. Conéctala al conector Tools del agente. El agente recibe las filas encontradas, el aviso “No se encontraron documentos” si no hay resultados, o el mensaje de error si la consulta falla.

Ejemplo

Una tienda online quiere que su asistente informe del estado de los pedidos.

Conecta la salida Database Info de tu componente libSQL a Database Info.
En Metadata Schema, crea el argumento numero_pedido, de tipo texto y obligatorio, con la descripción “Número de pedido que da el cliente”.
En SQL Query Template, escribe SELECT 'Estado: ' || estado || ', entrega prevista: ' || fecha_entrega AS text FROM pedidos WHERE numero = {numero_pedido}.
Pon consultar_pedido en Tool Name y una descripción clara en Tool Description.
Conecta la salida Tool al conector Tools del agente. Cuando un cliente da su número de pedido, el agente lo consulta y le responde.

Buenas prácticas

Usa esta herramienta solo para consultas que leen datos, y conecta la base de datos con un usuario que solo tenga permiso de lectura.
Escribe descripciones claras en Metadata Schema: es lo que el agente lee para saber qué valor poner en cada argumento.
Limita el número de filas en la consulta (por ejemplo con LIMIT) para que el agente no reciba más datos de los que necesita.

Componentes relacionados

SQLRetrieverTool: la misma herramienta, recomendada para flujos nuevos.
libSQL: la conexión a tu base de datos libSQL / Turso.
Retriever Tool: búsquedas en una base vectorial como herramienta.