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.

Distinguish `ASK` from `SEND`

ASK and SEND both communicate with end users, but they work differently:

SEND delivers information and moves on — the Agent does not wait for a response. Use it for status updates, instructions, and confirmations.
ASK collects a value from the end user. By default (only_when_needed), the Agent first checks whether the value is already available in the conversation — if so, it extracts the value silently without prompting. If the value is missing, the Agent asks the end user. Set “when to ask” to always to skip extraction and always prompt.

Scenario	Step type	Why
Collect the end user’s email address	`ASK`	The Agent needs the email before it can proceed.
Confirm the end user’s shipping address	`ASK`	The Agent waits for confirmation (“Yes, that’s correct”).
Present plan options and ask which one the end user prefers	`ASK` (with accepted values)	The Agent presents choices and waits for a selection.
Inform the end user that their refund has been processed	`SEND`	No response is needed — the Agent is delivering a status update.
Share troubleshooting steps for the end user to follow	`SEND`	The Agent provides instructions and moves on.

When using ASK to present options, add accepted values to constrain the expected responses. For example, if asking “Would you like a refund or a replacement?”, set the accepted values to “refund” and “replacement” so the Agent can reliably interpret the end user’s choice.

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 redirects the flow to a specific step. It is commonly used for jumps and loops, but it can also serve a simpler purpose: confirming that the flow should proceed to the next step.

Without a GO TO, the Playbook automatically advances to the next step when the current one completes. Adding a GO TO that points to the next step is functionally equivalent, but makes the intended flow explicit — which improves auditability in complex branching Playbooks.

When GO TO is purely a confirmation (no looping risk):

At the end of an IF/ELSE branch, pointing to the step that follows the conditional block.
After a SEND or ASK step, confirming the next step in a linear flow.

When GO TO introduces a looping risk:

Pointing back to an earlier step. This creates a loop — the Agent repeats that step and everything after it. Use this intentionally for retry patterns, but always pair with an IF/ELSE condition that provides an exit path.

Example — using GO TO at the end of every IF/ELSE branch for auditability:

IF order is shipped → SEND tracking number → GO TO Step 3.
ELSE IF order is processing → SEND estimated delivery date → GO TO Step 3.
ELSE order is canceled → SEND apology and alternatives → GO TO Step 4.

You do not need a GO TO at the end of every step. Use it when you want to make the intended flow explicit — especially in Playbooks with complex branching — or when you need to skip steps or loop back.

Understand when `SET` is needed after `RUN`

When a RUN step executes an Action, any outputs configured in the Action’s output settings are automatically saved to their target variables — no additional SET step is required.

A SET step after RUN is only needed when you want to:

Transform an output value (for example, extract part of a response or reformat a date).
Rename an output to a different variable (for example, save the Action’s order_status output to a variable named current_status).
Derive a new value based on the output (for example, set is_eligible to “true” if the returned order total exceeds a threshold).

If you only need the Action’s output as-is, the variable is already available after the RUN step completes. You can branch on any auto-set output variable in a downstream IF/ELSE step — including the HTTP status code — without an intermediate SET.

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.