Best practices

Overview

Effective Playbooks guide your AI Agent through complex workflows with clear, well-structured steps. These best practices help you build Playbooks that are reliable, easy to maintain, and produce consistent end user experiences.

General guidelines

Follow these guidelines when creating and maintaining Playbooks.

Let Ada create a first draft

The Generate a Playbook feature creates a first draft from a simple prompt or an existing PDF file. To get the best results, clearly define your goal and the scenario you want the Playbook to address. Starting this way helps you understand how to structure sections and steps effectively.

Peer review your Playbooks

As the author, you might overlook missing branches or unclear step configurations. Having someone with limited context review your Playbook helps identify gaps — especially in IF/ELSE conditions and fallback paths.

Keep sections focused

Each section should represent a single stage of the end user journey. Avoid combining unrelated steps in one section. Clear section boundaries make Playbooks easier to read, test, and maintain.

Working with steps

Select the right step type for each action and configure modes, accepted values, and fallbacks to ensure reliable execution.

Choose the right step type

When you need to…	Use
Send a fixed message to the end user	`SEND` — Fixed message mode
Send a contextual, AI-generated response	`SEND` — Contextual AI-generated mode
Set a variable to a known value	`SET` — Exact value mode
Silently extract a value from the conversation	`SET` — Use reasoning mode
Capture direct input from the end user	`ASK` — Capture exact response mode
Interpret the end user’s response using AI	`ASK` — Map using reasoning mode
Call an API, trigger a handoff, run a linked Playbook, or exit	`RUN` — Deterministic only
Branch based on a condition	`IF/ELSE` — Deterministic only
Jump to another step	`GO TO` — Deterministic only

Distinguish `SET` from `ASK`

SET and ASK both write to variables, but they work differently:

SET is silent — it never prompts the end user. Use Exact value mode for known values and Use reasoning mode to extract information from the conversation without asking.
ASK prompts the end user. Use it when you need direct input.

If you find yourself writing a Use reasoning SET instruction like “ask the customer for their order number” — use an ASK step instead. SET extracts; ASK collects.

Use accepted values and fallbacks

When a Use reasoning SET or ASK step feeds into a downstream IF/ELSE branch:

Set accepted values to constrain extraction to a known set. This prevents unexpected values from breaking your conditional logic.
Set a fallback value (Use reasoning SET) to ensure the variable always has a value downstream. An unset variable can cause IF/ELSE branches to fall through unexpectedly.

Cover every `IF/ELSE` branch

Every IF/ELSE step should account for all possible outcomes:

Always include a fallback (else/default) branch. Think about edge cases — what happens when the input is unexpected or a variable is missing?
Consider what happens when a variable is not set — add an “Is Not Set” condition if needed.
Avoid deeply nested conditions. Flatten complex logic using multi-group conditions (nested AND/OR) instead of nesting IF/ELSE steps inside each other.

Use `GO TO` carefully

GO TO is powerful but can make Playbooks harder to follow:

Always pair GO TO with an IF/ELSE condition that provides an exit path to prevent infinite loops.
Prefer forward jumps (skipping ahead) over backward jumps (loops) when possible.
Use GO TO for retry patterns — for example, re-asking after invalid input — but limit retries to avoid frustrating end users.

Build action error handling

When a Playbook depends on an Action succeeding, build an explicit error path:

RUN the Action.
SET the HTTP status code to a variable.
IF/ELSE to check the status code.
In the error branch, SEND a helpful message and either retry, hand off, or exit gracefully.

Explicit error branches give end users a better experience and more control over fallback behavior.

Working with references

Use clear naming, explicit exits, and structured Knowledge references to keep Playbooks predictable and maintainable.

Use intuitive names and descriptions

Names and descriptions of Playbooks, Actions, Handoffs, and Variables are visible to the AI Agent. Clear names improve routing accuracy and reduce misfires.

What	Good	Not good
Action name	`@issue_order_refund`	`@action_ior`
Action input	`@order_id`	`@id`
Action output	`Customer's date of birth`	`DOBC`

Action names longer than 64 characters can cause errors and fallbacks. Keep names short.

Use explicit Exits

Always end your Playbooks with an explicit Exit. Every flow should have a clear termination point to ensure predictable behavior. Use a RUN step with the Exit option at each endpoint in the workflow.

Do not rely on the Playbook ending automatically. Always configure explicit exits for every completion path in the flow.

Reference Knowledge effectively

Reference Knowledge through:

General Guidelines: Use @ArticleName mentions or natural-language search instructions.
Availability rules: Scope which articles are available to specific Playbooks via the Knowledge page.
Runtime harness: The runtime harness can automatically pause execution to perform Knowledge searches when the end user asks a question. See Runtime harness.

Voice-specific best practices

Playbooks on Voice channels require adjustments for spoken delivery and real-time pacing.

Avoid duplicate acknowledgments

The Voice AI Agent automatically acknowledges end user responses before and during Playbook execution. Avoid SEND steps that duplicate these acknowledgments — the end user experience should not feel repetitive.

Acknowledgment messages on Voice will be configurable in a future release.

Optimize for spoken responses

Instruct the Agent to speak API responses in prose, not lists.
Specify how to read dates and email addresses aloud.
End every Voice Playbook with a clear question before exiting (for example, “Is there anything else I can help you with?”).

Testing and maintenance

Thorough testing and regular maintenance keep Playbooks reliable as products and processes change.

Test before publishing

Check	Details
Walk through common flows	Verify the happy path works end to end.
Test edge cases	Missing inputs, unexpected values, alternate branches.
Verify `IF/ELSE` coverage	Confirm every branch leads to a valid outcome.
Test Action failures	Simulate 4xx/5xx responses to verify error handling.
Check variable flow	Ensure `SET` and `ASK` steps write values that downstream steps can read.
Review from different user types	Test with different variable values to exercise availability rules.

Maintain and update regularly

Review Playbooks periodically as products and processes change.
Delete or deactivate outdated Playbooks.
Test Actions regularly to ensure APIs have not changed.
Check linked Playbook dependencies before making structural changes.