Playbook management

Playbooks are structured, natural-language instructions that teach AI Agents to handle complex, multi-step inquiries. Like internal standard operating procedures (SOPs) for human agents, they guide AI to interpret and act in real time, using context to decide what to do next.

Traditional bots can’t handle this—they break when processes change. Playbooks close that gap, enabling AI Agents to follow your procedures with logic and adaptability. This unlocks automation for complex workflows, reduces reliance on human agents, and drives significant cost savings.

Overview

Playbooks provide AI Agents with clear, step-by-step guidance for managing complex customer interactions. AI Managers can create them using structured lists that resemble traditional operating instructions, which AI Agents are expected to follow sequentially. Sections can also be added to organize and clarify the workflow.

The following examples illustrate how a Playbook is configured and how that configuration is experienced by customers during a live interaction.

Playbook configuration example

This configuration shows how an AI Manager structures a Playbook. Each step defines a specific action or message that the AI Agent will deliver, creating a clear and consistent workflow for managing customer interactions.

Playbook configuration example

Customer experience example

Here, the Playbook is shown from the customer’s perspective during a live interaction. The AI Agent presents the content according to the defined steps, guiding the customer through the interaction in a structured and coherent way.

Customer experience example

Limitations

While Playbooks offer powerful capabilities, it’s important to be aware of their current limitations:

  • Not supported on Ada Voice: Playbooks currently only work with Messaging and Email channels.

  • Limited Coaching support: While you can coach the AI Agent on when and which Playbook to use, Coaching is not considered once the AI Agent is executing a Playbook. Additionally, you cannot currently coach individual steps or messages taken during a Playbook. To adjust the AI Agent’s behaviour in these cases, edit the Playbook directly.

  • Limited knowledge access: The AI Agent currently cannot initiate a search for knowledge articles while using a Playbook. If relevant knowledge would be helpful, consider incorporating it directly into the Playbook content.

Being aware of these limitations helps ensure realistic expectations and supports better use of Playbooks in your workflows.

Use cases

Playbooks can be used across a variety of scenarios. The following examples demonstrate how they support AI Agents in practice:

  • Problem Resolution: Focused on troubleshooting issues and handling complaints.
    • Examples: Tracking an order, replacing a lost or stolen card.
  • Processing Requests: Assisting customers with straightforward tasks.
    • Examples: Updating an address, upgrading an account.
  • Gathering Information: Collecting details from customers to support follow-up actions.
    • Examples: Qualifying leads, capturing customer preferences.
  • Security & Verification: Confirming user identity before making sensitive changes.
    • Examples: Authentication flows, investigating potential fraud.

Capabilities

Designed to support complex workflows, the following capabilities can help AI Agents to handle interactions with structure, flexibility, and consistency:

  • Instruct the AI Agent with natural language: Playbooks provide structured, natural-language instructions that guide the AI agent through each step of a process, similar to how a human agent would follow operating procedures.
  • Reference Actions and Handoffs: Playbooks can incorporate references to specific Actions (like API calls) and Handoff flows, allowing the AI Agent to seamlessly perform tasks and escalate conversations to a human agent when needed.
  • Reference Global and Metavariables: Playbooks support referencing both Global variables and Metavariables, and also allow writing to Global variables. This enables AI Agents to make decisions and update values dynamically based on specific conditions. For example, an AI Agent could check if an order status matches a certain value and take a corresponding action, or update a Global variable if a customer indicates they meet certain criteria.
  • Multi-channel support: Playbooks are supported on both Messaging and Email channels, ensuring consistent, high-quality interactions across communication modes.

Quick start

Get started with creating your first Playbook by following these quick steps:

  1. Navigate to Training > Playbooks.

  2. Choose the Playbook generation method, then finalize the Playbook details.

Playbooks: Quick start

Create a Playbook

You can create a Playbook using one of three methods: Generate a Playbook, Import an existing procedure, or Start from scratch. Each method offers a different starting point depending on your needs.

No matter which method you choose, you’ll complete the process by finalizing Playbook details. This guide walks you through each creation method and the shared configuration steps.

Generate a Playbook

You can use AI to help you quickly create a Playbook by providing a short description of the task or procedure you want to automate. Select from a list of prompt suggestions or describe your own use case to generate the first draft of your Playbook. This is a great way to get started if you’re not sure how to structure your workflow or want a head start on writing.

Generate a Playbook

To generate a Playbook:

  1. On the Ada dashboard, go to Training > Playbooks.

  2. On the Playbooks page, in the top-right corner, click New Playbook.

  3. On the New Playbook page, describe the procedure you want your AI Agent to handle, or select from a list of common use cases.

  4. Review and update your Playbook, as needed. For more information, see Finalize Playbook details.

Import an existing procedure

If you already have an SOP—such as a customer support workflow saved as a PDF—you can import it directly into Ada to jump-start your Playbook. This method is helpful when migrating content from another tool or repurposing existing documentation. Once imported, the content is automatically converted into a Playbook that you can review, edit, and refine.

To import an existing procedure:

  1. On the Ada dashboard, go to Training > Playbooks.

  2. On the Playbooks page, in the top-right corner, click Import PDF.

  3. Select and upload your PDF file.

  4. Once the upload is successful, review and update your Playbook, as needed. For more information, see Finalize Playbook details.

Start from scratch

If you already know how you want your Playbook to work, you can build it manually from the ground up. This option gives you full control to define the structure, instructions, and logic that guide the AI Agent’s behavior—perfect for custom workflows or more advanced use cases.

Playbooks: Start from scratch

To start from scratch:

  1. On the Ada dashboard, go to Training > Playbooks.

  2. On the Playbooks page, in the top-right corner, click New Playbook.

  3. On the New Playbook page, in the top-right corner, click Start from scratch.

  4. Fill out the required fields, including the Playbook’s name, usage guidance, and instructions. Customize the content to fit your workflow. For more information, see Finalize Playbook details.

Finalize Playbook details

Name and describe your Playbook

Every Playbook begins with a name and a short description that explains when it should be used. These details provide important context to the AI Agent, helping it understand the purpose of the Playbook and when to apply it.

Playbooks: Start from scratch
  • The Playbook Name should be specific and clearly reflect what the Playbook is designed to handle—for example, Handle refund requests or Verify account details.

  • When to use this Playbook should outline the situations where the Playbook is appropriate, much like how you would explain its use to a human agent. This ensures the AI knows when it’s relevant to use this workflow during a conversation.

Control who can access your Playbook

If required, you can restrict Ada Playbooks to certain users, based on information your AI Agent collects about your users and saves in variables.

Playbook access
  • Under Availability, choose which customers you want the Playbook to apply to:

    • To make the Playbook available to all users, select Everyone.

    • To restrict the Playbook to certain users, select Based on the following rules. A section expands where you can enter the logic your AI Agent will use to decide whether to serve specific Playbooks.

      1. Under Where, in the Choose a variable list, select a variable.
      2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target.
      3. Comparison operators are logic statements that tell your AI Agent to match customer information that’s captured in the variable you’re using. The available operators vary based on the variable type you’re using:

        OperatorVariable typesDescription
        Begins With icon Begins With

        - All text variables (including phone and email)

        Match information in the variable that begins with certain text (partial match).
        Ends With icon Ends With

        - All text variables (including phone and email)

        Match information in the variable that ends with certain text (partial match).
        Contains icon Contains

        - All text variables (including phone and email)

        - List variables

        Match information in the variable that contains certain text in any position (partial match).
        Is icon Is

        - All text variables (including phone and email)

        - Number variables

        Match information in the variable that equals specific text exactly (exact match).
        Is Not icon Is Not

        - All text variables (including phone and email)

        - Number variables

        Match information in the variable that does not equal specific text exactly (exact match).
        Is Not Set icon Is Not Set

        - All text variables (including phone and email)

        - Number variables

        - List variables

        Match if there is no information contained in the variable.
        Is Set icon Is Set

        - All text variables (including phone and email)

        - Number variables

        - List variables

        Match if there is any information contained in the variable.
        Greater Than icon Greater Than

        - Number variables

        Match if the information in the variable is greater than a specific value.
        Less Than icon Less Than

        - Number variables

        - List variables

        Match if the information in the variable is less than a specific value.
        Is True icon Is True

        - Yes/No variables

        Match if the information in a variable is Yes (or True).
        Is False icon Is False

        - Yes/No variables

        Match if the information in a variable is No (or False).
        Does Not Contain icon Does Not Contain

        - List variables

        Match if none of the selected items contains this value.
        Is Equal To icon Is Equal To

        - List variables

        Match if the customer selected a particular number of options in a List Option block.
        Is Greater Than icon Is Greater Than

        - List variables

        Match if the customer selected more than a particular number of options in a List Option block.
        Is Less Than icon Is Less Than

        - List variables

        Match if the customer selected fewer than a particular number of options in a List Option block.
      4. In the Value field, enter or select a value for the variable that you want to use to target users.
      5. If required, add additional conditions.
        • To add a new top-level condition, click Add .

          If you’re adding your first additional top-level condition, in the dropdown that appears, choose And or Or as the operator for all of your top-level conditions.

        • To create or add to a group of conditions, click the Add to group icon beside a condition you want to include in the group.

          If you’re creating a group, in the dropdown that appears, choose And or Or as the operator for all of the conditions in that group.

Write your Playbook

A Playbook consists of structured instructions that guide the AI Agent through a specific workflow. Whether you generate a Playbook, import an existing procedure, or start from scratch, the goal is to create clear, structured guidance that mirrors how a human would handle the interaction.

Structure your workflow into sections

The body of a Playbook is organized into sections, each representing a stage of the customer journey. For example, a refund workflow might include sections like Verify customer and Process refund. Use second-level headings to clearly separate each part of the flow.

Within each section, outline the steps the AI Agent should follow using a numbered list. This ensures the process unfolds in the correct order. Keep the language simple and direct, like you’re explaining the task to a teammate—concise, clear, and actionable.

Use formatting to improve clarity

Formatting tools help make your Playbook easier to read and follow. Use bold to highlight key actions, bullet points for unordered lists, and links to provide supporting information or resources. Consistent formatting improves scannability and enhances the live interaction experience.

Quick reference

Here’s a quick reference for formatting options and editor commands.

Check out Best practices for some common examples and guidance.

IconPurpose
H1Top-level heading
H2Sub-heading
BoldBold text, for emphasizing important actions or terms
BulletsBulleted list, for items without a required order
NumbersNumbered list, for structured step-by-step instructions
LinksLinks

Reference Actions, Handoffs, and Variables

Playbooks can reference Actions, Handoffs, and Variables—to create dynamic, intelligent workflows. These elements allow your AI Agent not only to follow static instructions, but also to interact with external systems, personalize responses using customer data, and escalate conversations when necessary.

Actions and Handoffs

Playbooks support references to specific Actions, such as API calls, and Handoff flows that transfer the conversation to a human agent. Referencing these allows the AI Agent to perform real tasks—like fetching order status, submitting a return request, or initiating a live chat handoff—at the appropriate points in the flow.

When editing a Playbook, you can type @ to bring up a searchable menu of existing Actions and Handoffs. Selecting one inserts a reference directly into the Playbook, connecting the written instructions to the underlying logic.

Playbooks: Actions and Handoffs

If typing the name of an Action or Handoff doesn’t return any results, you can create a new entry directly from the menu. Just click + Create Action or + Create Handoff to define a new item without leaving the editor.

Playbooks: Create Actions and Handoffs
Global and Metavariables

Playbooks also support referencing Global Variables and Metavariables, enabling the AI Agent to personalize responses, control flow, or record important data points.

Variables can be used in conditionals to guide the Agent’s behavior. For example, a Playbook might check whether a variable like order_status is set to delivered and take a specific action based on that condition. Or it might listen for a customer to indicate they’re eligible for a discount and update a variable accordingly.

  • Reading variables: You can reference a variable to shape the logic of your Playbook. For example, use a customer’s email to look up their order and adjust the Agent’s next steps based on the result.

  • Writing to variables: Playbooks can write only to Global Variables. For instance, if a customer selects a credit card to reorder, that selection can be stored in a Global Variable. This allows the AI Agent to remember and reuse customer input later in the interaction.

Metavariables are read-only in Playbooks.

Just like with Actions and Handoffs, typing @ allows you to search and reference existing variables, or create new ones directly from the editor via + Create Variable.

Sensitive variables—used to temporarily store private user information like email addresses or account numbers—are not supported in Playbooks.

Test your Playbook

Before publishing, it’s important to thoroughly test how your Playbook behaves to ensure it performs as expected across a variety of situations.

Start by walking through the most common flows and expand your testing to cover edge cases—such as missing or unexpected inputs, customer confusion, or alternate paths through the workflow. Test from the perspective of different types of users to evaluate how the Playbook adapts based on context, permissions, or intent. Don’t forget to account for error states and fallback scenarios to ensure the experience remains smooth even when something goes wrong.

You can preview the Playbook in isolation using Test Playbook, or simulate a full conversation using Test AI Agent to confirm that it triggers under the right conditions. Note that Test AI Agent is only available for live Playbooks—inactive Playbooks can only be tested using the Test Playbook button. For more details on setup, see AI Agent testing.

To help guide your test coverage and approach, see Best practices and Use cases.

Test a Playbook

Manage Playbooks

After creating a Playbook, you can save, publish, duplicate, edit, or delete it—all from the Ada dashboard. These options give you full control over how your Playbooks are stored, maintained, and made available to your AI Agent. Save and publish

Playbooks can be saved in one of two states: inactive or active.

  • Saving as inactive keeps the Playbook in draft mode. It won’t be used by your AI Agent until you’re ready to publish.

  • Saving as active makes the Playbook immediately available in live customer interactions.

This flexibility allows you to work on Playbooks incrementally without affecting the customer experience.

Duplicate an existing Playbook

To reuse the structure or content of a Playbook, you can create a copy using the Duplicate option. This is useful for iterating on a workflow, experimenting with variations, or creating reusable templates.

Edit or delete a Playbook

To make changes or remove a Playbook, go to Training > Playbooks in the Ada dashboard and open the Playbook you want to manage.

You can:

  • Edit the content and choose to save it as active or inactive, depending on whether it should be live.

  • Delete the Playbook by selecting Delete Playbook from the More options menu at the top of the page.

Playbooks and Processes

Like Playbooks, Processes also use structured instructions for guiding AI Agents through multi-step workflow. But they serve different purposes based on the level of flexibility required.

  • Playbooks handle complex, dynamic inquiries where your Agent adapts based on input, context, or channel—using natural language and decision logic to pursue a goal.
  • Processes are for specific, structured interactions that require specific wording and flow using predefined blocks.

Choosing between a Playbook and a Process depends on the level of flexibility, context sensitivity, and risk associated with the interaction.

Default to a Playbook when:

  • The flow may change based on customer input or channel (e.g., product availability or troubleshooting).
  • You need to gather information or handle multiple paths to resolution.
  • Tone or wording should adapt based on context.
  • You want the AI Agent to follow a goal, not a strict script.

Use a Process when:

  • The response must be scripted word for word without variation.
  • It contains compliance-sensitive or legally approved language.
  • Any deviation could cause confusion or risk.