Understand how Agent instructions apply
This page explains the mechanics behind Agent instructions and Agent Memories: 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).
Instructions do not run retroactively on already-processed invoices. To apply updated guidance to an existing invoice, edit the fields directly or use Clark to apply the change in one prompt.
When memories run
Active memories are retrieved when their type, scope, and content match the agent's current invoice or email context. Global memories can guide all matching work for that agent; Vendor memories are restricted to their vendor anchor. The agent can use approved memories on future processing and show a From memory rationale on a field when one contributed to the value.
The nightly authoring process proposes new or changed memories from repeatable reviewer corrections. A proposal enters Tasks for approval before it becomes active. Admins can also create an active memory from the Agents page. See Agent Memories and Approve proposed memories.
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).
- Field-level coding rationales and recommendations.
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. A memory still cannot bypass validation or approval policy.
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 Clark
Clark uses the same Agent and instructions. When you ask Clark to fix a field in plain language, the response respects your instructions. For example, if you say "recode this to office supplies," Clark uses the 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.