Skip to content
Sign inSign up

Writing Agent Instructions

Learn how to write effective system prompts for Horizon agents — covering persona, constraints, examples, and best practices.

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.

text
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.

text
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.

text
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.

text
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?"

Agent instructions are not templated

Instructions are used exactly as written. Horizon performs no {{ }} substitution when compiling an agent’s system prompt — the prompt compiler does no interpolation of any kind.

Caution

Writing {{company_name}}, {{agent_name}}, {{current_date}} or similar into your instructions does not insert a value. The literal braces are sent to the model, and nothing warns you — there is no error and no validation message. The agent simply receives text it cannot resolve.

Write the value in directly instead.

Good — the model receives the company name:

text
You are the finance assistant for Northwind Trading.

Avoid — the model receives the literal braces:

text
You are the finance assistant for {{company_name}}.

For anything genuinely dynamic — today’s date, a current balance, a record’s status — ask for it through a skill rather than trying to bake it into the prompt. That is what skills are for, and a skill result is current at the moment the agent runs, which a prompt substitution would not be.

Note

{{company_name}} does exist elsewhere in the platform — it is part of skill-parameter resolution in Horizon Forms, a different subsystem. It has no effect in agent instructions, which is the source of the confusion.

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

text
"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.

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

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

text
"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.