Skip to main content

Best Practices: 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.

Identity and Style​

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

Where to configure

  • Identity — agent role, expertise, and responsibilities
  • Speech Style — tone and communication rules
  • Task — actions, decision logic, and interaction flow

Be Specific​

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

Define Behavior, Not Personality​

Avoid abstract personality descriptions. Define explicit operational behaviors. This ensures that any developer or tester can interpret the instruction identically. Behavior-based definitions make results predictable and measurable.

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

Keeping Identity and Task Consistent​

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.

Best Practices for Workflow​

Few-shot examples added to the workflow 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.

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

Avoid Configuration Conflicts​

Contradictions across configuration areas — identity, task, knowledge, and workflow — 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

Keep agent configuration maintainable​

Large or disorganized configurations reduce both speed and stability. Keep all agent instructions — identity, task, and workflow — 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
tip

Measure response speed and accuracy after each configuration change to quantify impact.