Writing Agent Instructions

Instructions are the single most important configuration for an agent. They define the agent’s persona, tell it what to do (and what not to do), and shape every response it generates. In LLM terminology, instructions become the agent’s system prompt.

Anatomy of good instructions

Effective agent instructions have four sections:

1. Persona

Define who the agent is and how it should communicate.

You are a senior accounting analyst at {{company_name}}.
You communicate in a professional but approachable tone.
You always explain financial concepts in plain language
when speaking with non-finance team members.

The persona sets expectations for tone, expertise level, and communication style. Use {{company_name}} and other template variables to personalize instructions per workspace.

2. Scope and responsibilities

Clearly state what the agent should and should not do.

Your responsibilities:
- Answer questions about profit & loss, balance sheets, and cash flow
- Generate QuickBooks reports on demand
- Look up customer and invoice information
- Flag unusual transactions or discrepancies

You do NOT:
- Make financial decisions or approve payments
- Access payroll or employee compensation data
- Modify accounting records without explicit user confirmation

Caution

Agents without clear boundaries tend to over-promise. If an agent lacks a skill for something, explicitly instruct it to say so rather than hallucinate a response.

3. Constraints and rules

Define hard rules the agent must follow.

Rules:
- Always confirm before creating or modifying any invoice
- When reporting financial figures, always include the date range
- Never display raw API responses — summarize data into readable tables
- If a QuickBooks query returns no results, ask the user to verify
  the search criteria before retrying
- Always use the company's fiscal year (April 1 - March 31) unless
  the user specifies different dates

4. Examples

Provide concrete input/output examples to demonstrate desired behavior.

Example interaction:

User: "What were our sales last quarter?"
Agent: "Here are the sales figures for Q3 (October 1 - December 31, 2025):

| Category        | Amount      |
|-----------------|-------------|
| Product Sales   | $142,500.00 |
| Service Revenue | $87,200.00  |
| **Total**       | **$229,700.00** |

This represents a 12% increase compared to Q2. Would you like
a breakdown by customer or product?"

Template variables

Horizon supports template variables in agent instructions that are automatically replaced at runtime:

Variable	Replaced with
{{company_name}}	The workspace’s company name
{{department_name}}	The agent’s assigned department
{{agent_name}}	The agent’s display name
{{current_date}}	Today’s date in the workspace’s locale
{{fiscal_year_start}}	The configured fiscal year start date

Instruction length guidelines

There is no hard character limit on instructions, but keep these guidelines in mind:

• 500-1,500 characters — typical for focused, single-purpose agents.
• 1,500-4,000 characters — appropriate for agents with complex responsibilities, many rules, or detailed examples.
• 4,000+ characters — consider whether the agent’s scope is too broad. It may be better to split into multiple agents.

Note

Longer instructions consume tokens on every conversation turn. This affects both response latency and cost. Be thorough but concise.

Common pitfalls

Too vague

❌ "You are a helpful assistant. Answer questions about our finances."

This gives the agent no constraints, no persona, and no examples. It will produce generic responses.

Too rigid

❌ "Only respond with exactly these phrases..."

Over-constrained agents cannot handle variations in user requests and will frustrate users.

Just right

✅ "You are a financial analyst specializing in accounts receivable.
When users ask about outstanding invoices, query QuickBooks and
present results in a table sorted by due date. If an invoice is
overdue, highlight it and suggest follow-up actions. Always confirm
the customer name before running a search."

Clear persona, defined scope, formatting guidance, and a specific behavior rule.

Iterating on instructions

Instructions are not write-once. Use the following workflow to refine them:

1. Write an initial draft covering persona, scope, constraints, and at least one example.
2. Deploy the agent and test with real-world queries.
3. Review conversation logs for places where the agent behaved unexpectedly.
4. Add constraints or examples to address those gaps.
5. Repeat.

The conversation history in the Horizon dashboard is your best tool for instruction refinement — it shows exactly how the agent interpreted your instructions in practice.