Skip to main content

Writing Effective Instructions

Poorly written instructions are one of the most common reasons AI agents behave inconsistently, misunderstand tasks, or produce unpredictable responses. This guide explains how to write clear, technically precise instructions that make your agent reliable, predictable, and aligned with your goals.

1. Be Specific and Concrete​

Language models do not infer meaning from vague or abstract phrasing. Always describe observable behavior rather than intent.

Example:

❌ Poor: “Be helpful”
✅ Good: “Provide step-by-step guidance. If the user is unclear, ask one clarifying question.”

Explanation:
“Helpful” could mean giving direct answers, offering extra information, or even taking initiative unprompted.
Specific descriptions ensure reproducible, testable behavior across sessions.

2. Align Identity, Tone, and Task​

All configuration elements—Identity, Speech Style, and Task—must reinforce the same behavioral profile. Conflicting instructions are a major source of instability.

Example:

❌ Conflicting:
Identity: “Friendly, casual support agent”
Speech Style: “Use formal business English”
✅ Aligned:
Identity: “Professional, polite support agent”
Speech Style: “Use formal tone while remaining warm and respectful”

Result:
A coherent persona that maintains consistent tone, regardless of the situation.

3. Use Examples as Behavioral Anchors​

Few-shot examples are one of the most powerful configuration tools. They act as direct templates for how the agent behaves in similar situations.

Example Dialogue:

## Example dialogues

### Successful verification
Agent: Hello, am I speaking with John Smith?
User: Yes
Agent: <Action: verify_identity>

### Wrong person
Agent: Hello, am I speaking with John Smith?
User: No, wrong number
Agent: I apologize for the inconvenience. Have a good day.

Key point: If the real conversation matches your example, the model will often repeat it exactly. Use this to enforce deterministic handling of frequent scenarios.

4. Define Behavior, Not Personality​

Avoid abstract personality descriptions. Define explicit operational behaviors. This ensures that any developer or tester can interpret the instruction identically.

Example:

❌ "Be confident and proactive"
✅ "If the user hesitates, suggest one next step with justification.
Avoid asking more than one question at a time."

Behavior-based definitions make results predictable and measurable.

5. Avoid Conflicting or Redundant Directives​

Contradictions across configuration layers (identity, tools, workflows, policies) create ambiguity in model reasoning.

Checklist:

  • Every instruction must support the agent’s main objective.
  • Avoid overlapping behavior definitions (for example, both “ask questions” and “never ask questions”).
  • Consolidate similar rules into a single statement.

6. Test in Realistic Scenarios​

Testing is part of instruction design. Validate the agent in multiple environments and user types before deployment.

Recommended sequence:

  1. Happy path – straightforward, ideal input
  2. Ambiguous input – unclear or partial requests
  3. Hostile input – aggressive or frustrated tone
  4. Failure handling – unavailable data or external errors

Goal: Observe how consistently the agent applies defined rules and tone across these cases.

7. Iterate and Measure​

LLM-based agents drift as their workflows, knowledge bases, and integrations evolve. Regularly review and refine configurations to maintain predictable performance.

Review cadence:

  • Weekly: check active transcripts for tone, logic, and accuracy
  • Monthly: analyze conversation completion and satisfaction metrics
  • Quarterly: clean outdated knowledge and redundant workflows

Metrics to track:

  1. Response consistency across sessions
  2. Average handling time per scenario
  3. Escalation rate and causes
  4. User satisfaction or completion rates

8. Optimize for Performance and Clarity​

Large or disorganized configurations reduce both speed and stability. Keep the instruction set minimal and modular.

Best practices:

  • Split large knowledge bases into topic-specific subsets
  • Remove obsolete or conflicting content regularly
  • Avoid excessive Fast Access knowledge — include only essentials
  • Simplify workflows before adding integrations

Testing tip: Measure latency and accuracy after each configuration change to quantify impact.