Configure

Every Playbook has a description, availability rules, one or more sections containing steps, and general guidelines. Playbooks can also be assigned to conversation start events so they run automatically when a conversation begins on a specific channel. The Playbook editor includes a side panel with four panes, accessible via the icon rail on the right side of the editor.

Runtime harness

While a Playbook runs, the AI Agent continuously monitors the conversation and can intervene automatically — without requiring explicit steps in the Playbook. This built-in behavior ensures Playbooks stay responsive to end user needs even when the conversation takes an unexpected turn.

• Intent change detection: If the Agent detects that the end user’s intent has shifted away from the current Playbook, it exits the Playbook and routes the conversation appropriately.
• Pause and resume for Knowledge search: When the Agent determines that a Knowledge search would help answer the end user’s question, it temporarily pauses Playbook execution, performs a Q&A search (the same search your AI Agent uses outside of Playbooks), and then resumes where it left off.
• Escalation and exit: The Agent can escalate to a human agent or exit the Playbook entirely based on end user input, even if no explicit Handoff or Exit step is configured at that point in the flow.

Side panes

Playbook Details

The Details pane controls the Playbook’s description, usage scope, and access rules.

• When to use this Playbook: Describes the situations where the Playbook is appropriate, much like how you would explain its use to a human agent. This is the primary signal the Agent uses when selecting which Playbook to run.

• Usage: Check Only available within other Playbooks to prevent the Playbook from triggering on its own. When checked, the AI Agent only uses this Playbook inside another Playbook, not on its own. Use this for child Playbooks that exist solely to support a parent.

• Availability rules: Restrict which end users can access this Playbook based on variable conditions. Set to Everyone or configure rules using the following operators:

  Operator	Description
  Is	Exact match.
  Is not	Does not match.
  Starts with	Value begins with the specified text.
  Ends with	Value ends with the specified text.
  Contains	Value appears anywhere.
  Does not contain	Value does not appear.
  Is set	Variable has a value.
  Is not set	Variable has no value.

Conversation start events

A conversation start event triggers a Playbook automatically when a new conversation begins on a specific channel. Instead of relying on intent matching from the description, the Playbook runs immediately as the first response on that channel.

The available events depend on which channels are configured. Messaging and Voice events are always available. Other events appear when the corresponding channel is configured.

To assign a conversation start event to a Playbook:

1. Open the Playbook editor and select the Details pane.
2. In the When to use this Playbook field, type @.
3. Select a conversation start event from the dropdown. Events already assigned to another Playbook are greyed out. The selected event appears as a pill above the description field.
4. Save the Playbook.

A Playbook can have multiple conversation start events assigned — for example, both Messaging and Voice — so it runs at the start of conversations on all assigned channels. Each event can only be assigned to one Playbook at a time.

What happens to Greetings: Messaging and Voice channels use a Greeting as their default conversation opener. When a conversation start event for one of these channels is assigned to a Playbook, the Playbook replaces the Greeting for that channel. The Greeting page shows which events currently trigger the Greeting and which have been reassigned to a Playbook. To revert a channel to using the Greeting, remove the event from the Playbook.

Social channels and Email do not have Greetings, so assigning a conversation start event to a Playbook on these channels sets the Playbook as the first response — there is no Greeting to fall back to.

Greeting-first vs. user-message-first channels: On Messaging and Voice, the AI Agent speaks first — the Playbook fires before the end user sends a message. On social channels and Email, the end user sends a message before the conversation start event fires. In this case, the Playbook has access to the end user’s first message and can reason about their intent when generating responses. If the Playbook is not designed to address the original intent, that intent is stashed and picked up after the Playbook completes, so the end user’s request is not lost.

Playbooks can also be linked to Proactive Conversations so they run when an end user engages with a proactive message.

Simulations support conversation start events — when a Playbook has an event assigned, simulations trigger that Playbook at the start of the conversation, matching production behavior.

General Guidelines

The General Guidelines pane is a rich text editor for instructions that apply to all end user interactions in the Playbook. Type @ to reference API tools, Handoffs, Variables, Playbooks, Knowledge articles, and Exit.

The editor supports headings (H1, H2), bold text, bulleted lists, and numbered lists. Use it for:

• Tone and formatting specific to this Playbook.
• Guardrails and boundaries — what the Agent should and should not do.
• Knowledge references — reference articles using @ArticleName mentions or instruct the Agent to search the knowledge base.
• Linked Playbook references — call a linked Playbook from any point in the conversation without tying it to a specific step (for example, “If the end user needs to verify their identity, use @Verify Identity”).
• Edge case handling — fallback behavior for unexpected situations.

General Guidelines are stateless — they apply throughout the entire conversation regardless of which step the Agent is currently on. This makes them ideal for cross-cutting rules that should not be embedded in any single step or section.

Good General Guidelines content:

• “Always verify the end user’s identity before sharing account-specific information.”
• “Never offer a refund greater than the original order value.”
• “If the end user asks about a topic not covered by this Playbook, search the knowledge base before handing off.”
• “Use a friendly, professional tone. Avoid jargon.”

Poor General Guidelines content:

• Step-specific instructions that belong in a particular step (for example, “In Step 3, ask for the order number” — write this directly in Step 3 instead).
• Long, detailed procedures — structure these as steps within a section instead.
• Guidance that only applies in one branch of the flow — place this in the relevant IF/ELSE branch instead.

Steps

The Steps pane provides a navigable outline of all sections and steps in the Playbook. Each row displays the step number, keyword (SEND, SET, RUN, etc.), and a preview of the step’s target — such as the API tool name for a RUN step or the variable name for a SET step.

Click any row to scroll directly to that step in the editor.

Variables

The Variables pane displays all variables referenced in the Playbook. Each variable row shows a reference count. Click a variable to expand it and see every step that reads or writes it, listed by step number and keyword.

Build your Playbook with sections and steps

The body of a Playbook is organized into sections and steps.

Sections

Sections represent stages of the end user journey — for example, “Verify identity”, “Look up order”, or “Process refund”. Each section contains a sequence of steps that execute in order.

• Add sections to group related steps and make the workflow easier to read.
• Sections execute in order unless redirected by an IF/ELSE branch or GO TO jump.
• GO TO can jump to steps in other sections, enabling cross-section flows.

Steps

Within each section, add steps to define what the AI Agent does. The six step types are:

For complete field-level documentation, including modes, validation rules, and examples for each step type, see Step reference.

To add a step:

1. In a section, click Add Step.
2. Select a step type.
3. Configure the step’s fields (for example, the message content for a SEND step, or the variable and instruction for an ASK step).
4. Click the step icon to open that step’s configuration in the side pane. Applies to ASK, SEND, and SET.

Reference API tools, Handoffs, Exits, and Variables

Playbooks connect to external systems and end user data through references to API tools, Handoffs, Exits, and Variables.

API tools and Handoffs

In any step that supports references, type @ to search for existing API tools and Handoffs. Select one to insert a reference. If no results appear, click + Create API tool or + Create Handoff to define a new item without leaving the editor.

Use RUN steps to execute API tools (API calls) and trigger Handoffs (escalation to human agents) at specific points in the workflow.

Exits

Use a RUN step with the Exit option to deterministically end a Playbook. Type @Exit to find the Exit Playbook option in the reference menu — it appears in the same reference dropdown shown above.

Variables

Playbooks support Global Variables, Sensitive Variables, and Metavariables. Reference variables in any step to personalize the flow.

• Reading: Reference a variable to shape logic (for example, check @order_status in an IF/ELSE branch). Metavariables are read-only.
• Writing: SET and ASK steps write to Global Variables and Sensitive Variables. Variables cannot be written from General Guidelines.

Knowledge

Playbooks can reference Knowledge sources — including third-party knowledge bases, Ada-created articles, and web-scraped content.

• Direct reference: Use @ArticleName in General Guidelines to reference a specific article.
• Native search: The runtime harness can pause Playbook execution to perform a Knowledge search when it detects the end user needs information, then resume where it left off. You can also add natural-language search instructions in General Guidelines to guide this behavior.

Link a Playbook

Break large workflows into smaller, reusable components by linking Playbooks together.

Version compatibility

Linked Playbooks must be of the same version. A Playbook cannot link to a Playbook (Classic), and a Playbook (Classic) cannot link to a Playbook. If you are migrating from Classic, update all Playbooks in a linked chain together so that parent and child Playbooks are on the same version.

How linking works

Linked Playbooks use call-and-return logic: the parent calls a child via a RUN step, the child runs to completion, then control automatically returns to the parent. The child does not branch — it always returns to the exact point in the parent where it was called.

How to link

Use a RUN step with the linked Playbook option. The parent pauses while the child runs, then continues once the child exits.

• You can link multiple Playbooks within a single parent with no limit on how many a parent may call.
• Treat the top-level Playbook as the parent and all linked Playbooks as children.
• Keep child Playbooks focused on a single, structured task to ensure they remain reusable.

Restrict child Playbooks

When a Playbook exists only to support another — meaning it should never trigger on its own — enable AI Agent can only use this Playbook within other Playbooks in the Playbook Details pane. This prevents accidental triggering and reduces misfires.