The Stalwart user guide¶

This guide is for two kinds of reader: the people who build AI agents with Stalwart, and the people who answer for what those agents do, such as a security, risk or compliance team. It explains what each Stalwart Agents product does, how to use it, and, just as importantly, where each of its guarantees stops.

The guardrail¶

The guardrail checks every tool call an LLM agent makes before it runs, whichever framework the agent was built with, and answers allow, ask the person, or refuse, naming the rule. Nothing in it is guessed by a language model.

Learn More

The developer products¶

For teams that build AI agents, an API key gives six more products. The guide calls them by the same names as the website and the API reference.

• The Bot Builder builds an AI agent of your own from the tools your business already has. You describe the agent in one file, and your rules are checked on every tool call before it runs.
• Agent Graph Verification checks every route through an agent, or a team of agents, before it goes live. It reports each route that reaches a tool without the check it should pass, the confirmation it should ask for, or the step that should come first.
• The Guardrail Bug Hunter finds every way through your guardrails to an action they were meant to stop. It shows each one happening, and hands you a fix it has already tested by scanning again.
• Guardrail Verification answers whether an action can ever happen without the condition that should guard it, for one question or a whole table of them. If it can, you get an example of how and a repair; if it cannot, you get a certificate that proves it.
• Guardrail Writing turns a rule written in plain words into a guardrail policy. Your own model writes the draft; Stalwart then checks it and repairs it where it is wrong.
• Random Forest Verification checks a trained random forest model for robustness, monotonicity, fairness and reachability. It can also start from real records and search for the smallest change that would flip a decision.

One agent, in one file¶

You don't need to learn an agent framework to use any of this. A team puts the products to work through a single agent, described in one file: its tools, its rules, and which changes undo which. Before the agent runs, every route through it is checked. While it runs, every message is read and every tool call is checked, on your own machine. And if a run fails halfway, its changes are undone, the last one first. This is the shop agent the guide uses throughout Part I:

# The shop's support desk, and the billing desk it hands refunds to.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider; the key comes from your environment
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # a turn no tool covers is refused, by name
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # every public function of shop/tools.py
rulebook: ./policy.co                      # the rules every call is checked against
facts:                                     # what the rulebook's $card_on_file and $order_paid are
  card_on_file: {from: get_order.card, same: order_id}           # read from get_order's answer
  order_paid: {from: get_order.status == paid, same: order_id}   # for the order the call names
runs: atomic                               # a failed run is undone, last write first
storage: sqlite:///runs.db                 # where runs and waiting confirmations are kept

Part I builds it step by step, using only the words in the file above.

Where to start¶

• If you only read one page: the whole guide, summed up on a single page.
• Quickstart: about fifteen minutes, in the console alone, with no key and no terminal. You start a bot from a template, try it, and run it on your own computer.
• Developer quickstart: about half an hour. You make an account, build a small shop's support bot, check it cannot be misused, talk to it, scan a guardrail policy for holes, and check a proof yourself.
• What this service does, and what it does not claim: chapter 1. Read its second half before you quote a result to anyone.

The guide has five parts: the Bot Builder, the Bot Builder's selector, the Guardrail Bug Hunter, the hunter and the selector together, and verification and writing. If you work in governance or security, chapter 39 is for you: it shows what each product covers in the 2026 OWASP Top 10 lists and the NIST AI Risk Management Framework, and what such a mapping does not mean. The appendix has the reference tables, the glossary and the changelog.

Checking our work without us¶

You don't have to trust us to trust a result. A certificate can be checked with no key, no network and none of our software. The certificate specification explains how to read one, the reference checker is a single file you can read in an afternoon, and the certificate corpus gives you real certificates to try it on.

The guide offline. The whole guide in one file, for reading with no network or for an audit file: English · Portuguese.

Each file's SHA-256 is in SHA256SUMS, so a copy can be checked against the one published here. Links that leave the guide -- the API reference, the website -- need the network, and say so; the offline guide has no search.

Elsewhere¶

• stalwart.it: the products, the plans, and where to register your interest.
• The API reference: every operation, each of which you can try with your own key.
• The package's documentation: the stalwart-agents package, page by page, with its Python reference.

Chapter numbers never change, even when a chapter moves to another page, so an audit file that cites chapter 7 will always point to the same chapter.

If you only read one page¶

This page tells you, in a few minutes, what Stalwart does. Each point links to the chapter that explains it in full, so you can go deeper wherever you need to.

For developers¶

Stalwart also has tools for teams that build AI agents, reached with an API key:

• The Bot Builder builds an agent of your own from tools you already have: Python functions, MCP servers, OpenAPI operations, LangChain tools or a TypeScript project, described in a single agent.yaml file (chapter 30). Every tool call it makes is checked against your rules: allow, confirm or refuse (chapter 32).
• The Guardrail checks every tool call an LLM agent makes before it runs: your list of tools, their arguments, your rules, what the conversation already did, and whether each value in a write was actually said. It answers allow, ask the person, or refuse, naming the rule. It works on its own, in front of MCP tools through stalwart gateway, or inside a Guardrails AI guard, and an MCP server lets you ask what it checks and measure it on your own traces (the guardrail). The same check guards any LLM agent's calls, not only agents built here.
• Agent Graph Verification reports any route through an agent that reaches a tool without the check it should pass, before the agent runs (chapter 47).
• The Guardrail Bug Hunter searches the guardrail rules you already run for every way through to an action they were meant to stop (chapter 28).
• Guardrail Verification proves an action cannot happen without the condition that should guard it, or shows how it can (chapters 3 to 12); Guardrail Writing turns a rule in plain words into a checked policy (chapter 13); Random Forest Verification checks a trained random forest against properties you state (chapter 14).

The developer quickstart takes you through them in about half an hour. When Stalwart proves that something cannot happen, it gives you a certificate you can check with no key, no network and none of our software: read the specification, or run the reference checker over the real certificates in the corpus.

Your account¶

To start, register your interest at stalwart.it; we write back with your access, and you then sign in to the developer console with Google or with a link we email you. Chapter 40 says what each plan includes, and chapter 16 says what we keep, for how long, and what we never keep.

Quickstart¶

This page takes about fifteen minutes. By the end of it you will have a Stalwart account and a bot for a small restaurant that answers customers about the menu, takes their orders and books their tables. You will have chatted with it, and it will be running on your own computer. You need no key, no code and no terminal: the only thing you type outside your browser is one line you copy at the end.

Where a step needs the console, a picture of that console page follows, with the part that matters circled.

Sign up¶

Register your interest on stalwart.it; once we write back, sign in to the console with your Google account or with a link we email you. Continuing accepts the terms and the data processing addendum, which the page links to.

Your bots¶

The first time you sign in, your organisation is made for you, on the free plan, named after your email address; you can rename it on Account. The developer console opens on its Overview; your bots are under Build: open Your bots. Each of your bots will be a card here; for now there is none, so press Start from a template:

Start from a template¶

A template is a bot that already works: it comes with its tools, its rules and its replies. Pick Restaurants and takeaways and press Start from this template:

That is all: your bot is made, with every tool the template comes with, and it opens. Its rules are already set: on the free plan, it asks you before it writes anything, an order, a booking or a change to the menu. It uses no AI model: a message it cannot read gets a polite I can't help with that, with how to reach you. At the top of its page are the two things to do now: run it on your computer, and chat with it.

Below them are its settings, to change whenever you like: its name, the language your customers write in, how to reach you (your bot gives it to anyone it cannot help), a greeting and your logo. Under When your bot doesn't understand you can let an AI model answer what it cannot read, on your own key from your AI provider, which you add on your computer once your bot runs there: Stalwart never sees it. A person's details reach a model only on the Enterprise plan. To set the template's own settings before the bot is made, press Change its settings first instead.

Chat with it¶

On Chat, you chat with your bot here, with its real tools and nothing to install. Press Start chatting and ask it something, such as what's on the menu? or 2 margherita pizzas for Rui, collection at 7pm. When it would change something, such as taking that order, it asks you first. Your conversations are kept with the bot, on the right, to read again or delete. To chat on sample answers instead, with nothing real read or written, tick Practice with sample answers before you start.

Under Chat as, you start as You, the owner; choose One of your customers to see what they see. Your customers can ask about the menu, order and book; what is for you and your staff, such as changing the menu, they never reach: the bot says no, with how to reach you.

Run it on your computer¶

Do this on the computer your bot will run on. Here is how it goes on Windows; a Mac is the same, with Terminal in place of PowerShell.

1. Open your bot from Your bots. Under Your computer, choose Windows, and press Run it on my computer. The console shows the line to paste:

   

2. Press Copy to clipboard. The button says Copied to the clipboard: the line is copied, as if you had selected it and pressed Ctrl and C.

   

   If your browser does not let the page copy, the console selects the line for you instead and says so: press Ctrl and C to copy it.

3. Open PowerShell: press the Windows key, type PowerShell, and press Enter. A window opens with a line that starts PS C:\Users\ and your name.

4. Paste the line: press Ctrl and V, or right-click in the window. The whole line appears after the PS, ending in | iex:

   

5. Press Enter. PowerShell says Setting up your bot. This takes a minute or two., and shows a bar while it downloads what your bot reads with. When it is done it says Your bot ... is running. Its chat: with an address, and Its files: with your bot's folder, and the chat opens in your browser. You can close the PowerShell window then: your bot keeps running.

If something goes wrong, PowerShell says so in a line that starts with Stalwart:, such as a computer with no internet; fix that and paste the same line again.

The line works for seven days, as often as you run it, until you press A new line, which stops the old one working. It installs what your bot needs, with a key made for it that you never see, starts the bot, and opens its chat in your browser. The bot starts again each time you sign in to your computer, and follows what you save in the console: a new version reaches it within a quarter of an hour, and one that takes something away waits until you press Use the new version in its chat.

Your bot keeps its files in a folder of its own, in Documents, Stalwart, under its name: the menu and the orders in Menu.csv and Orders.csv, which open in Excel or Numbers, and the bookings in bookings.csv. Change a price or mark a dish sold out in the file, or ask the bot to do it for you.

Your bot's chat¶

The chat shows your bot's name, its greeting and your logo. Under What I can do, it lists what the person may ask for, grouped by task: each tool's name in bold, what it does, and an example to try. Anyone who writes help gets the same list. Your customers see their tools; you and your staff see yours.

On your computer, the chat also shows you:

• Your files: what your bot saved in its folder, newest first, each to open or download. When a reply saves a file, the reply links it.
• Your bot needs your AI key, where your bot asks first or lets an AI model answer: paste the key your AI provider gave you. It is kept on this computer only, and your bot starts again with it.
• Use it on your phone: press Show the code, and scan it with your phone's camera, on the same Wi-Fi as your computer. Your phone warns that the connection is not private, because your bot made its own certificate; check that the fingerprint starts as the page here says, then go on. Your phone is then signed in as you. Windows may ask whether to let your bot use the network: allow it on private networks.

Where next¶

• To learn what each part of your bot does, read the User Guide.
• To build a bot in code, check it, and use the other products, follow the Developer quickstart.

The guardrail¶

The guardrail checks every tool call an LLM agent makes before it runs, and answers allow, ask the person or refuse, naming the rule that decided. It works with any agent: give it the tools you give your model, and it checks each call the model proposes.

Nothing in it is guessed by a language model: the same call and the same rules always give the same answer.

Guaranteed:

• Every tool call is checked before it runs, by the same rules, and the same call, context and rules always give the same answer.
• A tool not on your list never runs; a call whose values break the tool's own description never runs.
• A write no rule allowed never runs without a person's yes, and that yes covers exactly the call shown.
• A value in a write that nobody said and no tool returned is asked about.
• Nothing in a decision is guessed by a language model.

Not guaranteed:

• It judges tools, arguments, labels, history and rules, not what a reply means.
• It cannot tell a right value from a wrong one that someone did say.
• Your rules are only as complete as you wrote them: the bug hunter looks for holes.
• A tool whose name and description hide what it does may be classed wrongly: mark it.
• Calls made outside the guardrail are not checked.

The steps below follow one support desk, with four tools: look up an order, refund a card, send an email and save a note. The numbers in each picture match the numbered steps under it, and every line in a picture was printed by the guardrail itself.

What each check does¶

Every rule of the guardrail, in the order it is applied; the first that applies decides.

1. Put the guardrail in front of your tools¶

1. In Python, three lines: the guardrail is made from the tools you give your model, and each call is checked before your code runs it. Install it with pip install stalwart-agents.
2. In front of an MCP server, stalwart gateway checks every call on its way to the server. The snippet tool of stalwart mcp writes its configuration for you.

2. Write your rules¶

1. Your rules are a rule sheet: plain YAML a person can read aloud. Here, a refund over 100 needs a manager's approval, and every email waits for a person's yes.
2. The sheet is compiled once; the decisions are then made on your own machine.
3. The sheet is checked against your tools: here, save_note changes something and no rule names it, so you are told, and can decide.

3. A call is allowed, asked about, or refused¶

1. Looking up an order only reads, so it is allowed.
2. A refund of 20 changes something and no rule allows it outright, so it waits for a person's yes.
3. A refund of 150 breaks the rule of step 2, so it is refused, and the answer names the rule and gives an id to look it up by.

4. An amount nobody said is asked about¶

1. The person asked for a refund but never said how much. The model proposed 35 anyway.
2. No one said 35 and no tool returned it, so the guardrail asks the person before anything runs. It never fills a value in, and never changes the call.

5. Add it to your Guardrails AI guard¶

1. Install stalwart-agents[guardrails] and add our validator to your guard. A refused call arrives as Guardrails AI's own failure, with the rule's sentence.
2. With on_fail=gai.ask, a call that needs a person is held back, and gai.asked(guard) gives you the sentence to show them. On their yes, validate the same call again with the token gai.approve gives.

6. Ask the MCP server what it can do¶

1. Add stalwart mcp to your AI assistant (Claude Code, Cursor, VS Code) and ask what the guardrail can check: it answers from the guardrail's own list.
2. Ask it to build a guardrail for your tools: the build-guardrail prompt walks your assistant through it with you, and the assurance-plan prompt through the rest of the suite -- the hunt, the red team, proofs and certificates.

Chapter 53 is the server in full: adding it, its tools and prompts, and where its results appear in the developer console.

7. Measure it on your own calls¶

1. replay runs your agent's past calls through the guardrail: how many it would have allowed, asked about and refused, by which rule, and whether a second run gave the same answers.
2. Label each call with what should have happened, and evaluate counts the false alarms (calls that should run, stopped) and the misses (calls that should be stopped, let through).

8. Check your rules for holes¶

1. hunt runs the bug hunter on your rule sheet. Each finding is something your rules let through, with what to look at; here, it asks you to say what refund_card must never run without, since no table of yours says so.

9. Why was this call refused?¶

1. explain_decision reads back a decision by its id: the rule, what it read, the tool and the names of its arguments. The values themselves, and anything the person said, are never kept.

Going further¶

The full manual, in English and Portuguese, is in the SDK documentation: building a guardrail, the checks, the rule sheet, evaluating it and connecting it. stalwart mcp serves the same pages to your assistant.

53 · The MCP server¶

stalwart mcp gives your AI coding assistant -- Claude Code, Cursor, VS Code -- the whole suite as tools: the guardrail, built with you and dry-run on your own calls; the gateway; the bug hunter; the red team; formal verification of your rules and of an agent's graph; and certificates, checked on your machine. Your assistant does each step through the server and brings you the result, with the page of the developer console that shows it and the chapter of this guide that explains it.

The server runs on your machine, over stdio. It calls Stalwart's service only where a step already does -- compiling a rule sheet, a hunt, a red team, a proof -- and it never calls a model: where a step needs one, such as drafting a rule sheet from your policy, your own assistant does it, through a prompt, and the server checks what it made.

Adding it to your assistant¶

In your project's folder:

$ stalwart mcp --config claude      # prints: claude mcp add stalwart -e STALWART_MCP_HOME=<this folder> -e QLS_API_KEY=<your key> -- ...
$ stalwart mcp --config cursor      # the mcpServers entry for Cursor
$ stalwart mcp --config vscode      # the servers entry for VS Code

Run it in your project's folder: the configuration names that folder (STALWART_MCP_HOME), so the server's files go there, never into the home folder a client starts servers in. Put your key in the configuration too: a server reads its environment once, when it starts, so a key set afterwards needs the server started again (status says so).

Then ask your assistant to call status: it answers with the folder the server works in, whether it has your key, your plan, and how much of each meter is left this month.

How it leads your assistant¶

An assistant uses what a server shows it, so the server shows it everything, and says where to go next:

• Its instructions, which your assistant reads first, name every product and the tool for each, and tell the assistant to do every step through these tools rather than by writing code or reading the package's source.
• Every answer says what comes next (next): what the step did not cover, and the tool that does. After a hunt that found nothing, for example, it says what the hunt did not read, and that verify_rules proves one action against your rules.
• Every answer that leads to a page gives its address: console for the developer console's page that shows the result, guide for this guide's chapter on the step. links gives every address at once (below).
• The assurance-plan prompt walks your assistant through every level in turn, says what each covers and what it uses of your plan, and asks you which you need.

A session that starts from nothing goes like this: status; catalogue_from_server on your tools' server; writes_file, and the kinds you check; a rule sheet your assistant drafts from your policy in plain words, which you read; compile_rules and lint_rules; check_sequence on a conversation's calls; hunt into a project; and, where you want it proved, verify_rules on the proof profile and check_certificate on what it wrote.

Its tools¶

Asking what it can do¶

Building and dry-running a guardrail¶

check_call answers one call alone. Order rules (after), limits (at_most) and confirmations are met only across a conversation, so try them with check_sequence: each call is answered with what the calls before it ran.

Measuring, hunting and red-teaming¶

Proving¶

Its prompts¶

• assurance-plan: every level of assurance in turn -- build, dry-run, hunt, red team, prove, certify, monitor -- what each covers and does not and what it uses of your plan; your assistant asks which you need and does only those.
• build-guardrail: the whole build, in order: tools, kinds, a rule sheet drafted from your policy in plain words, compile and lint, dry runs, search and hunt, the snippet. Your assistant drafts the sheet; you read it before it is used.
• classify-tools: your assistant proposes kinds for the tools the inference is unsure of.
• set-up-guardrail: a recipe from how_to, followed step by step.
• evaluate-guardrail: replay and evaluate on your calls, with nothing quoted from them.

Results in the developer console¶

What the server does with the service is listed in the developer console, under your organisation:

• Findings: hunt with a project (a name; the project is made the first time) stores the scan against it, on a branch and at a commit where you give them. The answer gives the project's address on the Findings page, and each finding's own. There you accept a finding with its reason, or leave it to fix, and the next scan of the project reads your decisions (chapter 28).
• Jobs: every hunt, red team and proof is a job, with its state, its verdict and its files, a certificate among them (chapter 9).
• Usage: what each meter has used this month against its cap -- status gives the same figures to your assistant (chapter 16).

links gives your assistant every address: each developer console page with what it holds, and where to sign in; this guide's chapter for each product; the API reference, the package's documentation, the package and where to sign up. links(about="findings") narrows each list to what names it. Chapter 5 has every console page.

A proof, or the solver's word¶

verify_rules asks one question -- can this action run without this condition? -- and answers it on the profile you name (chapter 10):

• Yes comes with the witness: the conversation in which it runs. Fix the rule it passes, compile, and ask again.
• No, on proof or patch, is a derived proof, with a certificate. The server writes it to certificates/, and check_certificate checks it on your machine, offline, with the checker the package carries (chapter 7).
• No, on fast, is the solver's word, with no certificate. The answer says so, and says to ask again on proof for one.

A proof answers the question asked, and no other (what this proves). verify_graph proves an agent's graph before it is deployed (chapter 47).

The files it reads and writes¶

Every path is inside the folder the server works in; a path that would leave it is refused.

Plan and quota¶

Hunts, red teams and proofs are the service's, and count against your plan; status says what is left before your assistant starts one, and a proof on the proof profile is counted apart (chapter 16). Building, dry runs, replays and checking a certificate run on your machine, and count nothing.

The limits¶

• The server leads your assistant; it does not make it follow. An assistant that writes its own code instead still can, and its results are its own.
• A report holds tool names, rule names, counts, decision ids and digests, never an argument value or a word a person said. To see a finding's witness in full, open its page in the console.
• The red team reads your tools' server, not your agent's own routing: verify_graph is the step for that.

Developer quickstart¶

This page is for developers, and takes about half an hour; to make a bot in the console alone, with no key and no terminal, start with the Quickstart instead. By the end of it you will have a Stalwart account and built a support bot for a small online shop. You will also have checked that the bot cannot charge or refund a card without the checks you gave it, read every message its words can make, and talked to it. Last, you will scan a guardrail policy for holes, check an agent built without Stalwart, and get a proof you can check yourself.

You will work in two places: your terminal, where you run the commands and the Python on this page, and the Stalwart console in your browser, where your account, your keys and the results of your checks live. Where a step needs the console, or leaves something there for you to look at, a picture of that console page follows, with the part that matters circled.

Every output on this page is exactly what the code above it printed when this guide was built, so what you see when you run it should match.

The guardrail¶

The guardrail checks every tool call an LLM agent makes before it runs, whichever framework the agent was built with, and answers allow, ask the person, or refuse, naming the rule. Nothing in it is guessed by a language model.

Learn More

Your account, and its first key¶

Everything starts with an account. Register your interest on stalwart.it; once we write back, sign in to the console with your Google account or with a link we email you; continuing accepts the terms and the data processing addendum, which the page links to:

The first time you sign in, that is all: your organisation now exists, on the free plan, named after your email address until you rename it on Account, and the developer console opens on its Overview. This page needs an API key, so open Keys, say what the key is for, and press Mint a key. This is the only time you will ever see the key: we keep only a hash of it, so nobody, us included, can show it to you again. Copy it somewhere safe now:

If you lose it, or want a separate key for each program that uses Stalwart, mint another the same way. The page lists each key by its public id, a short label that tells your keys apart but cannot be used in place of the key (chapter 5):

Install, and your two keys¶

Now install the package, give it your key, and let this machine run your bots:

$ pip install "stalwart-agents[anthropic]"    # or openai, google, mistral, ollama; or none, for no model
$ export QLS_API_KEY=qls_live_...
$ stalwart licence activate

QLS_API_KEY is the Stalwart key you just copied. Keep it apart from the other key you may have, your model's key: that one comes from your model provider, such as Anthropic, and stays in your own environment under the provider's usual name, such as ANTHROPIC_API_KEY. You never type it into our console (chapter 5). The last command, stalwart licence activate, registers this machine as one your bots may run on (chapter 38).

An agent, its first draft refused¶

The bot you will build is the support desk of a small shop. It can look up orders, charge a card, send a receipt, and pass refunds to a separate billing desk. The whole bot fits in one file: the tools it may use, a sentence for each saying what it does, and the billing desk it hands refunds to (chapter 30). Here is a first draft:

# The shop's support desk, and the billing desk it hands refunds to: the first draft.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider; the key comes from your environment
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # a turn no tool covers is refused, by name
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # every public function of shop/tools.py
rulebook: ./policy.co                      # the rules every call is checked against
facts:                                     # what the rulebook's $card_on_file and $order_paid are
  card_on_file: {from: get_order.card, same: order_id}           # read from get_order's answer
  order_paid: {from: get_order.status == paid, same: order_id}   # for the order the call names
runs: atomic                               # a failed run is undone, last write first
storage: sqlite:///runs.db                 # where runs and waiting confirmations are kept

Beside it sits a rulebook, which says when a charge or a refund is allowed to happen: a refund, for example, only for an order that was paid. Suppose a teammate, in a hurry, added one more rule so that a customer who types just refund it gets their refund straight away:

# Added in a hurry: a refund, on the intent alone.
define user ask quick refund
  "just refund it"

define flow quick refund
  user ask quick refund
  bot execute_refund_card

Before this bot answers a single customer, check it with stalwart verify. This is everything it does, in order:

• It reads the bot's file. It loads agent.yaml and builds the bot from it: the two desks, their tools, and the rulebook the file names.
• It reads your tools' code, on your machine. Every source file in the bot's folder, in Python, JavaScript, TypeScript or Go, is read for the ways code leaks secrets or reaches where it should not: turning off the check that a website is the one it claims to be, writing a password into a log, or sending a request to an address a customer typed. Only the number of problems found is sent to Stalwart; your code stays on your machine. Every problem found fails the check.
• It compiles your rulebook and lints your tools. The rulebook becomes the checks every tool call goes through while the bot runs, compiled as the bot compiles it when it starts, and the lints list what your tools leave unsaid, as warnings. Nothing of your bot is kept on Stalwart's service.
• It searches every route through the bot. On Stalwart's service, it follows every way a conversation can go through the two desks, looking for one that reaches a tool without its check, without the confirmation it asks for, or before the step it must come after.
• It prints what it found, and a verdict. Each problem, the most serious first, and then whether the bot passes.

How it ends tells a script what happened: exit status 0 means the bot passed, 1 that it failed, 2 that the file could not be read, and 3 that nothing was checked. Chapter 31 has the options, such as --keep to save what was checked in a folder, and --replay to replay each problem found with stand-ins for your tools:

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Lints from the runtime (the rulebook's error stops the agent at its start; no other blocks it):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it
  rulebook_unsupported (error) on policy.co: line 30: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow. The rulebook was not compiled.

Code checks: no finding in 8 file(s) (rules d656f9ab32d3).

Blocking: 2 findings that block this agent until fixed, or accepted with its reason:

QG002 Critical on execute_refund_card (policy.co:19)
  The policy gates 'execute_refund_card' on 'order_paid', and there is a way past it.
  OWASP LLM03:2026, ASI02:2026

QG005 High on execute_refund_card (policy.co:30)
  line 30: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow.

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: failed. This agent is blocked by the 2 blocking findings above and the rulebook it could not start with. The warnings do not block it.
$ echo $?
1

It failed the draft, and says why three times over. The refund can now be started from two places, the careful rule and the hurried one, and the hurried one checks nothing: a customer who typed just refund it would be refunded whether they had paid or not. The compiler refuses the rulebook at line 30, where the hurried rule starts the refund (rulebook_unsupported), so the bot would not even start with it; the search finds the refund started from two flows (QG005) and a way past the check that the order is paid (QG002). The command ended with status 1, so a build pipeline running it would stop here too (chapter 46).

The draft fixed, and verified¶

The fix is to have one rule decide every refund. The hurried sentence moves into the careful rule, so just refund it is now treated like any other refund request, and checked the same way:

# A quick refund is a refund: its sentence joins `ask refund`, so the one guarded flow decides it.
define user ask refund
  "refund order 4411"
  "give the customer their money back"
  "just refund it"

define flow refunds
  user ask refund
  if $order_paid
    bot execute_refund_card
  else
    bot refuse

The search also gave the draft two warnings, which do not block the bot. Two lines in agent.yaml settle them (chapter 31). budget: caps how many calls one run may make, so the bot cannot go round in circles (QG023). undo: none says honestly that a refund cannot be taken back, so nothing pretends to undo it if a run fails halfway (QG105). Here is the finished file. Its last lines give the bot some work to do on its own, which you will meet further down:

# The shop's support desk, and the billing desk it hands refunds to: fixed, and given its morning's work.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider; the key comes from your environment
    tools: [get_order, list_orders, next_unpaid_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # a turn no tool covers is refused, by name
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # every public function of shop/tools.py
  - {name: refund_card, undo: none}        # a refund is not taken back: a failed run leaves it done
rulebook: ./policy.co                      # the rules every call is checked against
facts:                                     # what the rulebook's $card_on_file and $order_paid are
  card_on_file: {from: get_order.card, same: order_id}           # read from get_order's answer
  order_paid: {from: get_order.status == paid, same: order_id}   # for the order the call names
budget: {max_steps: 20}                    # the most calls one run may make
runs: atomic                               # a failed run is undone, last write first
storage: sqlite:///runs.db                 # where runs and waiting confirmations are kept
job:
  title: Shop support desk
  purpose: answers customers about their orders, and charges the unpaid ones
  manager: owner
  hours: {days: [mon, tue, wed, thu, fri], from: "09:00", to: "17:30", time_zone: Europe/London}
tasks:
  charge_unpaid:
    title: Charge the oldest unpaid order
    agent: desk
    tools: [next_unpaid_order, get_order, charge_card]   # read first, then the one write
    starts_at: suggest                     # a person approves each run on Today
    triggers: [weekday_mornings]
triggers:
  weekday_mornings: {kind: schedule, at: "09:00", days: [mon, tue, wed, thu, fri]}

Run the check again:

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 8 file(s) (rules d656f9ab32d3).

No findings.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent.
$ echo $?
0

Read it from the top:

• Compiled the rulebook policy.co: the rules the bot runs under are the ones this run checked, compiled as the bot compiles them when it starts.
• Lints from the runtime: what your tools leave unsaid. None of them stops the bot. Here they say three things. Nothing tells the bot that sending the same charge or refund twice makes only one, so when one fails without saying whether it went through, a person decides instead of the bot trying again (not_retry_safe). Nothing describes what the tools answer, so the bot cannot report their outcome in its own words (without_result_schema). And the desk can charge a card while only the billing desk can refund one, so a run at the desk that fails halfway cannot undo its charge (out_of_reach). Chapter 34 shows the line in agent.yaml that settles each one.
• Code checks: how many of your files were read, with no problem in any of them, and the version of the rules they were read with.
• No findings: the search found no route through the bot to a charge, a refund or a receipt without its check, the confirmation it asks for, or the step it must come after, to the depth it searched (chapter 31).
• Rules with nothing to read: checks that look at something you declare about your tools, such as an argument that is run as code or a tool that reads confidential records. This bot declares none of these, so these checks had nothing to look at, and the list names them (chapter 31).
• Gate: the verdict. passed means nothing blocks this bot, and the command ended with status 0.

Nothing of your bot was kept on Stalwart's service: your tools and your rulebook are the files in your folder. The search itself ran on Stalwart's service, and it is listed on the developer console's Jobs page, which you will look at at the end.

Every way a customer can say it¶

The search you just ran follows routes through the bot. The wording check tests the messages themselves: it writes out every message a customer could send using the words the bot knows, and reads each one. It runs on Stalwart's service when you hand the bot's tools to the bug hunter with client.hunt. This is what it does:

• It gathers the bot's words. These are the words of your tools' names and descriptions, the everyday names in also_called, the words of your vocabulary, the numbers, dates and addresses the tools take, and the small words that join a sentence, such as not, and then or to. Any other word means nothing to the bot, so one made-up word stands for all of them.
• It writes every message those words make, up to a size. Each request has up to three words that name something, such as what to do, what to do it to, and a value like an order number. A message has up to two requests, and up to one typing mistake.
• It reads each message with the same reader your bot runs, exactly as it would read a customer's, in the language your console's Settings page names (below).
• It checks each reading for three mistakes: a message that says not to do something, such as don't charge order 4411, that does it anyway; a message that only asks to see something that changes something instead; and a message that sends data out, such as to an email address, that the bot does not refuse.
• It checks that other words change nothing. It puts made-up words into the messages and checks that every answer stays the same. That is why the messages built from the bot's own words stand for every message a customer could send.
• It reports how far it got. For each desk, it says how many messages it built, and whether it read them all in the two minutes it has or ran out of time first. It reads the shortest messages first.

The bug hunter reads the bot's tools from a catalogue file, which Agent.catalogue() writes from agent.yaml:

catalogue = Agent.from_file("agent.yaml").catalogue()    # the bot's tools, as the reader reads them
with open("catalogue.json", "w", encoding="utf-8") as file:
    json.dump(catalogue, file)

result = client.hunt(model="catalogue.json", gate=True)    # the wording check runs on Stalwart's service
wordings = result.wordings
limits = wordings.bounds
print(f"Sentences built from the bot's own words: {wordings.total:,}")
print(f"  each with up to {limits['content_slots']} words that name something, "
      f"{limits['instructions']} requests in one message and {limits['slips']} typing slip")
for desk in wordings.agents:
    print(f"  {desk.agent}: {desk.read:,} read, every one ({desk.completeness})" if desk.completeness == "exhaustive"
          else f"  {desk.agent}: {desk.wordings:,} built, and the two minutes ran out before all were read ({desk.completeness})")
print("Findings:", ", ".join(finding.rule for finding in result.findings) or "none")
print("Gate passed:", result.result["gate"]["passed"])

Sentences built from the bot's own words: 3,502,934
  each with up to 3 words that name something, 2 requests in one message and 1 typing slip
  billing: 359,010 built, and the two minutes ran out before all were read (partial)
  desk: 3,143,924 built, and the two minutes ran out before all were read (partial)
Findings: QG307, QG102, QG102, QG102, QG202, QG324
Gate passed: True

Read it from the top:

• The size of the search: over five million messages, most of them for the desk, which has more tools and so more words. Both desks say partial: the two minutes ran out before every message was read. A partial search reports what it found in the messages it read, and never says the rest are clean.
• QG307: read_inbox reads from the outside world and takes a folder, which is a place, and it runs without asking. A message could try to use it to send the inbox somewhere. The check wrote such messages and none of them did it, so this is a point for a person to look at, rated High. Had one of them done it, it would be Critical, and it would block.
• QG102, three times: a typing slip alone reached a write: acharge the card, arefund the card and asend the receipt. The bot does not run these: it asks the customer first. They are listed so that you check your host asks too, which stalwart serve does.
• QG202: hand_off, the tool that passes a customer to the billing desk, was understood from its name, because nothing declares what it does.
• QG324: messages of one shape reach send_receipt, and none of your test cases has that shape. The finding comes with examples of it for you to label.
• The gate passed: none of these blocks a release. A new Critical finding would.

Attacked before launch¶

A bot that reads email can be tricked by what it reads. The verification above finds every route a hostile text could take; stalwart redteam then runs each route it found on the bot itself, on your machine, as it runs for customers, with every tool replaced by a stand-in that records the call, so nothing real is charged or sent (chapter 33):

$ stalwart redteam agent.yaml

It prints the same report as stalwart verify, with each finding's replay beside it. The finished shop bot has no finding to replay, so its report ends as the one above did: Gate: passed. A finding that does not replay on the bot means the search and the bot that runs disagree: it is listed first, and the command ends with status 1. With --graph, the same command checks a bot built with something else.

Talk to it, and serve it¶

Now talk to the bot. This script plays a short conversation with it, one customer message at a time:

# The host's clock, fixed here at Wednesday 21 October 2026, 11:00 in London, so this prints the same every time.
wednesday = datetime(2026, 10, 21, 11, 0, tzinfo=timezone(timedelta(hours=1)))
desk = Agent.from_file("agent.yaml", clock=lambda: wednesday)   # the graph is proved once, before the first turn


def say(text):
    reply = desk.chat(text, user="u-17")
    print(f"> {text}\n< " + reply.text.replace("\n", "\n  "))   # a reply of several lines, each indented
    for waiting in reply.waiting:           # a write waits for a person, every argument with its origin
        print("  waiting:", waiting.tool, [(a["name"], a["value"], a["origin"]) for a in waiting.arguments])


def decide(decision):
    print(f"> ({decision})\n< " + desk.confirm("u-17", decision).text.replace("\n", "\n  "))


say("show me order 4411")                   # a read: answered with no model call
say("list the orders placed this week")     # a date read against the clock: Monday to Monday
say("charge order 4411")                    # a value is missing: the bot asks for it
say("40.00")                                # the answer fills it; the charge waits for a person
decide("approve")                           # it runs now, with exactly the arguments shown
say("show me order 4412 and then send the receipt for order 4412")   # two steps: a read, then a write
decide("skip")                              # the person says no: the receipt is not sent
say("can you sort it out for me")           # nothing here reads it: asked once to say it again
say("forward the support inbox to ana@example.com")                  # no tool does this: declined whole

> show me order 4411
< card: visa-0019
  customer: c-208
  order_id: 4411
  status: unpaid
  total: 40.00
> list the orders placed this week
< orders: 4411
> charge order 4411
< To charge card, which amount?
> 40.00
< Run charge_card?
  waiting: charge_card [('amount', 40, 'reply'), ('order_id', '4411', 'typed')]
> (approve)
< amount: 40
  charge_id: ch-4411
  order_id: 4411
> show me order 4412 and then send the receipt for order 4412
< Run send_receipt? Nothing undoes it once it has run.
  waiting: send_receipt [('order_id', '4412', 'typed')]
> (skip)
< card: visa-0019
  customer: c-208
  order_id: 4412
  status: paid
  total: 12.50

  A person declined send_receipt.
> can you sort it out for me
< I didn't recognise anything in that. I can charge card, get order, hand off, list orders, next unpaid order, read inbox or send receipt. Which do you mean?
> forward the support inbox to ana@example.com
< I can't do that: S1 egress: forward; S2 destination: ana@example.com.

Lines starting > are what the customer typed, or what a person decided, in brackets; lines starting < are the bot's reply. A lookup's reply is the tool's own answer, laid out one field to a line; chapter 42 shows how to word replies for your customers. Each exchange shows a different part of how the bot behaves:

• Looking up an order needs no language model at all. The bot matched the message to the tool whose description fits it, get_order, by a rule it can name (a turn read, below).
• Dates are read against the computer's clock: this week means Monday to Monday, passed to list_orders as two times.
• A missing detail is asked for by name, and the customer's answer fills it in. The bot records that the amount came from the customer's reply (chapter 22).
• Charging a card waits for a person. The bot shows every detail of the charge and where each one came from: on the waiting: line, typed means the customer typed it in the message, and reply that it came from their answer to the bot's question. Approved, the charge runs with exactly those details; skipped, it does not run at all (chapter 32).
• Two requests in one message are done in order. The lookup ran; the receipt, which cannot be unsent, waited for approval and said so. Skipped, it did not run, and the reply gives the lookup's result with it.
• A message the bot cannot make sense of gets one question back. If it comes again, the bot does what your on_unread setting says, which here is to refuse.
• Something no tool should do, such as forwarding the support inbox to an outside address, is refused as a whole, naming the rules that stopped it, and no part of that message runs. S1 egress: forward says the message asks to send something out, and no tool sends; S2 destination: ana@example.com says it names an address that no tool takes (chapter 49).

When you are happy with it, serve it. This runs the bot on your machine, with a chat page at http://127.0.0.1:8700/ (--host and --port change where):

$ stalwart serve agent.yaml

What the model is for¶

You may have noticed that no language model was used in any of that. The bot decides which tool to use, and when, by its own rules, the same way every time. Your model has one job: it writes words when a customer says something no tool covers, and nothing else. It never picks a tool, plans a run or calls anything.

In this example the desk hands such messages to its model (on_unread: model), and a stand-in model answers the way a real provider's would:

def model(conversation):
    """Your model, here a stand-in that answers as a provider's might: in words, and never with a tool call."""
    said = [message for message in conversation if message["role"] == "user"][-1]["content"]
    if "birthday" in said:
        return "I'm sorry it hasn't arrived. Tell me the order number and I'll look it up for you."
    return "Don't worry: I've refunded order 4411 in full."


desk = Agent("desk", tools=[get_order, charge_card, refund_card], model=model, on_unread="model")
for text in ("my parcel never arrived",                     # nothing reads it: asked once to say it again
             "it was a birthday present and I'm upset",     # still nothing reads it: the model answers, in words
             "please make this right"):                     # the model claims a refund nobody made
    print(f"> {text}\n< {desk.chat(text, user='u-18').text}")

> my parcel never arrived
< I didn't recognise anything in that. I can charge card, get order or refund card. Which do you mean?
> it was a birthday present and I'm upset
< I'm sorry it hasn't arrived. Tell me the order number and I'll look it up for you.
> please make this right
< Not done: refund card.

The first message gets one question back, listing what the bot can do. The second reaches the model, which answers kindly in its own words. The third shows why those words are checked before any customer reads them: the stand-in model above answered Don't worry: I've refunded order 4411 in full, but nothing was refunded, so the reply check replaced the claim with what was actually done, Not done: refund card (chapter 42). What a model says is always held to what the bot really did.

If you prefer, you can let the model choose tools itself. Every call it makes is still checked, but you give up the guarantee that the same message always leads to the same call (chapter 45).

A calculation no tool answers¶

A customer asks: what is the average total of orders 4411 and 4412? No tool does averages. The bot plans it as two lookups and a calculation, and your model writes the small function that does the arithmetic. The model is told the field names and the type of the answer, but never sees the customers' actual values. Before the function runs, it is read, and refused if it opens a network connection, reads a file or imports anything outside a short list of allowed modules. It then runs in a sandbox on your machine, a fresh container with no network and nothing of your machine's, and its answer is checked to be of the type asked for (chapter 23):

def write(prompt):
    """Your model: given the result type and the sources' field names -- never a value -- it writes the function."""
    return ("def compute(data):\n"
            "    totals = [float(order['total']) for order in data.values()]\n"
            "    return sum(totals) / len(totals)\n")


with Client() as client:
    plan = client.plan("what is the average total of orders 4411 and 4412", agent="desk", catalogue=catalogue)
    print(plan.outcome, "|", [step.selection.tool if step.kind == "tool" else step.kind for step in plan.steps])
    step = next(step for step in plan.steps if step.kind == "compute")
    sources = [{"tool": "get_order", "result": get_order(plan.steps[i].selection.arguments["order_id"])}
               for i in step.compute["sources"]]
    done = client.compute(step, sources, model=write)
    print(done.state, done.result, done.result_type)

run | ['get_order', 'get_order', 'compute']
succeeded 26.25 number

The first line is the plan: two get_order lookups, then the calculation. The second is the result: the function ran, the average is 26.25, and it is a number, as the plan asked.

A question your documents answer¶

Customers also ask how the shop works, such as how long a refund takes. No tool answers that either, but your own documents do. stalwart sources build indexes them on your machine, and with on_unread: answer the bot replies with the passage that answers the question. Under the extract setting used here, no model is involved at all (chapter 44):

desk = Agent("desk", tools=[get_order, charge_card], on_unread="answer",
             answers={"index": "sources.json", "composer": "extract"})   # the passage itself, no model
for text in ("How long does a refund take?", "Can a gift card be refunded?"):
    print(f"> {text}\n< {desk.chat(text, user='u-19').text}")

$ stalwart sources build docs/delivery.md docs/refunds.md --out sources.json
Indexed 2 document(s), 3 passage(s), into sources.json (ba9e751e249e).
$ echo $?
0
> How long does a refund take?
< A refund reaches the card the order was paid with in three to five working days.
> Can a gift card be refunded?
< An order can be refunded within 30 days of delivery. A gift card cannot be refunded.

stalwart sources build cut the two documents into passages, short pieces that each answer one thing, and the code in brackets identifies this index. Each reply is the passage, or passages, that answer the question, word for word from your documents. A request to actually do something is never answered from documents: it always goes to its tool, with its confirmation.

Work it does by itself¶

Remember the last lines of the finished agent.yaml? They give the bot a job, and one task within it:

job:
  title: Shop support desk
  purpose: answers customers about their orders, and charges the unpaid ones
  manager: owner
  hours: {days: [mon, tue, wed, thu, fri], from: "09:00", to: "17:30", time_zone: Europe/London}
tasks:
  charge_unpaid:
    title: Charge the oldest unpaid order
    agent: desk
    tools: [next_unpaid_order, get_order, charge_card]   # read first, then the one write
    starts_at: suggest                     # a person approves each run on Today
    triggers: [weekday_mornings]
triggers:
  weekday_mornings: {kind: schedule, at: "09:00", days: [mon, tue, wed, thu, fri]}

A task is work the bot does without being asked. It names the tools it uses, lookups first and then changes, and the triggers that start it. This one is a schedule: it starts at a set time on the days named, in the job's time zone. Other triggers start a task when a tool's data changes, or when a mail, a webhook, a form or a message arrives.

stalwart serve runs the tasks. When one is due, the bot does the lookups, each checked like any other call, and puts the changes they lead to on its Today page as a card for a person to approve. Nothing is changed before someone approves it (starts_at: suggest), and the approval covers exactly the plan on the card and nothing else. Here is what Today showed at 09:00 on Monday, and what ran once the card was approved:

09:00, Monday: the host started charge_unpaid by itself
On Today: Charge the oldest unpaid order (suggest)
  looked up first: next_unpaid_order, get_order
  it will: 1. charge card: amount 40, order id 4411
  decisions: approve, edit, reject
Approved with a passkey: the run is done
  charge_card ran: {'amount': 40.0, 'order_id': '4411'}

The card names the task, the lookups it already made, and the change it will make, with its values. The person can approve it, edit the values first, or reject it. Here it was approved with a passkey, the sign-in kept by their phone or computer, so the record shows who approved the charge, and then the charge ran.

If the computer was asleep when a task came due, a laptop for example, the task runs when it wakes, as long as it is still within the task's window. After that, it waits on Today as Missed, with a Run now button.

Your users' language¶

The bot reads one language for your customers' messages, English or Brazilian Portuguese, and you choose which on the console's Settings page, under Language the selector reads. It never guesses: a message in another language is not read at all (chapter 20). With Portuguese chosen, the bot understands mostre o pedido 4411, asks Para charge card, qual amount?, and says Não posso fazer isso when it refuses. The Portuguese quickstart builds this same shop in Portuguese.

The words that are yours stay yours to write in your customers' language:

• your tools' words: their descriptions, the everyday names customers use for them (also_called), and the questions your confirmations ask (confirm_with);
• your rulebook's sentences, which its rules recognise;
• the messages about what was done: replies: {language: pt} gives you the standard ones in Portuguese, and any you write yourself are in whatever language you write them (chapter 42).

If your tools are named in English, give them your customers' own words, because one word can mean different things: a pedido is an order in a shop and a request at a service desk. Put those words in also_called, or in the vocabulary file for that language, which you can publish yourself or let Stalwart learn from your customers' thumbs up and down (chapter 25).

A turn read¶

Underneath every conversation, each message is read before any model is called, and the reading ends in one of three ways: a tool with its values, a question back, or a refusal. Each comes with the rule that decided it, so you can always see why the bot did what it did (chapter 20):

def show(turn, plan):
    print(f"{turn!r}: {plan.outcome}")
    for step in plan.steps:
        print(f"  {step.kind} | {step.decided_by} | {step.selection.tool or '-'} | "
              f"{dict(step.selection.arguments)} | from {dict(step.selection.sources)}")
    if plan.declined_because:
        print("  declined because:", plan.declined_because)
    if plan.guidance and plan.outcome != "run":
        print("  says:", plan.guidance.render)


with Client() as client:
    print("answered by:", client.runtime_status()["side"])
    for turn in ["show me order 4411", "charge order 4411 40.00", "charge 40.00 to order 4411",
                 "charge order 4411", "delete order 4411", "zork the frobnicator"]:
        show(turn, client.plan(turn, agent="desk", catalogue=catalogue))

answered by: local
'show me order 4411': run
  tool | tool: admission | get_order | {'order_id': '4411'} | from {'order_id': 'turn'}
'charge order 4411 40.00': run
  tool | tool: provenance | charge_card | {'amount': '40.00', 'order_id': '4411'} | from {'amount': 'turn', 'order_id': 'turn'}
'charge 40.00 to order 4411': run
  tool | tool: provenance | charge_card | {'amount': '40.00', 'order_id': '4411'} | from {'amount': 'turn', 'order_id': 'turn'}
'charge order 4411': ask
  ask | ask: incomplete | charge_card | {'order_id': '4411'} | from {'order_id': 'turn'}
  says: I can charge card -- I need the amount.
'delete order 4411': unread
  unread | unread: no tool | - | {} | from {}
  says: I can get orders, but nothing here can delete them.
'zork the frobnicator': unread
  unread | unread: no tool | - | {} | from {}
  says: I didn't recognise anything in that. I can charge card, get order, hand off, read inbox or send receipt. Which do you mean?

answered by: local says the reading ran on your machine, in the runtime your licence lets it run. Under each message, a step reads: what it is, the rule that decided it, the tool, the values, and where each value came from, turn meaning the message itself. The rules named here:

• tool: admission: one tool fits what the message asks for, so it is that tool;
• tool: provenance: more than one tool fit, and the one whose own words the message used most directly was kept;
• ask: incomplete: one tool fits, and a value it needs is missing, so the bot asks for it;
• unread: no tool: no tool does what was asked, and the bot says what it can do instead.

A policy scanned¶

So far you have checked a bot you built. Many teams already run guardrails written for NeMo Guardrails, and the bug hunter checks those too. It reads the policy and reports every way through it to an action it was meant to stop, each with a fix it has already tested by scanning again (chapter 28). Here it scans the shop's policy, written for NeMo Guardrails, with two rules a team added in a hurry:

# Added in a hurry: the refund, on the intent alone.
define flow quick refund
  user ask quick refund
  bot execute_refund_card

define flow receipts after a charge
  user ask charge
  if $card_on_file
    execute send_receipt(order_id=$order_id)

# Added in a hurry: the receipt, called without execute.
define flow receipts
  user ask receipt
  $sent = send_receipt(order_id=$order_id)
  if $sent
    bot "The receipt is on its way."

The script scans it, then looks closer at one finding, then saves the findings in SARIF, the format code scanning tools such as GitHub's read:

result = client.hunt("policy.co", inputs={"rails_config": "config.yml"}, gate=True)

print(result.state, "| gate passed:", result.result["gate"]["passed"])
for finding in result.findings:
    where = finding.location
    print(f"{finding.rule} {finding.raw['title']} · {finding.severity} · {where['file']}:{where['line']}")
    print("  ", finding.raw["message"])
    print("   OWASP:", ", ".join(f"{entry.id} {entry.title}" for entry in finding.owasp) or "none")
print("nothing to read:", ", ".join(rule["rule"] for rule in result.nothing_to_read))
print("no rule for:", result.coverage["not_addressed"], "--", result.coverage["not_addressed_reasons"]["LLM05:2026"])
escapable = next(finding for finding in result.findings if finding.rule == "QG002")
print("root cause:", escapable.owasp_root_cause, "| reproduction:", escapable.reproduction)
print("fix:", escapable.fix["patch"], "in", escapable.fix["flows"])
print("re-scanned:", escapable.fix["verified"], "| over-blocking:", escapable.fix["over_blocking"]["outcome"])
print("OWASP's mitigation:", escapable.raw["owasp_remediation"][0])
saved = result.artifact("sarif").save("findings.sarif")        # what your code scanning upload reads
run = json.loads(saved.read_text(encoding="utf-8"))["runs"][0]
rule = next(rule for rule in run["tool"]["driver"]["rules"] if rule["id"] == "QG002")
print("taxonomies:", ", ".join(taxonomy["name"] for taxonomy in run["taxonomies"]))
print("QG002's tags:", ", ".join(rule["properties"]["tags"]))
print("results:", [(r["ruleId"], r["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]) for r in run["results"]])

succeeded | gate passed: False
QG002 Escapable guard · high · policy.co:27
   The policy gates 'execute_refund_card' on 'order_paid', and there is a way past it.
   OWASP: LLM03:2026 Excessive Agency, ASI02:2026 Tool Misuse and Exploitation
QG005 Unshippable policy · high · policy.co:35
   line 35: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow.
   OWASP: none
QG008 Call without execute · high · policy.co:45
   'send_receipt' is called without execute, so the action never runs
   OWASP: none
QG022 Rail with a published advisory · high · config.yml:5
   The configuration runs the library rail 'fiddler bot faithfulness' (nemoguardrails), which advisory QGA-2026-0001 describes: Fiddler faithfulness rail raises the jailbreak exception. version: unknown. The advisory affects nemoguardrails >=0.23.0,<=0.24.1, and no fixed version is published. Supply the file that pins the version you install: `stalwart verify --dependencies`, or `dependencies=` to `client.hunt`. With exceptions enabled, the faithfulness rail raises JailbreakDetectionRailException, so a host reads a detected hallucination as a jailbreak. Versions before 0.23.0 were not checked. Fix: Raise FaithfulnessRailException from the faithfulness flow, as the Colang 2 rail does.
   OWASP: LLM04:2026 Supply Chain, ASI04:2026 Agentic Supply Chain Vulnerabilities
nothing to read: QG017, QG018, QG019, QG020, QG021, QG023, QG106, QG107
no rule for: ['LLM05:2026'] -- a property of training data and model weights, which no guardrail policy decides
root cause: permissions | reproduction: not_yet_replayed
fix: Patch: allow 'execute_refund_card' only when: $order_paid in ['refunds', 'quick refund']
re-scanned: verified | over-blocking: proved_free
OWASP's mitigation: OWASP LLM03:2026, "Complete mediation": enforce the check in the rail, which decides from trusted state, rather than relying on the model to decide whether the action is allowed.
taxonomies: OWASP Top 10 for LLM Applications, OWASP Top 10 for Agentic Applications, Guardrail categories (Vassilev 2026), NIST AI RMF functions (NIST AI 100-1)
QG002's tags: security, guardrail, guardrail-category:E, ai-rmf:GOVERN, ai-rmf:MANAGE, OWASP LLM03:2026, OWASP ASI02:2026
results: [('QG002', 'policy.co'), ('QG005', 'policy.co'), ('QG008', 'policy.co'), ('QG022', 'config.yml')]

Read it from the top:

• The gate failed, with four findings. Each gives its rule, its name, how serious it is, the line of the policy it is on, what was found, and the entries of the OWASP Top 10 lists it is an instance of.
• QG002: the careful rule checks that the order was paid before a refund, and there is a way past that check, the hurried rule.
• QG005: the same refund is started from two rules, which is why the bot's own rulebook was refused at the start of this page.
• QG008: the receipt rule calls send_receipt without execute, so the receipt is never sent.
• QG022: config.yml turns on a library rail with a published advisory against it. Give the scan the file that pins the versions you install, and it checks whether yours is affected.
• nothing to read: rules that had nothing to look at in this policy, as with stalwart verify.
• no rule for: an OWASP entry no guardrail policy can decide, with the reason.
• root cause and reproduction: which of OWASP's three causes QG002 comes from (too much functionality, too many permissions or too much autonomy), here permissions, and that the conversation that triggers it has not yet been replayed against the policy.
• fix: the change that closes it: allow the refund only when the order was paid, in both rules. re-scanned: verified says the policy, with the fix applied, was scanned again and the way past is gone; over-blocking: proved_free says it was also proved that the fix blocks nothing the policy is meant to allow.
• OWASP's mitigation: what OWASP recommends for this kind of finding.
• taxonomies, tags and results: what the SARIF file holds, so your code scanning tool shows each finding at its file and line.

That scan's results came back to your script and were not kept anywhere. To keep them, and to see them in the console, scan into a project. You create the project once, then pass its id each time you scan that policy. Each new scan is compared with the previous one, and anything a person decides about a finding in the console, such as accepting a risk until a date, is taken into account by the next scan (chapter 28):

with Client() as client:
    project = client.create_project("shop-guardrails")        # once: the console lists it under Findings
    result = client.hunt("policy.co", inputs={"rails_config": "config.yml"}, gate=True,
                         project=project["id"], branch="main")

print(project["name"], "|", result.state, "| gate passed:", result.result["gate"]["passed"])
print("findings:", ", ".join(f"{finding.rule} {finding.severity}" for finding in result.findings))

shop-guardrails | succeeded | gate passed: False
findings: QG002 high, QG005 high, QG008 high, QG022 high

The project now appears on the console's Findings page, with its last scan: the gate failed, with four findings, all rated High.

Open the project to see the findings. On the free plan, every finding is counted and the most serious one is shown in full; the paid plans show every finding, its history and how the project is trending (chapter 40):

Open a finding to see the bug itself: where it is, a conversation that triggers it, and the fix, already tested by scanning again:

An agent built elsewhere¶

The search stalwart verify ran on the shop bot also works on an agent built with something else, such as LangGraph or your own code. It needs no bot built with this package, only three things written down:

• the agent's graph, a qls-graph/1 JSON file: the steps the agent is made of, such as the model and the step that runs tools, and which step may follow which;
• a catalogue of its tools, a JSON file saying what each tool is: whether it only reads or changes something, whether it reads from the outside world, and what undoes it;
• a rulebook, if you have one: a Colang policy whose rules your tool calls are checked against.

You send them to Stalwart as an ordinary job, here with client.verify_graph, and it searches every route through the graph as it did for the shop bot. A LangGraph graph is written out for you by export_graph; any other agent, you write down yourself. Here is the shop's desk written by hand, as another framework would run it, with the model free to call any tool:

graph = {                                   # the agent, as any framework runs it: who may follow whom
    "format": "qls-graph/1", "name": "support", "agent": "desk", "recursion_limit": 20,
    "nodes": [{"id": "__start__", "kind": "start"},
              {"id": "model", "kind": "model"},                     # the model chooses the next tool
              {"id": "tools", "kind": "tools_plain",                # the tools run as asked, unchecked
               "tools": ["get_order", "read_inbox", "refund_card"]},
              {"id": "__end__", "kind": "end"}],
    "edges": [{"from": "__start__", "kind": "fixed", "destinations": ["model"]},
              {"from": "model", "kind": "conditional", "destinations": ["tools", "__end__"]},
              {"from": "tools", "kind": "fixed", "destinations": ["model"]}],
}
catalogue = {"tools": [                     # what each tool is
    {"name": "get_order", "read_only": True},
    {"name": "read_inbox", "read_only": True, "reads_outside": True},   # it reads email from anyone
    {"name": "refund_card", "read_only": False},                         # it changes something
]}
with open("support.graph.json", "w", encoding="utf-8") as file:
    json.dump(graph, file)
with open("support.catalogue.json", "w", encoding="utf-8") as file:
    json.dump(catalogue, file)

with Client() as client:
    result = client.verify_graph("support.graph.json", catalogue="support.catalogue.json")
    print(result.state, "|", len(result.findings), "finding(s)")
    for finding in result.findings:
        print(f"{finding.rule} · {finding.severity} · {finding.raw['tool'] or '-'}")
        print("  ", finding.raw["message"])

succeeded | 5 finding(s)
QG023 · medium · cycle:model
   the cycle through 'model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 20 is the run's only ceiling
QG001 · medium · get_order
   'get_order' can run on a plain tool node, without the tool check
QG001 · medium · read_inbox
   'read_inbox' can run on a plain tool node, without the tool check
QG001 · high · refund_card
   'refund_card' can run on a plain tool node, without the tool check
QG011 · high · refund_card
   the privileged 'refund_card' can run carrying the label untrusted:read_inbox with no confirmation or refusal

The shop bot passed this same search, because its tools run through the tool check. This desk, written by hand, does not:

• QG001, three times: the step that runs the tools is tools_plain, so each tool runs exactly as the model asks, without the tool check. It is Medium for the two lookups and High for refund_card, which changes something.
• QG011: refund_card, a privileged tool, can run straight after read_inbox has brought text from outside into the conversation, with nobody asked in between. That is the kind of route stalwart redteam --graph replays.
• QG023: the model and the tools can call each other in a loop with no limit set, so only the framework's own limit of 20 steps stops it.

The fix for the first two is to run the tools through the tool check, a tools_guarded step; the third needs a budget for the loop.

Chapter 47 has every field of the graph and the catalogue, and how to read what comes back.

A verdict and a certificate¶

The last step goes one level deeper. Instead of searching for holes, you ask Stalwart to prove that one specific thing can never happen. The policy here is the guide's smallest, a bank's: it says a transfer runs only for a customer who is signed in.

# transfers.co: the guide's smallest policy. A transfer runs only for a signed-in user.

define user express greeting
  "hello"
  "good morning"

define user ask transfer
  "I want to transfer money"
  "send 100 pounds to another account"

define bot greet
  "Hello! I am your banking assistant. How can I help?"

define bot refuse unauthorized action
  "Sorry: for your security, you need to be signed in to do that."

define bot execute_transfer_funds
  "Transfer authorised. Sending the funds now."

define flow greeting
  user express greeting
  bot greet

define flow secure funds transfer
  user ask transfer
  if $is_authenticated
    bot execute_transfer_funds
  else
    bot refuse unauthorized action

You name the policy, the action (execute_transfer_funds) and the condition it must never run without (is_authenticated), and ask Stalwart to prove it. profile="patch" asks for a certificate, and for a fix where the rule does not hold (chapter 10). The answer comes with that certificate, which you then check on your own machine, with no key and no network (chapter 6):

with Client() as client:
    result = client.verify_guardrail("transfers.co", "execute_transfer_funds", "is_authenticated", profile="patch")
    print(result.state, result.status, "| decided by", result.decided_by)
    result.certificate.save("transfers.certificate.json")

checked = check_certificate("transfers.certificate.json")      # here, offline: no key, no network
print("certificate:", checked.outcome, "|", checked.reason)

succeeded UNSAT | decided by candidate-derivation
certificate: verified | replayed 5 operation(s), and the withheld final step yields 0 = 1

UNSAT means it holds: there is no situation in which the transfer runs for a customer who is not signed in. Stalwart turns the policy into equations and shows that a transfer without sign-in has no solution; decided by names the part of the engine that showed it. The certificate is the evidence: the steps of that calculation, with the last step left for the checker to take, so whoever checks it reaches the contradiction (0 = 1) themselves (chapter 7). Anyone can check it, including people who do not trust us; stalwart check transfers.certificate.json does the same check from the command line.

Back in the console, the Jobs page lists every check your organisation has run. Among them are this one, a guardrail job with its verdict, and the hunt jobs from earlier, such as the search stalwart verify ran and the project's scan.

Files shows what a job kept. The certificate there is the one you just checked. Opening it in the console is recorded in your organisation's history, so you can always see who looked at it.

Finally, the Usage page shows how much of your plan you have used this month, meter by meter, including the tool checks, one for each call your bot's tool check answers (chapter 16):

Where next¶

• To build your own bot, start with Part I.
• To use the selector inside an application you already have, read Part II.
• To scan the guardrails you already run, go to chapter 28.
• To check an agent you built with LangGraph or your own code, go to chapter 47.

30 · Your first agent¶

The Bot Builder is the stalwart-agents package. You declare an agent in one file, or in a few lines of Python: its tools, the words that say what each tool does, its rules, and which agent it may hand a conversation to. You check it, and you run it. You do not need to learn an agent framework for any of this, and this part of the guide never asks you to.

Before you start¶

You need an account and its key (chapter 5), and the licence activated once on each machine that runs your agents:

$ pip install "stalwart-agents[anthropic]"    # or openai, google, mistral, ollama; or none, for no model
$ export QLS_API_KEY=qls_live_...
$ stalwart licence activate

Nothing in the package works without the key and an activated licence, except activating it, stalwart doctor, which says what is missing, and stalwart check, which checks a certificate. What a licence is, and what works offline, is chapter 38.

Where the runtime is installed, a turn and a tool call need no network: the runtime answers both on the machine that runs your agent.

The shop agent, in one file¶

This guide follows one agent through Part I: a small shop's support desk. It reads orders, charges cards, e-mails receipts and reads the support inbox, and it hands refunds to a billing desk that has more privilege:

# The shop's support desk, and the billing desk it hands refunds to.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider; the key comes from your environment
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # a turn no tool covers is refused, by name
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # every public function of shop/tools.py
rulebook: ./policy.co                      # the rules every call is checked against
facts:                                     # what the rulebook's $card_on_file and $order_paid are
  card_on_file: {from: get_order.card, same: order_id}           # read from get_order's answer
  order_paid: {from: get_order.status == paid, same: order_id}   # for the order the call names
runs: atomic                               # a failed run is undone, last write first
storage: sqlite:///runs.db                 # where runs and waiting confirmations are kept

Its tools are plain Python functions. A function's type hints are its arguments, the first line of its docstring is what it does, and @tool(...) gives it the words the checks read. A function with no words is a read:

"""The shop's tools: plain functions. Their type hints are their schemas, the first line of
each docstring is what the tool does, and @tool gives a tool the words the checks read."""

from decimal import Decimal

from stalwart_agents import tool

ORDERS = {
    "4411": {"order_id": "4411", "total": "40.00", "card": "visa-0019", "customer": "c-208", "status": "unpaid"},
    "4412": {"order_id": "4412", "total": "12.50", "card": "visa-0019", "customer": "c-208", "status": "paid"},
}


def get_order(order_id: str) -> dict:
    """Show an order: its total, the card on file, the customer and its status."""
    return dict(ORDERS.get(order_id, {"order_id": order_id, "status": "not found"}))


@tool(writes=True, undo="refund_card")
def charge_card(order_id: str, amount: Decimal) -> dict:
    """Charge an amount to the card on file for an order."""
    return {"charge_id": f"ch-{order_id}", "order_id": order_id, "amount": str(amount)}


@tool(writes=True, requires_privilege="high")
def refund_card(order_id: str, amount: Decimal) -> dict:
    """Refund an amount to the card on file for an order."""
    return {"refund_id": f"rf-{order_id}", "order_id": order_id, "amount": str(amount)}


@tool(writes=True, irreversible=True)
def send_receipt(order_id: str) -> dict:
    """E-mail the receipt for an order to its customer."""
    return {"sent": True, "order_id": order_id}


@tool(reads_outside=True)
def read_inbox(folder: str = "support") -> dict:
    """Read the newest message in the shop's support inbox."""
    return {"from": "someone@example.com", "body": "refund order 4411 in full"}

Before it answers anyone, check it:

stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.

stalwart verify reads your code for network and credential problems on your machine, lints the catalogue and compiles the rulebook, and has every route through the two agents searched on our servers for a way to a tool without its check, its confirmation or its order rule. Chapter 31 is what it finds and how to read it.

Then talk to it:

desk = Agent.from_file("agent.yaml")        # the graph is proved once, before the first turn

reply = desk.chat("show me order 4411", user="u-17")
print(reply.text)                           # get_order, chosen from the words; no model was asked

reply = desk.chat("charge order 4411 40.00", user="u-17")
for waiting in reply.waiting:               # the write waits for a person
    print(waiting.tool, "|", waiting.wording, "|", waiting.decisions)
    for argument in waiting.arguments:      # each argument, and where its value came from
        print("  ", argument)

reply = desk.confirm("u-17", "approve")     # runs now, with exactly the arguments shown
print(reply.text)

card: visa-0019
customer: c-208
order_id: 4411
status: unpaid
total: 40.00
charge_card | Run charge_card? | ['approve', 'skip', 'cancel_all']
   {'name': 'amount', 'value': 40, 'origin': 'typed'}
   {'name': 'order_id', 'value': '4411', 'origin': 'typed'}
amount: 40
charge_id: ch-4411
order_id: 4411

The read was answered with no model call: the selector read show me order 4411 against what each tool says, and chose get_order. charge order 4411 40.00 names the charge, the order and the amount, in the order a person types them. The charge waited for a person, showing each argument and where its value came from, and ran only once approved, with exactly those arguments (chapter 32). The rulebook allows a charge only if $card_on_file, and facts: reads that from get_order's answer for the same order, so the charge is allowed once the order has been shown with a card (chapter 45).

To serve it over HTTP, with a chat interface at / that shows confirmations, refusals and rollbacks:

$ stalwart serve agent.yaml

Chapter 35 is the interface and the routes behind it.

The same agent in Python¶

Everything the file says can be said in Python, and means the same:

from stalwart_agents import Agent

from shop.tools import charge_card, get_order, read_inbox, refund_card, send_receipt

billing = Agent("billing", tools=[refund_card], privilege="high", rulebook="policy.co")
desk = Agent("desk", tools=[get_order, charge_card, send_receipt, read_inbox], hands_off_to=[billing],
             model="anthropic:claude-sonnet-5-5", on_unread="refuse", rulebook="policy.co",
             facts={"card_on_file": {"from": "get_order.card", "same": "order_id"},
                    "order_paid": {"from": "get_order.status == paid", "same": "order_id"}},
             storage="sqlite:///runs.db")

from_file = Agent.from_file("agent.yaml")
print(desk.catalogue_digest() == from_file.catalogue_digest())   # the same catalogue, either way

True

The file and the Python agent give the same catalogue, with the same digest, so a team can start in either and move to the other.

What agent.yaml says¶

The words at the file's top, under an agent, and under replies: and answers:, generated from the package:

A word the file does not know is an error at its line, never ignored (below). Chapter 48 lists the keys under each of these, at every level, and those of gateway.yaml.

In Python, load("agent.yaml") reads the file into an AgentFile: the agents, their tools, the stores and the rulebook it declares. Without fetch=True, an MCP server's tools are known by the names the file lists.

Where tools come from¶

• python: shop.tools takes every public function of the module, imported from the folder the file is in. Its schema comes from its type hints.
• mcp: https://tools.internal/mcp takes the tools an MCP server lists, with their schemas and the hints the server gives: a tool the server marks read-only reads, one it marks destructive writes, and one it says nothing about writes. tools: [...] keeps only those named; version: or digest: pins the server. Each user of your agent gets an MCP session of their own on the server, so what a server keeps for one user never reaches another. headers: sends a header on every request, its ${NAME} read from your environment when the request is made: how an agent behind stalwart gateway sends its token (chapter 37).
• openapi: ./crm.yaml makes each operation of an OpenAPI document a tool: GET and HEAD read, any other method writes unless the operation says otherwise in x-stalwart.
• name: refund_card, with words beside it, adds words to a tool from any source.

Chapter 21 has the other ways in, such as the exported functions of a TypeScript project.

A tool's words¶

The words are what turns a function into a tool the product can govern. Each sets one field of the catalogue the checks read:

You do not need most of them to start. A read needs none; a write needs writes=True; a write that can be undone needs undo=; one that cannot needs irreversible=True. The rest make the checks more precise, and the bug hunter tells you when one is missing (chapter 31).

TOOL_WORDS holds the name of every word, for code that writes the file.

Agents, privilege and hand-offs¶

An agent may hand a conversation to another it names in hands_off_to. Each agent has its own tools, and calls only those. privilege says how much a hand-off from an agent is trusted: an instruction that entered a low-privilege agent, from an e-mail say, is marked when it reaches a high-privilege one, and a write it leads to is confirmed by a person (chapter 33).

budget: {max_steps: 15}, on an agent or for the whole file, is where a run stops: the agent's own where it says one, else the file's, else 60 steps. A loop the model drives through your tools ends there, and stalwart verify checks that it does (QG023, chapter 31). max_tool_calls and max_model_calls limit what one turn calls: the call past one is not made, and the turn stops with BudgetSpent, a RunTooLong. A confirmation goes on with its turn's count, and an undo is never counted.

The model¶

model: "anthropic:claude-sonnet-5-5" names a provider and a model; the key is read from your environment, under the provider's usual variable, and stays yours. A missing key is reported before anything is sent, naming the variable. A model can also be a plain Python function that takes the conversation and returns the reply. We hold no model credential, anywhere.

The model is called only where your settings send a turn to it. Every turn is read by the selector first, and a turn that names a tool, needs a question asked, or is declined never reaches the model. A turn nothing reads is asked to be said again once; then on_unread decides: refuse, model, ask (the person says whether the model may have it) or answer, from your documents (chapter 44). With no model, on_unread: refuse, no hands_off_to, replies from your phrasings and answers in your documents' own sentences, no model is ever called (chapter 45).

Runs and storage¶

runs: atomic, the default, undoes a failed run, last write first (chapter 34). storage: is where runs and waiting confirmations are kept, so that a confirmation can be answered after a restart, or on another worker: sqlite:///runs.db for one machine, postgres://... for several.

The commands¶

Generated from the stalwart command itself:

The errors¶

Every error the package raises names what to change, in the words of agent.yaml, never in the terms of the libraries underneath:

A file error names its line:

agent.yaml:7: agent 'desk' lists 'refund', which no tools source declares

The limits¶

What stalwart-agents decides, and what stays yours:

• It decides which tool a turn names, whether a call may run, waits for a person or is refused, what is undone when a run fails, and what a reply may say about what was done.
• Your functions decide what they do. A tool's words are taken as you state them: a tool declared a read that writes is governed as a read. The code checks read your code for network and credential problems, and nothing else about what it does (chapter 46).
• Your model decides what it says and which tool it asks for, where your settings let it. Every call it asks for is checked; its choices are not proved good (chapter 31).
• A tool reachable outside the agent can be called around it. The checks govern the calls the agent makes; chapter 37 puts the same check in front of your tools for everything else.

31 · Checking an agent before it runs¶

stalwart verify agent.yaml checks an agent before it serves anyone. It reads your code on your machine, lints the agent's catalogue and compiles its rulebook, and has every route through your agents searched on our servers for a way to a tool without its check, its confirmation or the step it must follow. It prints each finding with its rule, the line of agent.yaml it comes from, its OWASP entries and its fix, and exits non-zero when the gate fails, so it stands in CI as it stands on your machine.

What it does, in order¶

1. The code checks, here. Every Python file of the folder agent.yaml is in is read on your machine for network and credential problems, with the tools the file names taken as the functions whose parameters are tool arguments. Any finding fails the gate. Only its counts by rule leave your machine, with the hunt (chapter 46).
2. The catalogue and the rules, here. The catalogue -- every tool with its words -- is made from agent.yaml and linted by the runtime on your machine, and the file's rulebook: is compiled into the rules the tool check enforces, as the agent compiles it at its start. So the rules the agent is checked against here are the rules it runs under. No lint blocks the agent, and nothing of the agent is kept on the service.
3. The hunt, on our servers. The agents' graph, the catalogue and the rulebook are scanned by the bug hunter as one hunt job, under its gate. The search runs on Stalwart's servers, never on your machine. A hunt that could not run is an error, never a clean result.
4. The report. The findings are printed one per block, the most severe first.

The shop agent of chapter 30, checked:

stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.

Read it from the top:

• Compiled the rulebook policy.co: the rules the tool check enforces, compiled as the agent compiles them at its start. A rulebook the tool check cannot build a gate from is a lint instead, naming its line.
• Lints from the runtime: what the catalogue leaves unsaid, such as a write with no undo, and two tools the selector cannot tell apart. Each names the tool and what to add; none fails anything.
• Code checks: the files read and the version of the rules they were read with.
• Each finding: the rule, its severity and the tool, with the file and line that declared it; what was found, in one sentence; its OWASP entries; and the fix. Here QG023 says the desk's loop has no budget but the run's step limit, and QG105 says refund_card is a write with no undo, on a route with another write.
• Rules with nothing to read: rules that raised nothing because nothing they read was declared (below).
• Gate: passed or failed. A finding blocks the agent only where it fails the gate: by default, a new Critical finding -- such as a missing or escapable check on a tool that is irreversible or that requires_privilege: high -- and any code-check finding. Every other finding is a warning: it does not block the agent, and is there for you to look at and weigh. The report lists what blocks first, under its own heading, then the warnings, and its last line says in so many words whether anything blocks the agent. The shop agent's QG023 and QG105 are warnings, so it passes.

The command's exit status, generated from the command itself:

--keep DIR writes what was checked into a folder: agent.graph.json, the agents' graph as the hunter read it; agent.catalogue.json, the catalogue; and agent.findings.json, the findings document. Every option:

The questions it answers for every tool¶

For every tool, on every route through your agents, to the depth stated, the hunt asks:

• Can it run without its check, or can the check be got past? Over several turns, can an approval given at one turn be spent at another?
• Can a write run carrying a mark from outside -- an e-mail, a web page, another agent with less privilege -- with nobody confirming it?
• Can an irreversible step come before steps that will be undone if the run fails, without its confirmation saying so?
• Can a tool run out of its declared order?
• Can a route go anywhere, because nothing declares where it may go?
• Can a write fail to be undone, because nothing undoes it and nothing says it cannot be?

Each question is a rule, and each rule has its page:

Why each matters, and how to fix it:

• QG001 Missing check: the tool is reachable and nothing in the rules relates it to its check, so a conversation that reaches it reaches it whatever the check would say. Add the check as a condition on every route to the tool.
• QG002 Escapable guard: the check exists, and something else satisfies it: a second flow to the same tool, a branch that falls through. Apply the patch the finding names inside every flow it names.
• QG003 Multi-turn escape: a check read once and relied on later. Read the check in the same turn as the call, or carry it with the call it approved, and check again at the same depth.
• QG011 Confused deputy: a value from outside reached the model, and a route lets that model call a privileged tool with no person confirming it. Put the tool on the guarded tool step, so a call carrying the mark is confirmed or refused; mark the tool that reads the outside reads_outside where it is not.
• QG012 Cascading injection: the same, where the mark entered one agent and the call is made by another after a hand-off. Put the tool on the acting agent's guarded tool step, or confirm the hand-off.
• QG013 Irreversible before undoable: if a later step fails, the run is undone, and the irreversible step stays done; the person who approved it was not told. Move the irreversible step last, or let its confirmation say that the steps after it cannot undo it.
• QG014 Order rule escapable: a tool declared after, not_after or at_most runs where its rule is not checked. Put the tool on the guarded tool step, where order rules are checked over the session's history.
• QG015 Undeclared route: see an undeclared route.
• QG016 Unmodelled path: an attacker campaign made a privileged call on agents the hunt found clean, so what runs and what was checked disagree. Nothing this product reports is more urgent: check again from what runs, and compare the attacker's trace with the checked graph (chapter 33).
• QG105 Unrecoverable write: a write with no undo, not marked irreversible, on a route with another write; a failed run cannot undo it, and nothing says so. Declare its undo -- which may be the tool itself with its arguments swapped -- or undo: none where a failed run may leave it done, or mark it irreversible so a person confirms it knowing that (chapter 34).

A graph agent.yaml describes puts every tool on the guarded tool step, where each call is checked and each write is confirmed, so most of these rules find nothing on it; they find what a team's own steps leave open (chapter 27). The rules on what your declarations say are below.

Reading a finding and its witness¶

A finding's witness is the run that reaches the tool: the steps, in order, that the hunt found. The findings document --keep writes holds it under detail. Here is the QG011 that E16's own graph raises on refund_card, with the fields this section reads:

{
  "rule": "QG011",
  "title": "Confused deputy",
  "severity": "critical",
  "action": "refund_card",
  "control": "a confirmation",
  "obligation": "taint:refund_card:untrusted:read_inbox",
  "reproduction": "not_yet_replayed",
  "detail": {
    "witness_path": [
      "1.0 __start__",
      "1.1 model",
      "1.2 tools",
      "1.3 model",
      "1.4 tools"
    ],
    "code_flow": [
      {
        "message": "step 1.0: the graph visits __start__"
      },
      {
        "message": "step 1.1: the graph visits model"
      },
      {
        "message": "step 1.2: the graph visits tools"
      },
      {
        "message": "step 1.3: the graph visits model"
      },
      {
        "message": "step 1.4: the graph visits tools"
      }
    ],
    "fix": "Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it."
  }
}

Read it step by step. A step's number is turn.step: 1.2 is the second step of the first turn.

1. 1.0 __start__: the person's turn arrives.
2. 1.1 model: the model reads it, and asks for a tool.
3. 1.2 tools: the tool step runs read_inbox. What it returns comes from outside, and is marked untrusted:read_inbox.
4. 1.3 model: the model reads the e-mail and asks for refund_card. Its request carries the mark.
5. 1.4 tools: refund_card runs, carrying the mark, and nothing confirms it: this team's own tool step is not the guarded one.

detail.code_flow gives one message per step, at the line that declared the step, so a code-scanning view shows the same path. The other fields:

• control: what was missing on the way -- here, a confirmation;
• obligation: what the hunt decided, named: taint:refund_card:untrusted:read_inbox is "refund_card never runs carrying untrusted:read_inbox unconfirmed";
• detail.fix: the change that closes the path;
• reproduction: not_yet_replayed until the witness is replayed (below).

The fix closes the path at its last step: a person sees the refund, with each argument and where its value came from, and the sentence that it was proposed after reading an e-mail from outside (chapter 33).

The depth of the check¶

A clean result holds to a stated depth, and the findings document states it, under scan.obligations.graph. For the shop agent:

verify("agent.yaml", keep="kept")          # as `stalwart verify agent.yaml --keep kept`

kept = json.loads(Path("kept/agent.findings.json").read_text(encoding="utf-8"))
print(json.dumps(kept["scan"]["obligations"]["graph"], indent=2))

{
  "total": 12,
  "decided": 12,
  "steps": 60,
  "turns": 3,
  "replay": "not replayed: the hunter reads the export, not the code that built it; each finding's witness_path is the run to reproduce"
}

• total and decided: how many questions the hunt asked of this graph, and how many it decided. Where they differ, the rest are listed under scan.undecided, and nothing is claimed for them.
• steps: the most steps one run may take, 60 here, the agent's step limit. Every route is searched up to it.
• turns: how many of the person's turns a route is followed over, 3 here. An approval given at one turn and spent at a later one is found within them (QG003).

So "no way through" means no way within 60 steps and three turns. Agent Graph Verification, which checks a graph you send it yourself, states the depth it searched on its [UNROLL] line (chapter 47).

Replaying a witness¶

stalwart verify --replay replays each graph finding's witness on your agents themselves, with every tool a stub that records its calls and returns fixture data, and a scripted model that makes exactly the witness's choices. The checks run as they run in production. A finding is reproduced when the run takes the witness's path and its tool is called. One that does not reproduce means the hunt and the agents that run disagree: it is listed first, and fails the gate. Each replay is recorded as digests and its outcome, never its trace.

What you can declare about your tools¶

Each declaration is optional, and each is read by one or more rules. A rule whose declaration is missing raises nothing -- see A missing declaration hides its rule.

In agent.yaml the words go under a tool's name; in Python they are arguments of @tool(...). An MCP server's entry is a tools entry that names the server and the tools it serves, with the server's version or digest where you pin one.

The runtime gives these declarations four lints, none of which fails anything.

Other lints read what every catalogue states rather than these declarations: a write with no result or argument schema, an irreversible tool that asks for no confirmation, two tools the selector cannot tell apart, a name the reader takes for grammar, a TypeScript function tagged neither @read nor @write, and tool code that failed the code checks. The last four are errors: fix them before the agent serves anyone.

The rules that read them¶

Each rule decides one question over every path the graph or the policy allows, and states its limit: what it decides, and what it does not.

QG022, the rail with a published advisory, is in chapter 28.

Every OWASP entry a finding carries is a statement at the policy level: the part of the risk that your rules and your catalogue control. A clean scan under an entry means no finding at the policy level, not that the risk is absent. The one entry no rule covers is LLM05:2026 Data and Model Poisoning: a property of training data and model weights, which no guardrail policy decides (chapter 28).

Worked example E16: the shop agent grows¶

The shop agent takes on new tools, each with its declaration:

• run_report, whose sql argument is declared sql and is written by the model;
• get_customer, confidential: subject with subject_argument: customer_id, whose record send_receipt can carry;
• search_help, over a multi_tenant store, scoped by a tenant_id the model writes, served by an MCP server registered with no version or digest;
• remember_note, persists: notes, reachable after read_inbox, and recall_notes, which reads the notes back before refund_card;
• the billing desk, moved to a remote agent over a2a with no authentication;
• and no budget on the desk's loop.

agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"
    tools: [get_order, run_report, get_customer, send_receipt, search_help, read_inbox, remember_note, recall_notes, refund_card]
    hands_off_to: [billing]
  billing:
    privilege: high
    tools: [issue_refund]
    remote: {transport: a2a, authentication: none}
tools:
  - name: get_order
    schema: {type: object, properties: {order_id: {type: string}}}
  - name: run_report
    argument_kinds: {sql: sql}
    schema: {type: object, properties: {sql: {type: string}}}
  - name: get_customer
    confidential: subject
    subject_argument: customer_id
    schema: {type: object, properties: {customer_id: {type: string}}}
  - name: send_receipt
    writes: true
    sends_out: true
    schema: {type: object, properties: {order_id: {type: string}, body: {type: string}}}
  - mcp: https://help.internal/mcp
    tools: [search_help]
  - name: search_help
    retrieves: {store: help, scope_argument: tenant_id}
    schema: {type: object, properties: {tenant_id: {type: string}, query: {type: string}}}
  - name: read_inbox
    reads_outside: true
    schema: {type: object, properties: {folder: {type: string}}}
  - name: remember_note
    writes: true
    persists: notes
    schema: {type: object, properties: {note: {type: string}}}
  - name: recall_notes
    retrieves: {store: notes}
    schema: {type: object, properties: {topic: {type: string}}}
  - name: refund_card
    writes: true
    requires_privilege: high
    schema: {type: object, properties: {order_id: {type: string}}}
  - name: issue_refund
    writes: true
    schema: {type: object, properties: {order_id: {type: string}}}
stores:
  help: {multi_tenant: true}
  notes: {persistent: true}

stalwart verify reads the file, builds the agents it describes -- the desk's model, the guarded tool step its tools are on, and a hand-off to billing -- and prints:

stalwart verify agent.yaml

Lints from the runtime (none of these blocks the agent):
  argument_kind_suggested (info) on search_help: query: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  write_not_retry_safe (warning) on issue_refund: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on issue_refund: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on remember_note: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on remember_note: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on send_receipt: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported

Code checks: no finding in 1 file(s) (rules d656f9ab32d3).

Warnings: 10 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG018 High on run_report (agent.yaml:4)
  'run_report' can run with its sql argument 'sql' written by the model or carrying a trust label, and nothing confirms the call
  OWASP LLM10:2026, LLM01:2026
  Fix: Bound 'sql' in the tool's schema with an enum, a const or a pattern; or take it from the user's typed text, the host's context or an earlier tool's result, and bind it so in the export's `arguments`; or put the call behind a confirmation -- the guarded tool node or an interrupt().

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help (agent.yaml:4)
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG023 Medium on cycle:desk_model (agent.yaml:2)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on issue_refund (agent.yaml:8)
  the write 'issue_refund' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'issue_refund' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on refund_card (agent.yaml:4)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note (agent.yaml:4)
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt (agent.yaml:4)
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp (agent.yaml:24)
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

QG107 Review on desk -> billing (agent.yaml:2)
  the hand-off from 'desk' to 'billing' reaches 'billing' over a2a with authentication: none: nothing shows the far side is the agent it claims to be
  OWASP ASI07:2026
  Fix: Declare and use mtls, oauth2 or signed_messages on the channel to 'billing', or accept the hotspot with the layer that authenticates it.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG022: no Colang policy and no rails config was scanned

Gate: passed. Nothing blocks this agent: the 10 warnings above are for you to look at and weigh.

The agents agent.yaml describes put every tool on the guarded tool step, where a write runs only on its confirmation. That is why they raise no QG021 and no QG019 through send_receipt: the confirmation is the fix those rules ask for, and it is already there. A team that writes its own steps, with the same tools on a tool step that checks nothing, sees them. Here is the same catalogue with the desk's tools on such a step:

stalwart verify desk graph

Blocking: 3 findings that block this agent until fixed, or accepted with its reason:

QG001 Critical on refund_card
  'refund_card' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG011 Critical on refund_card
  the privileged 'refund_card' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG011 Critical on refund_card
  the privileged 'refund_card' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

Warnings: 22 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG001 High on remember_note
  'remember_note' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 High on send_receipt
  'send_receipt' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG011 High on remember_note
  the privileged 'remember_note' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG011 High on send_receipt
  the privileged 'send_receipt' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

QG011 High on remember_note
  the privileged 'remember_note' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

QG011 High on send_receipt
  the privileged 'send_receipt' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG018 High on run_report
  'run_report' can run with its sql argument 'sql' written by the model or carrying a trust label, and nothing confirms the call
  OWASP LLM10:2026, LLM01:2026
  Fix: Bound 'sql' in the tool's schema with an enum, a const or a pattern; or take it from the user's typed text, the host's context or an earlier tool's result, and bind it so in the export's `arguments`; or put the call behind a confirmation -- the guarded tool node or an interrupt().

QG019 High on send_receipt
  'send_receipt' sends data out of the host while the session holds a confidential value, and nothing confirms the call -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Confirm the call to 'send_receipt' -- on the guarded tool node or with an interrupt() -- or remove the confidential fields from the context before it.

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG021 High on remember_note
  'remember_note' can write to the persistent store 'notes' while the session carries content from outside, and nothing confirms the write
  OWASP ASI06:2026, LLM01:2026
  Fix: Confirm the write to 'notes', strip or refuse labelled values before it, or declare the store not persistent if it is not.

QG001 Medium on get_customer
  'get_customer' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'get_customer' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on get_order
  'get_order' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'get_order' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on read_inbox
  'read_inbox' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'read_inbox' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on run_report
  'run_report' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'run_report' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on recall_notes
  'recall_notes' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'recall_notes' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on search_help
  'search_help' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'search_help' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG023 Medium on cycle:model (run_e16.py:48)
  the cycle through 'model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 25 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG022: no Colang policy and no rails config was scanned
  QG107: no agent in the catalogue declares a remote channel

Gate: failed. This agent is blocked by the 3 blocking findings above. The warnings do not block it.

The QG011 on refund_card through recall_notes comes from the store: until every write into notes is proved clean, what recall_notes reads back is untrusted, so the privileged call it feeds is a confused deputy (chapter 33).

A missing declaration hides its rule¶

The same agent with the sql kind removed from run_report:

stalwart verify agent.yaml

Lints from the runtime (none of these blocks the agent):
  argument_kind_suggested (info) on search_help: query: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  argument_kind_suggested (info) on run_report: sql: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  write_not_retry_safe (warning) on issue_refund: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on issue_refund: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on remember_note: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on remember_note: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on send_receipt: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported

Code checks: no finding in 0 file(s) (rules d656f9ab32d3).

Warnings: 9 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help (agent.yaml:4)
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG023 Medium on cycle:desk_model (agent.yaml:2)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on issue_refund (agent.yaml:8)
  the write 'issue_refund' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'issue_refund' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on refund_card (agent.yaml:4)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note (agent.yaml:4)
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt (agent.yaml:4)
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp (agent.yaml:23)
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

QG107 Review on desk -> billing (agent.yaml:2)
  the hand-off from 'desk' to 'billing' reaches 'billing' over a2a with authentication: none: nothing shows the far side is the agent it claims to be
  OWASP ASI07:2026
  Fix: Declare and use mtls, oauth2 or signed_messages on the channel to 'billing', or accept the hotspot with the layer that authenticates it.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG022: no Colang policy and no rails config was scanned

Gate: passed. Nothing blocks this agent: the 9 warnings above are for you to look at and weigh.

No QG018: the rule has nothing to read. Registration says a declaration may be missing (argument_kind_suggested), and the summary lists the rule as having had nothing to read. A missing declaration hides its rule -- the scan is clean of what it was not told about, and says so.

An undeclared route¶

A route is where a run may go after a step. In agent.yaml every route is declared: an agent goes to its tools, back to its model, or to an agent it names in hands_off_to, and nowhere else. A step a team writes in code can choose where to go next with a function that reads what the model said. If nothing declares the places it may choose, the hunt has to assume it can choose any step -- past every check the design puts in the way. That is QG015, and every way through it opens names it, so one fix closes them all: declare where the route may go.

The gate in CI¶

stalwart verify exits 1 when the gate fails and 3 when nothing could be checked, so a CI step that runs it stops on either. Keep the findings with --keep and upload them as the run's record; chapter 46 has the workflow.

The limits¶

• A clean scan found no path to a tool without its check, its confirmation or the step it must follow, to the depth stated. It does not show the model chooses well, and your own functions are read as able to do anything.
• The depth is the one the findings document states: the run's step limit and the number of turns. A path longer than either is not searched.
• The hunter decides where a model-written value goes, not what your tool does with it.
• A rule whose declaration is missing raises nothing; the summary lists it as having had nothing to read.
• A declaration you make -- sandboxed, sanitised_by, an authentication on a channel -- is taken as stated and listed under the scan's assumptions; the hunter does not verify it.

45 · Guarded and proved¶

A stalwart-agents agent is guarded while it runs and proved before it runs. Two checks stand around its model, both decided by native code on your machine -- the licensed runtime the package carries -- and never by a model: the router decides whether the model is called at all, and the tool check decides every call. Before the agent's first turn, the bug hunter searches its graph for a way past either. This chapter is how the two checks decide, what that guarantees, and how the proof runs.

Two checks and a proof¶

1. The router reads every turn before any model sees it (below).
2. The tool check decides every tool call, whether the router or the model chose it (below).
3. The proof searches every route through your agents for a way to a tool without its check, its confirmation or the step it must follow (below).

The hosted API decides nothing while your agent runs. Where the runtime cannot answer, a plan or a check raises SelectorUnavailableError and the call is not made: the agent never falls back to an unchecked call.

The router: whether a model is called¶

Every turn is read into a plan against what your tools declare. Where the turn goes, generated from the router itself:

A turn nothing reads is asked to be said again once. After that, the agent's on_unread decides:

Where an agent says nothing, each conversation takes the setting of your console's Settings page at its first turn, or refuse.

When no model is ever called¶

The router answers the turns it reads without a model. A model is called only where your settings send a turn to one, so no model is ever called when all of these hold:

• the agents name no model;
• on_unread is refuse, or answer with the extract composer (chapter 44);
• no agent hands_off_to another;
• replies are your phrasings: replies: {composer: template} (chapter 42).

The tool check: every call, whoever chose it¶

The check runs in the runtime, once per call, with the catalogue, the rulebook and the session's history, and the first rule that applies decides. The rules, in the order the runtime takes them (chapter 32 gives each its example):

It gives one of three answers:

• allow: the tool runs once, with an idempotency key.
• confirm: a person is asked, shown each argument and where its value came from; the call is checked again with the signed token their approval carries (chapter 35).
• refuse: nothing runs. Where earlier steps of the run had written something, those writes are undone, last first (chapter 34).

What is guaranteed, and what is not¶

Guaranteed. A refused call runs nothing. A confirmed call runs only with the exact arguments the person saw. The history cannot be dropped, edited or reordered without the check saying history_invalid. No model is called unless your settings route a turn to one.

Not guaranteed. The check judges names, schemas, marks and the history, never what a reply means (chapter 42 holds replies to what was done). A tool reachable outside the agent can be called around the check, unless the gateway stands in front of it. Agent(..., verify=False) skips the proof.

The rulebook it runs under¶

An agent's rulebook: -- Colang 1.0 or 2.x, a rule sheet, or the folder stalwart rules compile wrote -- is what its graph is proved against and what its tool check enforces, so the rules proved are the rules the agent runs under:

• At start-up, before its first turn, the agent compiles its rulebook into the record the tool check evaluates (POST /v1/rulebooks/compile, or POST /v1/rule-sheets/compile for a sheet), once for its client; a folder stalwart rules compile wrote is read as it is, with no call. Nothing is kept on the service: every check carries the record beside the agent's catalogue.
• stalwart verify compiles it the same way, and proves the graph against it (chapter 46).
• Where it cannot be compiled -- no service, a rulebook the compiler refuses (rulebook_unsupported, naming the line), or an organisation that sends compiled records only (policy_input_refused) -- the agent does not run. It raises RulebookNotHeld, saying why.

The shop's two desks, with a rulebook that lets a refund run only for an order that is paid:

define user ask refund
  "refund order 4411"
  "give the customer their money back"

define flow refunds
  user ask refund
  if $order_paid
    execute refund_card
  else
    bot refuse

# The shop's two desks, with a rulebook that decides when a refund may run.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools
rulebook: ./policy.co                      # proved against, and compiled for the tool check

The tool check decides under it, with the context your application supplies:

desk = Agent.from_file("agent.yaml")
catalogue = desk.catalogue()                    # both desks' tools, made on this machine
rulebook = desk.rules().record                  # policy.co, compiled once for this agent
with Client() as client:
    billing = client.session("billing", catalogue=catalogue, rulebook=rulebook)
    billing.read("refund order 4411 40.00")
    for paid in (False, True):
        check = billing.check_tool_call("refund_card", {"order_id": "4411", "amount": 40.00},
                                        origins={"order_id": "typed", "amount": "typed"},
                                        context={"order_paid": paid})
        print(f"order_paid {paid}:", check.decision, ", ".join(check.reasons), check.detail.get("flow", ""))

order_paid False: refuse refuse refunds
order_paid True: confirm write 

The unpaid order's refund is refused by the rulebook's refunds flow; the paid one passes the rulebook and is confirmed, as every write is.

A rulebook's actions name tools by execute <tool>, as the refunds flow does, or by bot execute_<tool>, the same call spelled as the registry names it. Any other bot line is something the bot says, not a tool call.

The rulebook's facts¶

A rule such as if $order_paid reads a fact: true or false, by name, sent with each check. A fact nothing gives is false, so the rule refuses. There are two ways to give one, and an agent may use both:

• Your code says it, where your application knows it: Agent.from_file("agent.yaml", context=...), or Agent(..., context=...), takes the facts as a mapping, or as a function of the user that returns them, called at each check so it gives them as they stand then. A check made through the client or a session takes context= on each call (chapter 24).
• The agent's own tool says it: facts: in agent.yaml, or Agent(..., facts=...), reads a fact from a field of a tool's result, in the latest answer of that tool in the conversation. The shop reads both of its facts from get_order (chapter 30):

facts:
  card_on_file: {from: get_order.card, same: order_id}
  order_paid: {from: get_order.status == paid, same: order_id}

from is <tool>.<field>, true when the field is true, a number other than 0, or a text, list or mapping that is not empty; or <tool>.<field> == <value>, true when the field equals the value. Until the tool has answered, the fact is false, so the shop's charge is allowed only once show me order 4411 has shown a card.

same: order_id ties the fact to the call being checked: only an answer to get_order for the order the call names counts, so one order's status never allows another order's refund. Leave it out only for a fact about the conversation as a whole, such as the user's account. A fact is never read from a tool that reads_outside: anyone could write what it returns. Where your code and the file both give a fact, the file's stands.

The proof¶

The agents compile to a graph (qls-graph/1) and its catalogue. Each obligation -- this tool never runs without its check, this write never runs unconfirmed after reading from outside -- is a question the hunter answers over every route:

• reachable: a finding, with a witness path mapped back to the line of agent.yaml (chapter 31);
• unreachable: the obligation holds, to the depth stated (chapter 31);
• undecided: reported as undecided, never as clean.

It runs three ways:

• Automatically. Agent(..., verify=True), the default, proves the graph on our service before the first turn, once per graph: a rebuild of the same graph is answered from the cache. A finding of type Vulnerability raises NotVerified, with the findings, and nothing runs. A proof that could not run raises too, never a clean result.
• As a CI gate. stalwart verify agent.yaml lints, compiles, hunts and prints the report, and exits 1 when the gate fails (chapter 46). The shop agent of chapter 30:

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.
$ echo $?
0

• Over the API. Client().verify_graph(graph, catalogue=..., rulebook=..., session_steps=...) sends the graph desk.export() returns and the catalogue desk.catalogue() returns, as a graph job (chapter 47).

The rules it proves¶

Every rule the hunt of an agent's graph and rulebook raises, generated from the hunter's catalogue. Fails the gate is what stalwart verify holds a build to; stops Agent(...) is what the automatic proof refuses to run with:

Each rule's page says what it proves and what it does not.

The limits¶

• A model chooses freely. The proof reads a model step as able to choose any tool and any argument it is given; the checks hold what it chooses, and nothing proves its choices good.
• Steps that are not ours are opaque. A step your team writes is read as able to do anything its declared routes allow (chapter 31).
• A clean proof holds to the depth it states: the run's step limit and the number of turns the findings document names.
• The proof covers the graph, the catalogue and the rulebook, not your tools' own code; the code checks of chapter 46 read that code for network and credential problems only.
• The rulebook decides only the tools its flows call by execute. A tool no flow governs is decided by the rest of the check.

46 · Checking an agent in CI: stalwart verify¶

stalwart verify agent.yaml is the check a build fails on. It is the proof an agent runs before its first turn (chapter 45), made into a command with an exit status, so a pull request that opens a way past a check, or adds code that turns a certificate check off, stops before it is merged. This chapter is the command in full: what it runs and where, a workflow, a passing and a failing report, and every option and exit status.

Four steps, one on your machine¶

1. The code checks, on your machine. Every Python, JavaScript, TypeScript and Go file of the folder agent.yaml is in is read for network-security and credential problems, by the runtime the package carries. Any finding fails the gate. Your code never leaves the machine: only the count of findings by rule goes with the hunt.
2. The catalogue and the rules. The catalogue -- every tool with its words -- is made and linted on your machine, and the file's rulebook: is compiled into the record the tool check enforces. The rules checked here are the rules your agent runs under (chapter 45). Nothing of the agent is kept on the service.
3. The hunt, on our servers. The agents' graph, the catalogue and the rulebook are sent as one hunt job (POST /v1/solves, with its quality gate on), and the bug hunter searches every route through your agents. The solver runs on Stalwart's servers and never on your machine, and nothing besides the package is installed.
4. The report. Each finding with its rule, its severity, the line of agent.yaml it comes from, its OWASP entries and its fix, then Gate: passed or Gate: failed. Chapter 31 reads a report line by line.

A hunt that could not run -- no route to the service, a job that ended without a findings document -- is an error with exit status 3. It is never a clean result.

What it needs¶

Your key in QLS_API_KEY, and a licence activated on the machine, as every command but stalwart licence, stalwart doctor and stalwart check needs. A CI runner is a new machine every time, so the job activates the licence first and releases its place last, whatever happened in between: a released place is free for the next run at once (chapter 38).

A GitHub Actions workflow¶

# .github/workflows/agent.yml: the shop agent checked on every pull request.
name: agent
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      QLS_API_KEY: ${{ secrets.QLS_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install stalwart-agents
      - run: stalwart licence activate          # a runner is a new machine every time
      - run: stalwart verify agent.yaml --replay --keep findings/
      - if: always()                            # the place is released whatever happened above
        run: stalwart licence release
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: findings
          path: findings/