Um agente sobre o seu banco de dados

Tradução automática

Esta página foi traduzida automaticamente do inglês e ainda não foi revisada por um falante nativo; correções são bem-vindas no GitHub. Se algo não bater, vale o original em inglês. O código e os resultados são os mesmos do original, importados dos arquivos testados.

Tarefa: deixar um assistente responder "quais produtos estão acabando?" a partir do banco da loja, sem nunca deixar o modelo escrever SQL.

# 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

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);

A ferramenta é uma função que você escreve, com uma consulta só de leitura. O modelo vê o nome, a descrição e o parâmetro dela; ele escolhe chamá-la e com qual valor, e esse valor é convertido para o tipo do parâmetro antes de a consulta rodar. stock_result.actions lista cada chamada, por extenso.

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

<!-- 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>

No CI, o modelo substituto segue um roteiro curto — chamar a ferramenta, depois terminar:

[
  {"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.\"}"]}
]

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

Uma ferramenta pode fazer tudo o que o corpo dela faz, e um prompt pode levar o modelo a chamá-la: dê às ferramentas só o acesso de que a tarefa precisa.

Testado: no CI estes testes rodam contra um servidor de modelos substituto, que responde a partir da primeira fonte que recebe; antes de cada versão eles rodam contra um modelo de verdade (tests/live_ai/test_cookbook_ai.py). Por isso eles conferem a estrutura — qual fonte, qual ferramenta, o que a página mostra quando algo falha — e nunca as palavras do modelo.

Veja IA-4 e IA-5.