State instructions guide your agent’s behavior within specific conversation states. Each state represents a distinct phase or purpose in the conversation.

Although not binding, aim for 200-600 words or 5-15 bullet points per state instruction as a healthy range. The focus is on well-written, clear instructions.

​
Key elements to include

Variables

Specify which variables can be accessed within the state. For more information on how to use variables, see.

Transition conditions

Define conditions for transitioning to other states.

Tools

Specify which tools the agent can use and how to use them in this state.

​
State transitions and flow control

​
Writing clear transition triggers

Each state should specify precise conditions that trigger transitions to other states. Use direct, unambiguous language to define these triggers.

Direct Language

Use phrases like “if user says…” or “on receiving…”

Clear Actions

Specify the exact state to transition to

​
Conditional logic in state instructions

Keep conditions straightforward and explicit to avoid confusion during runtime.

Good Pattern:

If user provides email, update variable:user_email and transition to state:ConfirmDetails

Bad Pattern:

If user responds:  # Too vague
  - Check response
  - Maybe transition  # Unclear action

​
Writing effective instructions

Language clarity

Use simple, concise language and avoid jargon or complex sentences that may confuse the user.

Example:

  • Instead of: “We would be delighted to assist you with any inquiries you might possess.”
  • Use: “How can I help you today?”

Ensuring good translation

Use simple language that translates well across different languages. Avoid complicated English words that may sound unnatural in other languages.

Example:

  • Instead of: “it would be very challenging for xyz”
  • Use: “its difficult for xyz”

Active voice

Always use active voice in instructions. Passive voice can be confusing and often translates poorly.

Example:

  • Instead of: “The account should be checked for verification”
  • Use: “Check the account to verify”

Response length

Add prompts to specify the length of agent responses. Long responses may overwhelm the user whereas very short responses may lack the necessary information.

Example: “Keep the responses between 50-100 characters”

Exact responses

If you want to exactly specify the agent response in certain cases, enclose it within quotes.

Example: Say “Which product did you use recently?”

Conflict check

Ensure prompts don’t provide conflicting information. Compare prompts across states and the global prompt, and update any discrepancies to maintain conversation coherence.