> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/automation/playbooks/best-practices/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# 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](/docs/automation/playbooks/get-started#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.                    |

> **Tip**
>
> 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:

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

> **Tip**
>
> 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 API tool, any outputs configured in the API tool'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 API tool'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 API tool'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 API tool error handling

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

1. `RUN` the API tool.
2. `SET` the HTTP status code to a variable.
3. `IF/ELSE` to check the status code.
4. 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, API tools, Handoffs, and Variables are visible to the AI Agent. Clear names improve routing accuracy and reduce misfires.

| What            | Good                       | Not good      |
| :-------------- | :------------------------- | :------------ |
| API tool name   | `@issue_order_refund`      | `@action_ior` |
| API tool input  | `@order_id`                | `@id`         |
| API tool output | `Customer's date of birth` | `DOBC`        |

> **Note**
>
> API tool 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.

> **Warning**
>
> 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.
* **`SEND` steps**: Add **Search Knowledge** when the answer depends on what the end user asks. Name the topic in the instruction to narrow the search. Reference an article when you know which article answers the step. See [Search Knowledge in `SEND` steps](/docs/automation/playbooks/step-reference#search-knowledge-in-send-steps).
* **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](/docs/automation/playbooks/configure#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.

> **Note**
>
> 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 API tool 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 API tools regularly to ensure APIs have not changed.
* Check linked Playbook dependencies before making structural changes.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).