Best practices for writing guides

AI Agent interactions are non-deterministic—meaning they may respond differently to the same query across different sessions, even when using the same guide. However, you can shape their behavior and improve consistency by following best practices when you write instructions of a guide.

Plan your guides

As you plan your guide, make sure to stay on goal and ensure that your guides are not lengthy.

Keep the guide focused on a single task

It is recommended to design each guide to handle a single, well-defined customer intent such as “change delivery date” or “check account balance”. Limiting each guide with one intent narrows the scope of the LLM to ensure predictability and accuracy. For conversations involving multiple intents, connect multiple guide blocks within a single Architect flow.

Keep the guide short

To build a successful guide, start with the essential steps first, validate with real users and data, and slowly extend the capabilities to achieve the desired result. With the right foundations and an iterative approach, AI agents can deliver real business value—automating not just tasks, but entire workflows with intelligence and adaptability. 

Maintain a professional and conversational tone

While your guide’s instructions may be technical, the resulting AI agent interaction should be natural. Phrase your instructions in such a way that they create a professional, helpful, and conversational tone.

Build your guides

Follow these guidelines for structuring, formatting, and creating simple, manageable tasks.

Structuring and formatting your guide 

  • Number the first step manually. The editor continues the numbering as you press Enter. 
  • Use indentation to represent a form of hierarchy so your AI agent can interpret the structure well. 
  • Use quotations when you want your AI agent to say a specific phrase or message. For example, “Can you describe the status lights on your router?”.
  • Mention any units or currencies that are part of the guide. For example, “All product values are in Euros € “.
  • Use specific formats for dates. For example, “dd/mm/yyyy”.

Break down your task into simple steps

Divide a complex task into simpler, more manageable steps. This process ensures that your Virtual Agent can follow the instructions accurately without getting overwhelmed.

  • Number each step in the order you want your AI agent to run the task. Numbering the steps also allows you to instruct your AI agent to break sequential execution and jump to any of the steps in the guide.
  • As an added measure, segregate your guide into main steps and sub-steps. With this approach, you can assign a unique name to your main steps, allowing your AI agent to jump to any of the main steps as necessary.
1. Basic checks
   ...
2. AB Refund
   ...
3. Refund
   ...
4. Troubleshooting
  - If customer has a model type A or B:
    - Go to: [AB Refund]
  - else if customer has any other type:
    - Go to: [Refund]

Trigger a customer action or prompt at the end of each step

  • Ensure that every step in the guide makes your AI agent anticipate a customer action or response.
  • If the current step has no such query, combine it with the next step that does require a customer reply. 
  • Use a single message when you want your AI agent to say multiple messages sequentially, without expecting a customer reply. 

Good example

Bad example
  1. Gather customer order and email information

 – Agent asks customer for their {{Variable.orderID}}

 – Customer provides {{Variable.orderID}}

 – Agent asks customer for their {{Variable.email}}

 – Customer provides {{Variable.email}}

 – Call {{Action.getOrderStatus}} using {{Variable.orderID}} and {{Variable.email}}
  1. Gather customer order and email information

 – Agent asks customer for their {{Variable.orderID}}

 – Agent asks customer for their {{Variable.email}}

 – Call {{Action.getOrderStatus}} using {{Variable.orderID}} and {{Variable.email}}

Use square brackets to jump between steps

  • Refer to other steps using square brackets. 
  • State the destination steps clearly.

Good example

Bad example

Go to [Gather Patient Information] step.

Go to step 2.

Reduce ambiguity

  • When defining steps, be precise and specific about the outcome or response you want from the AI agent.
  • Abstain from using ambiguous, vague, or broad instructions. Clear instructions help your AI agents to produce better results.
  • Provide as much context as possible by including variables, data actions, and specific guidance on handling different scenarios. Set up your agents to handle unexpected scenarios with a contingency plan. For example, if a user says “I don’t know”, your agent should recognize the user’s uncertainty and respond with “I am sorry, I am unable to help with your query. Do you want to connect with an human agent?”. You can add a sub-step under your main step to handle such unexpected scenarios.

    Preview and iterate

    • Test your guide by connecting it to an Architect bot flow and refine your instructions until you are satisfied with your AI agent’s performance. For more information, see Test and troubleshoot guides.