Skip to content
Nappai Documentation

SQLRetrieverTool

SQLRetrieverTool 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.

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, and whether it is required. 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.

Output

Tool: the query ready for the agent. Connect it to the agent’s Tools input. The agent gets the rows found, or a notice if there are no results.

Example

An online shop wants its assistant to report on order status.

  1. Connect the Database Info output of your database component to Database Info.
  2. In Metadata Schema, create the argument order_number, of type text and required, with the description “Order number given by the customer”.
  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 looks it up and replies.