stalwart-agents

Build your own AI agent, powerful but controlled: your tools and your rules, checked on your own machine. Declare it in one file -- its tools, its rules and its users -- then check it and run it. You don't need to learn an agent framework for any of this.

Before you start. You need a Stalwart account and its API key. Sign up at stalwart.it: a free account opens with its first key, in the console, in English or Portuguese. Set the key as QLS_API_KEY, and run stalwart licence activate once on each machine that runs your agents. What each plan includes is on stalwart.it. Nothing in the package works without the key and an activated licence, except activating the licence itself, stalwart doctor, which says what is missing, and stalwart check, which checks a certificate offline (the licence and the runtime).

$ pip install stalwart-agents                # everything: the agents, the client, the gateway, the runtime
$ pip install "stalwart-agents[anthropic]"   # with a model provider: anthropic, openai, google, mistral or ollama
$ pip install "stalwart-agents[all]"         # with every provider

The documentation is at api.stalwart.it/sdk, in English and Portuguese. Start with Build an agent: an agent of your own, from sign-up to stalwart serve.

The local runtime ships for Linux (x86-64 and arm64), macOS on Apple silicon and Windows (x86-64). It reads every turn and checks every tool call on your own machine, under your licence. Anywhere else -- an Intel Mac, Alpine, Windows on ARM -- the same command installs the package without it, and the package's other parts work as usual. Stalwart's hosted API answers no plan and no check: with no runtime, a plan or a check raises SelectorUnavailableError, saying how to set the runtime up.

# agent.yaml
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider and key, from your environment
    tools: [get_order, charge_card, refund_card, read_inbox]
    hands_off_to: [billing]
  billing:
    privilege: high
    tools: [issue_refund]
tools:
  - python: shop.tools                     # plain functions, schemas from their type hints
  - mcp: https://tools.internal/mcp        # an MCP server's tools/list
    receipts: true                         # behind a gateway that admits a call on the agent's own check
  - openapi: ./crm.yaml                    # each HTTP operation a tool
  - name: refund_card
    writes: true
rulebook: ./policy.co                      # Colang 1.0 or 2.x
runs: atomic                               # a failed run is undone
storage: sqlite:///runs.db                 # where runs are kept; postgres://... for several workers

Or in Python, with the same meaning:

from stalwart_agents import Agent, tool

@tool(writes=True, undo="refund_card")
def charge_card(order_id: str, amount: Decimal) -> dict: ...

desk = Agent("desk", tools=[get_order, charge_card, refund_card], rulebook="policy.co",
             model="anthropic:claude-sonnet-5-5")
reply = desk.chat("refund order 4411", user="u-17")
if reply.waiting:                          # a write waits for the person
    reply = desk.confirm("u-17", "approve")

Before a turn runs, the agents' graph is proved once (verify=False runs it unproved). A turn nothing reads is asked to be said again once; then on_unread decides: refuse, model, ask, where the person says whether the model may have it (desk.confirm(user, "approve") or "decline"), or answer, from your documents (below). A request no tool covers -- a calculation, say -- is what model is for. With refuse, no hands_off_to, composer: template for replies and composer: extract for answers, no model is ever called (worked examples).

Guarded and proved. Two checks sit around the model, both decided by native code on your own host: the router decides whether a model is called at all, and every tool call is checked -- allow, confirm or refuse -- whether the router or the model chose it. Before the first turn the graph is proved: every path to a write without its check, its confirmation or its order rule is a finding, and Agent(...) raises NotVerified with nothing run. The rulebook it is proved against is the one it runs under: at start-up, and on every stalwart verify, it is registered with the catalogue for the tool check to enforce (RulebookNotHeld where it cannot be).

from stalwart_agents import Agent, NotVerified

desk = Agent.from_file("agent.yaml")
try:
    desk.chat("refund order 4411", user="u-17")
except NotVerified as refused:            # nothing ran
    for finding in refused.findings:
        print(finding["rule"], finding.get("action"))   # QG012 issue_refund

$ stalwart verify agent.yaml --replay    # in CI: exits 1 when the gate fails
Registered as catalogue version 7, with the rulebook policy.co: the tool check enforces the rules verified here.
QG012 High on issue_refund (agent.yaml:7)
  Replay: reproduced
Gate: failed

In CI. stalwart verify runs the code checks on your machine and the bug hunter on Stalwart's servers -- nothing besides the package is installed. A runner activates its licence first and releases it last:

    env:
      QLS_API_KEY: ${{ secrets.QLS_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: pip install stalwart-agents
      - run: stalwart licence activate
      - run: stalwart verify agent.yaml --replay --keep findings/ --dependencies uv.lock
      - if: always()
        run: stalwart licence release

Exit 0 is a passed gate, 1 a failed one, 2 a file it cannot read or no key, and 3 a hunt that could not run -- never a clean result (the command in full).

Every check, every guarantee and what is proved, with examples: Guarded and proved.

Rules without Colang. The rules over your tools can be a YAML sheet a person reads aloud, compiled to the same rulebook a Colang policy becomes:

# rules.yaml
rules:
  - action: issue_refund
    requires: [supervisor_approved]
    when: { amount_over: 200 }
  - action: close_account
    requires_confirmation: true
  - action: delete_customer
    never: true
  - action: send_statement
    after: [verify_identity]

stalwart rules compile rules.yaml compiles it and lints it against your newest catalogue -- a rule for an action the catalogue lacks, a write the sheet never names -- and --save registers it on the catalogue, where every tool check enforces it. A construct the compiler cannot state exactly is refused with its line, never approximated.

Replies true to what was done. replies: holds every reply to the run it follows:

replies:
  rules: reply-rules.yaml        # personal data by class, phrases never to say, allowed offers
  phrasings: phrasings.yaml      # how each write's outcome is told: done, failed, refused, ...
  composer: model                # or template: the reply is the phrasings, and no model writes it

Each sentence that speaks of a write is held to that write's outcome -- done only if it ran, a failed or refused one never told as done -- and every amount, date, identifier or address in it to a value the call was sent or returned. A sentence that misstates is replaced by the outcome's phrasing, and a write the reply leaves out is added. Personal data the rules withhold is masked, or the reply held back. It runs in the local runtime, and only counts leave the machine.

Answers from your documents. A question no tool answers can be answered from your own documents, never by a tool's side effect: documentation describing a refund is never a refund.

answers:
  index: sources.json      # `stalwart sources build docs/*.md --out sources.json`
  composer: extract        # the documents' own sentences; compose: your model writes from them
agents:
  desk:
    on_unread: answer

Each sentence cites the passage it draws on, and the support check removes one that states a number, date, amount, name or negation its passages do not. It checks those facts, not the meaning around them: a sentence that keeps a passage's facts and draws a conclusion the passage does not is not caught, which is why extract -- the passages' own sentences -- is the default. compose needs a plan that includes composed answers.

Calculations on your host. A turn that needs a calculation no tool answers -- what is the average price of my orders -- is a compute step, on every plan: the tools it reads run, your own model writes one Python function from the data's shape (never its values), the runtime admits it -- no socket, no file, no import outside a short list -- and the qls-sandbox image runs it in a fresh container with no network. It needs a container engine: python -m stalwart_agents.sandbox fetches the image this release runs, and without the engine or the image the turn is declined, its reason starting compute off:.

What reaches Stalwart's servers. Conversations, tool calls, a calculation's data, function and result, your documents and their index stay on your host. What is sent -- a solve and its inputs, a catalogue's tool descriptions, a rule sheet, a guardrail generation prompt, and a thumb's feedback record, which carries the words of the turn it rates -- is scanned first for e-mail addresses, telephone numbers, payment card numbers, IBANs, UK National Insurance and Brazilian CPF numbers, and any identifiers you list as your own (Client(own_identifiers=[...])). A match sends nothing: PersonalDataError names each match's kind and where it is, never its value.

A person's thumb on a reply is feedback the hosted miner learns your users' words from:

reply = desk.chat("what is in order 4411?", user="u-17")
desk.thumbs(reply, up=False)        # one record: the turn's words, the tool, the router's verdict and rule

The record holds the rated turn's words and the router's reading of them -- the tool, its verdict and deciding rule, the tools the agent could reach -- and nothing else: no reply text, argument value, tool result or earlier turn. A turn the router could not read and the model answered records the verdict unread and the tool the model called. The same thumb twice is one record. Some thumbs are refused with ThumbRefused, saying what to thumb instead: a turn of several instructions is thumbed one step at a time (step=0, step=1, ...), and the reply after a confirmation is thumbed on the turn that named the tool. stalwart serve takes the same thumb at POST /threads/{id}/feedback, from the session that was shown the reply only.

An MCP server's tools are called in an MCP session per user: the user a turn names, or its thread under stalwart serve. What a server keeps for one session never reaches another user. desk.close() ends every session; stalwart serve ends them when it stops.

A tool's words are plain: writes, undo, irreversible, retry_safe, reads_outside, sends_out, after, not_after, at_most, and the words the bug hunter's OWASP rules read (argument_kinds, sandboxed, confidential, ...). checks, filter, spend, currency and outcome say only if, how much and when is it done in one grammar (stalwart_agents.conditions); they are checked when agent.yaml is read, and not yet applied to a call. A model is provider:model, resolved with your own key from your environment. A missing key is named before anything is sent. A model can also be a plain function that takes the conversation and returns the reply.

Nothing on stalwart_agents' own surface names LangChain or LangGraph: no name, signature, error or message. A test holds the package to that. stalwart_agents.langchain is there for a team already on LangGraph. desk.graph() is the one way to reach the graph that runs underneath, for a team that wants to extend it.

The same install carries the rest, each documented on its own page: