Write effective agent instructions
This page is the practical guide to writing Agent instructions. The goal is to encode the conventions your team already follows so the agent applies them on every future invoice without your team having to correct them manually.
Open the editor
Click Agents in the left sidebar. The markdown editor on the left is where you write instructions. The guide on the right has reference content and example prompts.
Use a structured format
The agent reads instructions as plain markdown. A clear structure makes it easier to maintain and easier for the agent to follow.
A useful skeleton:
## GL coding conventions
- Office supplies code to 5200.
- Legal services code to 6300, except M&A advisory which goes to 6310.
- Travel expenses code to 6500. Hotel and airfare both go here.
## Vendor-specific behavior
### Acme Corp
- Their invoice number is on page 2, not page 1.
- Their PO number is in the format "ACME-12345".
### Staples
- Treat all line items as Office Supplies (account 5200) unless the description says "ink" or "toner", which go to 5210.
## Dimension assignments
- Set Department to Marketing for invoices from advertising agencies.
- Set Cost Center based on the manager listed on the invoice.
## Document classification
- Documents titled "Statement" are not invoices. Classify them as non-invoice.
- Credit memos may arrive looking like invoices. If the total is negative, treat as credit memo.
Write rules, not stories
Instructions work best as concise rules, not narrative explanations.
Bad:
Our company has a long history of working with Staples for office supplies, so they should generally be coded to the office supplies account.
Better:
Code all Staples invoices to account 5200 (Office Supplies).
The agent's job is to apply rules to invoices. Specific, machine-readable rules apply more reliably than prose.
Be specific
Vague instructions produce inconsistent behavior.
Bad:
Code IT-related invoices appropriately.
Better:
IT services (including consulting, support, and managed services) code to 6420. IT hardware (laptops, monitors, peripherals) code to 5410. Software subscriptions code to 6430.
Use exact account codes and dimension values
Reference actual account numbers and dimension values from your ERP. The agent matches what you write against the values it has synced from your Fields.
Good:
Code all subscription software to 6430 (Software & Subscriptions).
Bad:
Code subscriptions to the software account.
Lead with the most common patterns
Put your highest-volume conventions at the top. The agent reads the entire prompt, but well-organized instructions are easier to update later.
Update as patterns emerge
When you find yourself correcting the same coding repeatedly, that is a sign to add it to the instructions.
A useful workflow:
- Notice a pattern in your corrections (for example, you keep recoding Acme invoices).
- Add a rule that covers it.
- Save the instructions.
- The next Acme invoice the agent processes uses the new rule.
Test your changes
Instructions take effect on the next invoice the agent processes. After a significant update:
- Save the instructions.
- Wait for or upload a new invoice that should trigger the rule.
- Confirm the agent applied your new rule once it has processed the invoice.
- If not, refine the instruction and try again on the next invoice.
Common pitfalls
- Conflicting rules. If you write two rules that contradict each other ("code all travel to 6500" and "code airfare from Acme to 6510"), the agent does its best to apply the more specific one but results may be inconsistent. Be explicit when one rule is an exception to another.
- Over-specifying. Hundreds of one-off rules slow down the agent and make instructions hard to maintain. Keep the instructions focused on patterns that affect many invoices.
- Vague conditions. "Some invoices from Vendor X..." is not actionable. The agent needs a concrete trigger.