Build an AI agent that asks before it acts

Declare an agent#

1. Start from a template#

   Open Administration › Agents. Under Start from a template, pick the archetype closest to what you want. Each one starts with as little permission as it needs, and you add only what is missing. Most agents are retrieval: they answer from published content and cannot write.

   

2. Fill in the declaration, or describe it#

   The Declare an agent form has a section for each part of the declaration: what it is for, what it may read, what it may do, which other agents it may hand work to, what it remembers between runs, how far it may go on its own, and how much one run may spend. A banner at the top says, as you go, whether the declaration as it stands would be accepted.

   

   If a model is connected, you can open Describe it instead, describe the agent in a sentence, and press Draft it. The model drafts a declaration, Quilzo keeps only the fields a declaration has, and the checker shows what the draft could do before anything is saved. A draft never adds tools or the ability to publish: the screen lists what it left out, and only a person can add those.

   

3. Mark what must wait for a person#

   Under What it may do, tick ask first beside any capability that should stop the run until a person agrees. For an agent that edits pages, that is write_page.

4. Check the map, then save#

   The map under What it reads, and what it may do is drawn from the declaration itself, so the two cannot disagree. Capabilities that ask first are highlighted. Press Declare it.

   

The same thing as a file#

A declaration is one JSON document, so it can be reviewed and kept in version control. quilzo agent new NAME --kind KIND creates one from a template. To declare one written out, save it to a file and pass it to quilzo agent declare, which validates it on the way in:

{
  "name": "returns-editor",
  "kind": "task",
  "purpose": "Keep the Returns and Delivery pages accurate, asking before each change",
  "capabilities": ["list_pages", "read_page", "search_pages", "write_page"],
  "autonomy": "draft",
  "ask_first": ["write_page"],
  "budget": { "steps": 25, "tool_calls": 15, "duration": "10m0s", "money": "0.50" }
}

quilzo agent declare returns-editor.json
quilzo agent show returns-editor --json      # what is saved, as JSON
quilzo agent check                           # does every declaration still validate

Run it#

On the agent's page, under Try it, write what it should do and press Run it once. Tick Let a model choose the actions to have a model decide. Leave it unticked to try every capability once without a model, which costs nothing and shows what this store answers. From the command line:

quilzo agent run --model returns-editor "Explain on the Returns page how to start a return"

A run never has more authority than the person who started it, and never more than the declaration allows.

Approve or decline what it asks for#

When the run reaches a capability marked ask first, it stops. The run's page shows the exact call it wants to make, field by field, with the full JSON one click away, and says what it had read before asking.

• Let it go ahead performs exactly the stored call, through the same limits as everything else. The model is not asked again, so it cannot change the call after you agreed to it.
• Decline refuses it, and the run carries on without it.

quilzo agent approve RUN 3
quilzo agent decline RUN 3

The agent's sponsor decides, as does whoever holds the approve permission on the agent or on the page it would change (see who approves an agent's actions). A model cannot approve its own work, declare an agent, or widen one. What an agent writes is a draft: it goes live only when somebody publishes (see Review, publish and roll back).

Everything waiting, in one place#

Approvals lists everything waiting for you to decide: what agent runs are asking, questions they need answered, actions the reviewer stopped, tool calls held for a second person, acts a case is waiting to have approved, a change waiting for your review, and memories held until somebody confirms them. Each says what deciding commits to: reads, acts, writes, sends, pays, deletes, publishes or answers. quilzo approvals lists the same, with the command that decides each.

When several runs wait on the same action, with the same input and the same reason, and the action only reads or acts, Let all go ahead approves them together. Anything that writes, sends, pays, deletes or publishes, and every question, is decided on its own page.

Questions it cannot answer alone#

An agent that asks a decider a question, and gets an answer less sure than the decider requires, stops and asks a person instead. The run's page shows the question in its own shape, a list of options, yes or no, or a number from 0 to 1, with the model's guess and how sure it was. The run continues with your answer and never with the unsure one.

quilzo agent answer RUN STEP eligible=no

When the store names a reviewer and it refuses an action, the run stops on that action. Let it go ahead performs exactly that action without asking either model again.

Read what it did#

Every run is kept, step by step, as it happens: what it tried, whether that was allowed, how long it took, and what came back. If it read content somebody else could have written, the run says so, names what it read, and its output needs a person before anybody relies on it.

Each step records the tokens and money of the model's choice and of whatever the action charged, at the model gateway's prices, so a run's cost is the sum of its steps. The run's page shows it beside each step. What they cost groups the kept runs by agent, by who started them, by kind of goal or by day; numbers, addresses and quoted words are taken out of goals, so "Refund order 1234" and "Refund order 98" count as one kind of goal. A run a model decided with no price is shown as not priced rather than as free.

The eight templates#

quilzo agent templates lists them with when to use each. Their defaults:

How far an agent may go on its own#

The autonomy you declare is a ceiling. A model reaches it only by passing evaluations, and loses it the moment it follows a planted instruction (see Evaluate agents).

Next#

• Limits that hold

  What an agent can reach, budgets in money, and the exfiltration breaker.

• Evaluate agents

  Test cases with planted instructions, and autonomy that is earned.

• Identity and receipts

  Who answers for each agent, and proof of what a run did.

• Memory

  What agents remember, held when tainted, and forgotten on request.