How agent instructions are applied
This page explains the mechanics behind Agent instructions: when they run, what they affect, and how they interact with other parts of the platform.
When instructions run
Agent instructions are injected into the agent's system prompt every time it processes an invoice. That includes:
- The first time an invoice is extracted (after upload or email forwarding).
- When the agent rebuilds the AI Summary.
Instructions do not run retroactively on already-processed invoices. To apply updated guidance to an existing invoice, edit the fields directly or use Copilot to apply the change in one prompt.
What instructions affect
Instructions can shape:
- Field extraction (which fields the agent extracts and how).
- Vendor matching (custom vendor name patterns).
- GL code suggestions on line items.
- Dimension value suggestions on line items.
- Document classification (invoice vs. non-invoice vs. credit memo).
- AI Summary content.
Instructions do not affect:
- Validation rules (those are configured separately; see Configuring rule severity).
- Approval policies (those route documents based on conditions, not on the agent's instructions; see How Approvals Work).
- Notice generation (system rules and integration hooks generate notices; the agent does not control which notices appear).
Where instructions are stored
Each entity has its own instructions stored on the entity record. When an invoice processes for a given entity, the platform reads that entity's instructions and injects them into the agent's prompt.
If your organization has multiple entities, each entity has its own instructions. Instructions you write for one entity do not apply to others.
Interaction with vendor history
Instructions and historical corrections both shape the agent's behavior. They combine, rather than competing.
- Instructions provide explicit rules for behavior the agent could not infer otherwise.
- History comes from corrections you make on actual invoices. The agent learns your preferences by example.
When both apply, the more specific one wins. An explicit instruction ("code all Staples to 5200") overrides historical corrections that conflict. A specific historical correction on a single line item overrides a general "default to 5200" instruction for that line.
Interaction with validation rules
Validation rules run after extraction. If your instruction says "code all subscriptions to 6430" but a validation rule requires the GL account on subscription invoices to come from a specific allow-list, the rule still fires regardless of the instruction.
If a rule conflicts with an instruction, the rule wins. Adjust the instruction or the rule, not both.
Interaction with Copilot
Copilot uses the same agent and instructions. When you ask Copilot to fix a field in plain language, the response respects your instructions. So if you say "recode this to office supplies," Copilot maps that to the GL account your instructions associate with office supplies.
When the agent gets it wrong
If the agent ignores or misapplies an instruction:
- Check whether the instruction is specific enough. "Code Acme to office supplies" is vague (which account number?). "Code Acme to 5200" is concrete.
- Check for conflicting instructions. If two rules cover the same case, the agent does its best with the more specific one but results can vary.
- Check the validation results. A validation rule may be overriding the agent's choice.
- Refine the instruction and confirm the new behavior on the next invoice the agent processes.
Audit
Every change to instructions is recorded in the entity's activity log: who changed them, when, and the diff. Useful for audit and for understanding why behavior shifted at a specific date.