An agent over your database

Task: let an assistant answer "which products are running out?" from the shop's database, without ever letting the model write SQL.

yaml

# Recipe: an agent that answers from your database through tools you write.
paths:
  components: ./components
  migrations: ./migrations

datasources:
  db:
    driver: sqlite
    database: ./data/shop.db

llm:
  model: phi3

sql

CREATE TABLE products (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    stock INTEGER NOT NULL
);

INSERT INTO products (name, stock) VALUES
    ('Mug', 40), ('Monitor', 2), ('Cable', 3), ('Keyboard', 25);

The tool is a function you write, with one read-only query. The model sees its name, its description and its parameter; it chooses to call it and with which value, and that value is converted to the parameter's type before the query runs. stock_result.actions lists every call, written out.

xml

<q:component name="Assistant">
  <!-- The model never writes SQL: it picks a tool and its arguments. The
       tool is a read-only query you wrote; its q:param says the argument's
       type, and the model's value is converted to it before the query runs. -->
  <q:agent name="stock" maxIterations="4" timeout="60000" onerror="continue">
    <q:instruction>You help a shop owner. Use the tools to look at the data,
      then answer in one sentence.</q:instruction>

    <q:tool name="low_stock" description="Products with fewer units in stock than `below`">
      <q:param name="below" type="integer" default="5" />
      <q:function name="lowStock">
        <q:query name="rows" datasource="db">
          SELECT name, stock FROM products WHERE stock &lt; :below ORDER BY stock
          <q:param name="below" value="{below}" type="integer" />
        </q:query>
        <q:return value="{rows}" />
      </q:function>
    </q:tool>

    <q:execute task="Which products are running out of stock?" />
  </q:agent>

  <ui:window title="Stock assistant">
    <q:if condition="stock_result.success">
      <ui:text>{stock}</ui:text>
      <q:else>
        <ui:alert variant="warning">The assistant did not finish: {stock_result.error.message}</ui:alert>
      </q:else>
    </q:if>
    <!-- Every tool call the agent made, written out. -->
    <q:loop items="{stock_result.actions}" var="a">
      <ui:text>Called {a.call}</ui:text>
    </q:loop>
  </ui:window>
</q:component>

xml

<!-- Structural checks, never the model's exact words: the same tests run
     against a real model before every release. -->
<q:test name="the agent looks at the data through its tool" page="/">
  <test:visit />
  <test:expect text="Called low_stock(" />
  <test:expect no-text="did not finish" />
  <test:expect table="products" count="4" />
</q:test>

In CI, the stand-in model follows a short script — call the tool, then finish:

json

[
  {"when": "Which products are running out of stock?",
   "replies": ["{\"action\": \"low_stock\", \"args\": {\"below\": 5}}",
               "{\"action\": \"finish\", \"result\": \"Monitor (2) and Cable (3) are running out.\"}"]}
]

text

tests/agent.test.q
  PASS  the agent looks at the data through its tool
1 passed, 0 failed

A tool can do whatever its body does, and a prompt can steer the model into calling it: give tools only the access the task needs.

Tested: in CI these tests run against a stand-in model server, which answers from the first source it is given; before every release they run against a real model (tests/live_ai/test_cookbook_ai.py). That is why they check structure — which source, which tool, what the page shows on failure — and never the model's words.

See IA-4 and IA-5.

An agent over your database ​

An agent over your database