Best practices

Overview

Effective Playbooks guide your AI Agent through complex workflows with clear, well-structured instructions. These best practices help you write Playbooks that are easy to understand, maintain, and scale.

General guidelines

These guidelines help you create effective Playbooks that are easy to understand and maintain.

Let Ada create a first draft

The Generate a Playbook feature helps you quickly create a first draft based on a simple prompt or an existing PDF file. To get the best results, clearly define your goal and the scenario or task you want the Playbook to address. Include enough context in your prompt to guide the generation accurately, but keep it concise and focused. Starting this way also helps you understand how to write a Playbook using the best practices outlined below.

Write like you’re writing for human agents

Write your Playbook as if you’re creating a standard operating procedure for a human agent. This means using clear, straightforward language that feels natural and conversational, rather than overly technical or robotic. Imagine you’re training a new customer service representative: your instructions should be easy to understand, detailed enough to follow without additional explanation, and structured logically, step by step. Avoid jargon, ambiguity, or assumptions that might confuse an agent unfamiliar with your processes.

Peer review your Playbooks

As the author, you might overlook missing details or unclear instructions. Having someone with limited context review your Playbook and provide feedback can go a long way in helping identify gaps and areas needing clarification. Encourage reviewers to imagine themselves as the customer service representative following the instructions.

Specific writing guidelines

Follow these formatting and structural recommendations to make your Playbooks clear and consistent.

Use rich formatting to make Playbooks easy to read and follow

• Use headings to structure the Playbook into clear, high-level steps (e.g., Step 1, Step 2).

• Break down instructions into short, clear lists rather than long paragraphs.

• Use numbered lists for sequential actions to highlight logical progression.

• Use bulleted lists for parallel actions or options.

• Highlight critical details with bold text.

• Use quotations to indicate specific messaging the AI Agent should use (e.g., “insert specific quote here”).

  Important: Use quotation marks around end user-facing messages when you want Playbooks to follow your phrasing closely. This improves interpretation and consistency.

Example:

Write well-structured Playbooks to make them easy to follow

When building complex Playbooks, especially those with multiple branches or variables, keep your content structured, scannable, and predictable. These guidelines help ensure clarity and consistency across steps.

• Avoid deep, multi-level lists. Keep steps flat and easy to scan. Nested lists make instructions harder for both users and the AI Agent to follow.
• Use flat bullets or numbered steps with clear, single-level items. Each step should contain only one clear instruction or decision point.
• Trim general guidance to essentials. Include only the high-impact, unique rules the model truly needs.
• Use a consistent scheme for H1 step titles (for example, 1, 2, 3… or 2A, 2B, 2C). Consistency helps users and reviewers quickly locate and reference specific steps.
• Provide a short Flow Overview at the top of your Playbook that summarizes the high-level process before diving into detailed steps.
• End each step with an explicit outcome and next-step cue (for example: Order found and confirmed. Then proceed to Step 3.). This helps define clear transitions and ensures the AI Agent knows when a step is complete.

Build Playbooks that handle every scenario

Writing clear instructions is just the start. A well-crafted Playbook should be clearly structured and easy to follow, guiding the AI Agent smoothly through both common and uncommon scenarios. The best Playbooks are:

• Easy to scan at a glance
• Explicit about each step
• Resilient to edge cases

Examples:

✅ Step 1: Ask for the end user’s email address

• If the email matches an existing account, confirm the account status.
• If it doesn’t match, ask the end user to try another email or initiate @handoff_to_support

❌ Ask the user to provide their email and then verify account info. If it doesn’t match, figure out the next best step or send them to support.

✅ Step 2: Offer resolution options

• If subscription is active, provide refund or reschedule options.
• If subscription is canceled, offer reactivation instructions.

❌ Resolve issue based on subscription.

Working with Actions, Handoffs, Exits, and Variables

Playbooks can reference Actions, Handoffs, Exits, and Variables to create dynamic workflows. These guidelines help you use them effectively.

Use intuitive names and descriptions

The names and descriptions of Playbooks, Actions, Handoffs, and Variables are visible to the AI Agent.

• Use clear, intuitive names and descriptions to immediately convey purpose and context
• Avoid technical jargon and abbreviations
• Avoid overlapping names and descriptions

Examples:

Incorporate Actions and Handoffs

Actions and Handoffs let your AI Agent do more than just follow instructions, they allow it to complete tasks and escalate when needed. You can think of them as tools that your AI Agent can use as it’s going through a Playbook.

To keep handoff logic consistent and easy to maintain, route escalations to a single dedicated handoff section rather than placing handoff steps throughout the Playbook. Use a clear phrase such as proceed to section X to direct the flow to that section.

Example:

✅ Step 3: Retrieve the end user’s order

• Use @get_order_details to retrieve the end user’s order
• If orders are returned, confirm the item and shipping status with the end user.
• If no data is returned, ask the end user to double-check if the order number they provided is correct
• If you’re still unable to find the order, initiate @handoff_to_support to connect the end user with a specialist.

❌ Check order details with the end user.

Avoid giving excess information that the AI Agent doesn’t need

When configuring your Actions for the AI Agent to use, optimize for giving only the required information for solving the end user’s inquiry. You can leverage JMESPath in the Action Output settings to filter out unnecessary fields.

Use explicit Exits to control the flow

Exits give you two ways to end: explicitly, where you decide exactly when the flow stops, or implicitly, where it ends on its own when it seems complete. Knowing when to choose each approach helps you design conversations that are both reliable and natural.

Choose an explicit Exit when:

• You need guaranteed flow termination (e.g., integrations where failing to exit could break the experience).
• A Playbook should always stop at a specific decision point, regardless of conversation context.
• Reliability is more important than flexibility (e.g., regulated workflows, partner-specific integrations).

Let Playbooks end automatically when:

• The conversation may branch flexibly and you want the AI Agent to decide when to close the Playbook.
• You want smoother, more natural endings where strict control isn’t necessary.
• Your flows benefit from reduced manual exits (e.g., exploratory or lightly-guided flows).

Also, when reviewing conversation transcripts, you may notice that hovering over a sent message displays a different Playbook than the one that was originally triggered. This happens when a Playbook does not properly exit and a subsequent Playbook takes over, updating the internal reference (similar to overwriting a global variable). Ensuring each Playbook exits explicitly and cleanly helps maintain accurate transcript references.

Example:

✅ Step 1: Ask if the request is about order issues, product questions, or something else.

• If the request is about something else, explain that only order issues and product questions are supported.
  @Exit Playbook
• If the request is about order issues, provide steps to look up and resolve the order issue.
• If the request is about product questions, provide relevant product details and guidance.

❌ Ask if the user wants to track an order or start a return. If the user wants to track an order, provide the order status. If the user wants to start a return, guide them through the return steps.

@Exit Playbook

Use Variables correctly

Your AI Agent can read variables values that you explicitly reference within a Playbook so it can personalize the experience based on attributes that were set or collected previously. You can also instruct the Agent to save specific attributes to Variables so it can be referenced later on in the conversation or for reporting purposes.

Example:

✅ Step 5: Inform the end user on refund ETA

• If the user’s @country is the US, inform them that the refund will take 2-3 business days
• If the user’s @country is Canada, inform them that the refund will take 3-5 business days.
• If the user’s @country is neither Canada nor the US, inform them that the refund will take 7-14 business days.

❌ Inform the end user on refund ETA based on if they’re in the US, Canada or somewhere else.

Communicating your procedure

Clear communication ensures the AI Agent follows your intended logic. These guidelines help you write instructions that are unambiguous and complete.

Clearly define conditional logic

Explicitly mention conditions and corresponding actions, using indentation to show branching paths. Avoid combining multiple conditions into one sentence.

Example:

✅ Ask the end user for their phone number:

• If it matches the account_phone_number, confirm with the end user.
• If it doesn’t match: ask for the number associated with their account.

❌ Ask the end user for their phone number and confirm whether it matches their account - if not ask for the number associated with their account.

Handle exception scenarios

Always provide clear instructions for handling exceptions, including:

• An explicit otherwise/else clause for if conditions
• Guidance for situations when Actions return no information or fail

Example:

✅ Step 1: Look up the end user’s order using @get_order_details.

• If an order is found, confirm the item and shipping status with the end user.
• If no order is found, ask the end user to provide their order number again or escalate using @handoff_to_support.

❌ Look up the end user’s order using @get_order_details. Next, if found, confirm the item and shipping status.

Include Additional guidelines for general instructions

Not every instruction fits neatly in a step-by-step format. Use an Additional guidelines section for general instructions or important guardrails, such as:

• Tone and formatting expectations specific to this Playbook
• What not to do, or boundaries that shouldn’t be crossed
• How to handle edge cases
• What to say when unsure

Example:

Use Custom Instructions carefully

Custom Instructions influence how the AI Agent interprets and executes a Playbook. Avoid referencing handoffs in Custom Instructions unless a handoff is explicitly intended. Language that suggests handing off can override the expected Playbook flow, causing the AI Agent to handoff prematurely instead of continuing through the intended steps.

Best practices for Playbooks in Voice

Optimizing Playbooks for Voice ensures smooth, natural conversations.

Avoid duplicate acknowledgments

Your Voice AI Agent automatically provides quick acknowledgment messages to users before entering a Playbook and after most user responses during it. For example, if a user asks to check their order status, your AI Agent will automatically acknowledge the user (“Let me look into the steps to check your order status.”) before entering the Playbook. If you then ask the user to provide their order number, your AI Agent will automatically acknowledge that they heard the number after the user responds (“Thanks for that.”).

If you provide instructions inside your Playbook for your AI Agent to acknowledge what a user said, make sure you take some time to understand the end user experience—you don’t want your AI Agent to sound like it’s repeating itself.

Example:

✅ “Inform the user that you’ll need to validate their identity before you can provide their account balance.”

Then: “Use the Verify User Identity Action to confirm their identity.”

❌ “Acknowledge that the user wants to check their balance.”

Then “Inform the user that you’ll need to validate their identity before you can provide their account balance.”

Then: “Use the Verify User Identity Action to confirm their identity.”

Avoid multiple backend steps without a user message

Setting a variable, running an Action, or performing another backend operation takes your AI Agent time to complete. To prevent silent gaps as your AI Agent executes multiple backend steps in a Playbook, provide the user with a short, spoken message that informs the user of what the AI Agent is doing.

Example:

✅ “Let the user know that you need a second to pull up their account information, but that you’ll be right back with them.”

“Use the Get Transactions Action to retrieve a list of their most recent transactions.”

“Set the entered_transactions_playbook variable to true.”

“Review the user’s most recent transactions and identify any declined transactions.”

❌ “Use the Get Transactions Action to retrieve a list of their most recent transactions.”

“Set the entered_transactions_playbook variable to true.”

“Review the user’s most recent transactions and identify any declined transactions.”

Optimize for spoken responses

Your Voice AI Agent reads responses out loud. Add instructions to optimize how responses are spoken:

• Provide instructions about how your AI Agent should speak information returned by API calls and provide examples. For example: “Provide the user with the orders associated with their email without using numbers or bullet points, and instead use prose and full sentences. Phrase it like this: ‘I found three orders associated with your email address. The first is a [order item 1]. The second is a [order item 2], and the third is an [order item 3]. Which item are you looking to return?’”
• Instruct the AI Agent about how you want it to spell out dates (for example, replace “06/30/2025” with “June thirtieth, twenty twenty-five”).
• Instruct the AI Agent about how you want it to spell out email addresses (for example, replace “mark.tilvey87@yahoo.com” with “mark dot tilvey eighty seven at yahoo dot com”).

End with a natural closing

Never leave Voice users hanging. End Playbooks with a clear question before exiting a Playbook.

Example:

✅ “After you provide the user with their account balance, ask them if they need help with anything else today and exit Playbook.”

❌ “After you provide the user with their account balance, exit Playbook.”

Keeping Playbooks up to date

Before publishing and over time, make sure your Playbooks stay clear, correct, and useful. Use this checklist before publishing, and review them regularly to keep them accurate.

Review before publishing

Maintain and update regularly

Your product and end user needs evolve, and your Playbooks should too. Treat them as living documents and make sure they stay useful with regular upkeep.