Agent Instructions

Instructions are the most important part of agent configuration. They define the agent's behavior, expertise, output format, and constraints. This page explains how to write effective instructions for your AI agents.

How Instructions Work

When an agent processes a workload, its instructions are assembled into a conversation context sent to the AI provider. The full context includes, in order:

Agent Identity (system prompt) — "Your Name is [WorkerID] and Job [Title]"
AI Setup Prompt (system prompt) — Company information, country, currency, current date
Agent Instructions (system prompt) — Your custom instructions from the agent's Instructions field
Workload Type Instructions (system prompt) — Additional instructions from the workload type
Workload Description (user message) — The specific task to process

This layered approach means your agent instructions should focus on the agent's role and behavior, while task-specific details go in the workload type instructions and workload descriptions.

Editing Instructions

Go to the AI Agents page (Worker List)
Select the agent you want to configure
Choose Edit Instructions from the action bar
The Instruction Editor opens with a code editor
Write or modify your instructions
Close the editor to save

Writing Effective Instructions

Define the Role

Start with a clear statement of who the agent is and what it does:

You are a senior accounts payable clerk with 20 years of experience.
Your expertise is in categorizing expenses, matching invoices to purchase
orders, and identifying discrepancies in vendor billing.

Specify the Task

Describe what the agent should do when it receives a workload:

When you receive an invoice or expense report:
1. Identify the vendor or source
2. Extract the total amount and line items
3. Match each line item to the appropriate GL account
4. Flag any unusual or potentially incorrect charges
5. Provide a summary of your findings

Define the Output Format

Tell the agent exactly how to format its responses:

Return your analysis in the following format:

Vendor: [name]
Invoice Number: [number]
Date: [date]
Total: [amount]

Line Items:
- [description]: [amount] → Account [GL account number]

Flags:
- [any issues or concerns]

For agents that pass data to other specialized agents, use structured formats like JSON:

Return your results as a JSON object:
{
  "vendor": "name",
  "amount": 1234.56,
  "account": "6100",
  "description": "Office supplies"
}

Set Boundaries and Rules

Define what the agent should and should not do:

Rules:
- Never create entries with amounts exceeding $50,000 without flagging for review
- Always use the current fiscal year for date fields
- If you cannot determine the GL account, use 9999 (suspense account)
- Do not modify existing posted entries
- If the vendor is not found in our system, report it rather than guessing

Provide Business Context

Include information about your specific business setup:

Our chart of accounts uses the following structure:
- 1000-1999: Assets
- 2000-2999: Liabilities
- 3000-3999: Equity
- 4000-4999: Revenue
- 5000-5999: Cost of Goods Sold
- 6000-6999: Operating Expenses
- 7000-7999: Other Income/Expenses

Our main cost centers are:
- ADMIN: Administration
- SALES: Sales Department
- OPS: Operations
- IT: Information Technology

Instruction Layers

Agent Instructions vs. Workload Type Instructions

Layer	Where to Set	Scope	Example
Agent Instructions	Worker card → Edit Instructions	Applies to all workloads this agent processes	"You are an invoice analyst. Always return JSON."
Workload Type Instructions	Workload Type card → Edit Instructions	Applies to all workloads of this type	"Process invoices for the ADMIN cost center only."
Workload Description	Workload card → Task Description	Applies to this single workload	"Process the attached invoice from Contoso Ltd."

This layering lets you reuse agents across different workload types while customizing behavior per type.

Example: Same Agent, Different Types

Agent: INVOICEAI Agent Instructions: "You are an accounts payable specialist. Analyze invoices and extract structured data."

Workload Type: DOMESTIC-AP Type Instructions: "These are domestic invoices. Use USD currency. Apply standard payment terms NET30."

Workload Type: INTL-AP Type Instructions: "These are international invoices. Convert amounts to USD. Flag any currency conversion issues."

The same agent behaves differently based on the workload type context.

Instruction Patterns

The Coordinator Pattern

For an agent that routes work to other agents:

You are a task coordinator. When you receive a workload:
1. Analyze what needs to be done
2. Break the task into subtasks
3. Delegate each subtask to the appropriate agent:
   - For data lookups, ask DATAQUERY
   - For journal entries, ask GLPOSTER
   - For sales documents, ask SALESAGENT
4. Combine the results and provide a final summary

The Validator Pattern

For an agent that checks other agents' work:

You are a quality reviewer. When you receive results from another agent:
1. Check that all required fields are present
2. Verify amounts are reasonable (flag anything over $100,000)
3. Confirm account codes match our chart of accounts
4. If everything passes, respond with "APPROVED: [summary]"
5. If issues found, respond with "REVIEW NEEDED: [issues]"

The Formatter Pattern

For an agent that structures data for document creation:

You receive analyzed data and must format it for journal entry creation.
For each entry, provide:
- Account No.: [the GL account number]
- Amount: [positive for debit, negative for credit]
- Description: [max 50 characters]
- Document No.: [from the source document]

Ensure that debits equal credits for each transaction group.

System Prompts

In addition to agent instructions, Simple Agent Designer uses system prompts for orchestration messages. These are configured in Setup → System Prompts and typically do not need modification. They include:

Prompt	Used For
PleaseStart	Starting a workload — sent as the first message
AreYouComplete	Checking if the agent has finished
NameAndJob	Establishing agent identity
TaskComplete	Confirming task completion
TaskFailed	Reporting task failure
ReplyFrom	Formatting messages between agents

System prompts support parameter substitution (e.g., %1 for agent name, %2 for job title) and language-specific versions.

Tips and Best Practices

Keep instructions concise but complete — the AI reads them on every call, and longer instructions use more tokens
Use numbered lists for multi-step procedures
Include examples of expected output when the format matters
Test instructions with simple workloads before running production data
If an agent produces unexpected results, review and refine its instructions
Avoid contradictory instructions — be clear about priorities when rules might conflict
Use consistent terminology across all your agent instructions
Remember that agent instructions are combined with workload type instructions — avoid duplication