> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbooks Overview

> Flexible, AI-driven procedures for your agents

Runbooks are natural-language instructions that guide your agents through conversations while allowing them to adapt to unique situations.

{/* Screenshot: Runbooks page showing runbook cards with names and agent usage counts */}

## What is a Runbook?

A runbook is a set of instructions written in plain language that tells your agent how to handle conversations. Unlike rigid scripts, runbooks give agents flexibility to adapt while following a general procedure.

**Example:**

> When a customer asks about refunds:
>
> 1. Acknowledge their request and express understanding
> 2. Ask for their order number if not provided
> 3. Look up the order using the Order Search tool
> 4. Check if the order is within the 30-day refund window
> 5. If eligible, process the refund and confirm the timeline
> 6. If not eligible, explain the policy kindly and offer alternatives
> 7. Ask if there's anything else you can help with

The agent follows this structure but adapts its language and approach based on the specific conversation.

## When to Use Runbooks

Runbooks are ideal when:

| Situation           | Why Runbooks Work                                          |
| ------------------- | ---------------------------------------------------------- |
| Conversations vary  | AI adapts to different phrasings, contexts, and edge cases |
| Judgment is needed  | Agent can make decisions within guidelines                 |
| Flexibility matters | Not every conversation follows the exact same path         |
| Quick iteration     | Easy to update instructions without rebuilding             |

## Runbook Structure

A good runbook includes:

### Objective

What the runbook should accomplish:

> **Objective:** Help customers with password reset requests while maintaining account security.

### Steps

Sequential instructions to follow:

> 1. Greet the customer and confirm their request
> 2. Verify identity by asking for their registered email
> 3. Check account status using the Account Lookup tool
> 4. ...

### Tool References

Links to specific tools when actions are needed:

> Use the **\[Password Reset Tool]** to send the reset email.

### Conditional Guidance

Instructions for different scenarios:

> If the account is locked, escalate to the security team.
> If the customer can't access their email, offer alternative verification.

### Snippets

Reusable instruction blocks included from your snippet library:

> Insert the **Verify Customer Identity** snippet from the editor's `@` menu.

## Runbooks vs Workflows

| Aspect           | Runbooks                        | Workflows                      |
| ---------------- | ------------------------------- | ------------------------------ |
| **Format**       | Natural language                | Visual graph                   |
| **Flexibility**  | High — AI interprets and adapts | Low — follows exact paths      |
| **Best for**     | Judgment-based processes        | Strict, repeatable processes   |
| **Complexity**   | Easy to write and update        | More setup, but visual clarity |
| **Auditability** | AI reasoning is logged          | Exact path is traceable        |

**Choose runbooks when:**

* The conversation could go many directions
* You want AI to handle edge cases intelligently
* Instructions are easier to write than flowcharts

**Choose workflows when:**

* Every step must happen in exact order
* Compliance requires deterministic execution
* Multiple tools must coordinate precisely

## Example Runbooks

### Customer Support Runbook

```
## Objective
Help customers resolve their issues efficiently while maintaining a friendly, professional tone.

## Steps
1. Greet the customer and acknowledge their question
2. Search the knowledge base for relevant information
3. If the answer is found, provide a clear, helpful response
4. If more information is needed, ask clarifying questions
5. If the issue requires action, use the appropriate tool
6. Confirm the resolution and ask if there's anything else
7. Close with a friendly sign-off

## Escalation
Escalate to a human agent if:
- The customer is upset and asks to speak to a person
- The issue involves account security or legal matters
- You cannot find relevant information after 2 searches
```

### Order Inquiry Runbook

```
## Objective
Help customers get information about their orders quickly.

## Steps
1. Ask for the order number if not provided
2. Use [Order Lookup Tool] to find the order
3. Provide the relevant information:
   - For status questions: Share current status and expected timeline
   - For shipping questions: Provide tracking information
   - For modification requests: Explain what's possible based on status
4. If the order cannot be found, verify the order number and check alternatives
5. Offer additional assistance

## When to Escalate
- Customer wants to cancel an order that's already shipped
- Order shows an error state
- Customer disputes the order details
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Runbook" icon="plus" href="/runbooks/creating-runbooks">
    Build your first runbook
  </Card>

  <Card title="Snippets" icon="puzzle-piece" href="/runbooks/snippets">
    Create reusable instruction blocks
  </Card>

  <Card title="Compare to Workflows" icon="diagram-project" href="/workflows/overview">
    Understand when to use each
  </Card>
</CardGroup>