Best practices

General guidelines

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

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”).

Example:

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, and Variables

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

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.

Example:

✅ Step 3: Retrieve the customers order

• Use @get_order_details to retrieve the customer’s order
• If orders are returned, confirm the item and shipping status with the end user.
• If no data is returned, ask the customer 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 customer 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 customer’s inquiry. You can leverage JMESPath in the Action Output settings to filter out unnecessary fields.

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 customer 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 @countryis Canada, inform them that the refund will take 3-5 business days.
• If the user’s @countryis neither Canada nor the US, inform them that the refund will take 7-14 business days.

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

Communicating your procedure

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 customer for their phone number:

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

❌ Ask the customer 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 customer’s order using @get_order_details.

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

❌ Look up the customer’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:

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 customer needs evolve, and your Playbooks should too. Treat them as living documents and make sure they stay useful with regular upkeep.