Skip to content
Nappai Documentation

libSQLRetrieverTool

libSQLRetrieverTool turns a query to your database into a tool for an agent. You write the query once, with blanks for the values that change, such as the order number or the customer’s city. The agent fills those blanks with what the user tells it, the query runs and the agent answers with the results.

This way the agent can only run the query you prepared, with the values you defined. It works with libSQL / Turso databases and also with the other connections that provide Database Info, such as SQLite.

When to use it

  • A customer service assistant has to check an order’s status from its number.
  • You want an agent to search your catalogue by category or price.
  • You need the agent to read data from your database without letting it write its own queries.
  • You want to combine a search by meaning in your database with fixed filters.

Configuration

FieldWhat it does
Database Info (required)The connection to your database. Connect the Database Info output of a database component here, such as libSQL or SQLite.
SQL Query Template (required)The query that runs. It must return a field called text with the information the agent will read. Write {name} where an argument’s value goes, for example SELECT description AS text FROM orders WHERE number = {order_number}.
Metadata SchemaThe arguments the agent must fill in: for each one, its name, type, a description telling the agent what to put, whether it is required and, optionally, a default value. Each argument’s name is the one you use in braces in the query.
Tool Name (required)The name the agent sees for the tool, for example check_order.
Tool Description (required)What the agent reads to know when to use it, for example “Checks an order’s status and delivery date from its number”.
EmbeddingOptional. An embeddings model to search by meaning. If the query includes {vector}, it is replaced by the numerical representation of the search.

The values the agent fills in are passed to the database as data, never as part of the query, so the agent cannot change what the query does.

Output

Tool: the query ready for the agent. Connect it to the agent’s Tools input. The agent gets the rows found, the notice “No se encontraron documentos” (no documents found) if there are no results, or the error message if the query fails.

Example

An online shop wants its assistant to report the status of orders.

  1. Connect the Database Info output of your libSQL component to Database Info.
  2. In Metadata Schema, create the argument order_number, of type text and required, with the description “Order number the customer gives”.
  3. In SQL Query Template, write SELECT 'Status: ' || status || ', expected delivery: ' || delivery_date AS text FROM orders WHERE number = {order_number}.
  4. Put check_order in Tool Name and a clear description in Tool Description.
  5. Connect the Tool output to the agent’s Tools input. When a customer gives their order number, the agent checks it and answers.

Good practices

  • Use this tool only for queries that read data, and connect the database with a user that only has read permission.
  • Write clear descriptions in Metadata Schema: that is what the agent reads to know what value to put in each argument.
  • Limit the number of rows in the query (for example with LIMIT) so the agent doesn’t get more data than it needs.