How Spend's agents work

Spend’s own agents (invoice exceptions, supplier onboarding and risk, P-Card review, request to PO, solicitation drafting, contract review and payment run guard) run on one runtime in @spend/ai. This page explains how they behave, for the architects and auditors who need to know.

An agent is a spec

Each agent declares:

• Tools, each one of three kinds:
  • Read: look something up, such as the invoice and its match, the supplier’s bank history, or similar past invoices.
  • Write: an internal, reversible change, such as writing findings on a case or putting an invoice on hold.
  • Propose: something only a person may do. The proposal names the permission it needs and waits for someone who holds it.
• Due work: how it finds items waiting for it, such as invoices that entered exception, or payment runs prepared.
• A brief: the job and lightweight pointers. Details are fetched through tools, so the model reads only what it needs.
• A playbook: the same job done by rules, with the same tools.
• Limits: tool calls, turns and tokens per run.

How a run goes

1. A trigger starts the run: a new item (the sweep runs a few per agent per tick, so a burst of mail is not a burst of model calls), or a person asking from the record.
2. The runtime checks whether the subject is in a class kept from the AI provider. If it is, or AI is off, or the agency set the agent to rules only, the playbook runs instead.
3. The model works through the tools. Text from suppliers, requesters and documents is wrapped and marked as data, never instructions, and guardrails check every proposal (for example, an agent may not quote a bank account number from a document).
4. Proposals wait for a person. Approving one executes it under that person’s name, with all the usual permission and segregation-of-duties checks.

A newer run on the same subject withdraws proposals an earlier run left pending.

Lessons

When a person edits or rejects a proposal, the change and note are kept as a lesson keyed to the subject, such as the supplier. Later runs on the same key read those lessons first, so agents follow the agency’s practice.

Modes

The policy pack sets each agent’s mode: auto (works new items), on_demand, rules_only or off.

Measuring agents

The Agents page reports, per agent: runs, the straight-through rate (finished runs that needed no change) and the share of proposals accepted as written.

An evaluation suite of scripted tasks covers all seven agents, including adversarial ones such as injected instructions in an invoice or receipt. The rules playbooks are checked on every build; the same tasks run against the live model with repeated trials to measure consistency.

Audit

Every step (each tool call with its input and a short form of its output, each guardrail and each proposal) is on the run and on the tenant’s ledger, with the model, prompt version and input digest.