Docs · Concepts

Agents

A model that reads your systems with read-only queries, looks before it decides, and shows every query behind its answer.

An agent is a model that answers a question by reading your data: it finds the tables, looks at the values in them, runs small queries, and says what it found — with every query it ran listed under the answer.

Mosaic uses agents in two places:

• Build with Agent, which writes a data source's query. It explores the database first and runs the query before it hands it over.
• Agents you define, which you attach to an investigation as an Ask an agent step, or run by hand.

Both need a model connected under Integrations and the model features switched on for the workspace. Agents you define are part of Business and above.

#What an agent can do

Values in columns whose names say they hold personal or secret data — people's names, email addresses, phone numbers, card numbers, passwords — are replaced with (withheld) before the model sees them.

Every step is kept: what it searched for, which tables it looked at, each statement as it was sent, how many rows came back, and the first few of them. That list is shown under the answer as What the agent looked at.

#Build with Agent

Open a data source, go to Query, and press Build with Agent. Say what the rows should be — stock on hand per store and item — and the agent:

1. finds the tables and reads their columns;
2. looks at the real values before it filters on them: the distinct codes in a status column, whether a join between two tables actually matches;
3. writes the query and runs it — if it comes back empty, it takes it apart to find which join or condition removes the rows, and fixes it;
4. hands it over with a short summary and Decided for you: what it chose on its own, each with the evidence it saw.

It does not ask questions first. If one of its decisions is wrong, press Change beside it, say what it should be, and it drafts again.

The query uses the check's parameters as {{name}}, so it runs for whatever values the check is given. It is told what the check's other sources return, so it can return comparable columns.

#Defining an agent

Open Agents in the sidebar: the sidebar turns into a list of your agents, with New agent at the top and your knowledge bases under them. Press an agent to open it, or New agent to make one; the arrow at the top goes back to the full sidebar. Each agent has its own address, so a link to one opens it. The settings panel on the right can be dragged wider from its left edge (double-click the edge to reset it). What defines an agent:

• What it is for — instructions in your own words. Say what it should find out and how you would go about it: the tables or documents that matter, the order to look in, what counts as an explanation.
• What it may read — the data sources it may query. Databases it can search and query with SQL; anything else it runs as saved.
• What it may consult — up to five knowledge bases: what your people wrote down about these systems.
• What it is given — its inputs, such as item_id or store_id, each with a type: Text, Number (a decimal comma is read as a point), Date (a day, or TODAY, TODAY-7, START_OF_MONTH as in a check's parameters) or Yes / no. In an investigation each is filled from the row; by hand you type them. A value that is not what its type says is refused before the agent starts, and the agent is told each value's type. In Preview, the pin beside an input keeps the value you typed: Preview opens with it filled in, for everyone trying the agent, until you unpin it. Pin all pins every value at once. A pinned date such as TODAY-7 stays relative. Pinned values are only for trying an agent by hand; in an investigation the inputs always come from the row.

#Knowledge bases

The data says what happened; it rarely says why. That a transfer posts at the receiving store two days after it ships, that one store closed in March, that documents starting TRF- move stock between stores while RTV- ones send it back to the supplier: an agent that has to work this out from queries spends its rounds on it, or never finds it.

A knowledge base is where you write it down once: a name, what it covers, and pages. Write a page in the editor, or upload text files (.txt, .md, .csv, .json and similar). A PDF or a Word file has to be saved as text first. A knowledge base holds up to 50 pages.

On the agent's canvas, knowledge hangs from the agent between the model and the data sources. Press Knowledge in the toolbar, or the + under the agent, to attach a knowledge base or start a new one. Press an attached one to edit its pages. The agent's Save saves its pages too. A knowledge base belongs to the workspace, not to one agent: attach the same one to every agent that reads the same systems, and a correction made once reaches them all. Deleting a knowledge base takes it off every agent.

Your knowledge bases are also listed in the sidebar under Agents, below your agents. Press one to open it on a page of its own, with its own address: edit its pages there, see which agents consult it (Open goes to one), or delete it. That page has its own Save. New knowledge base, at the end of the list, starts one without an agent: write the runbook first, and attach it when an agent needs it.

When the agent runs, it is told which pages there are. It can search them by word (a code, a store, a term) and read a page by its title. Each search and each page read is a step in its log, beside its queries. It is told to treat knowledge as a guide to where to look, not as evidence: what it reports about your data still comes from a query, and where the data and a page disagree, it says so.

#The log

Every run of an agent is kept in its log: from Preview, and from every investigation it is part of. Open an agent and switch from Editor to Logs at the top.

• The list shows each run, newest first: how it ended (Explained, Not explained, Inconclusive, or Failed, Stopped or Out of rounds when it did not conclude), its cause in a line, what it was given, where it came from and how long it took.
• Open a run to read it in full: the finding with its evidence, what happened in plain words (how many queries, on which systems, how many failed, how it ended), what it was given (and the row it investigated, for an investigation), and every step: each query with its statement and the rows it returned.
• Run again with these values puts the run's inputs back in Preview. Copy link copies the run's own address, to send to a colleague.

The log keeps each agent's 200 newest runs; Clear log empties it. The rows kept with each query are the few the agent was shown, with personal values already withheld.

• How it works — the model, and how many rounds of looking it may take before it must answer (3 to 40). One round is one turn of the model, which may run several queries.

Try it runs the saved agent by hand and shows each step as it happens, then its finding.

An agent answers with a finding:

• a verdict — Explained, Not explained or Inconclusive;
• the cause in a few words;
• a short summary;
• the evidence: each fact with the query it came from.

#In an investigation

Add an Ask an agent step, choose the agent, and fill its inputs from the row. See Investigations for when it runs — in particular, it is left for a person in the automatic pass after a check run unless you switch that on, and it never runs from a published page.