> ## 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.

# Creating Runbooks

> Build effective runbooks for your agents

This guide walks you through creating runbooks that guide your agents effectively.

## Creating a New Runbook

**1. Navigate to Runbooks**

Go to **Build → Runbooks** in your dashboard.

**2. Click Create Runbook**

Click **Create Runbook** to open the editor.

**3. Name Your Runbook**

Give it a clear, descriptive name:

* Good: "Password Reset Procedure", "Refund Request Handler"
* Avoid: "Runbook 1", "Support"

**4. Write Your Instructions**

Use the editor to write your runbook content.

**5. Save**

Click **Save** to save your runbook.

## Writing Effective Instructions

### Start with an Objective

Begin with a clear statement of what the runbook should accomplish:

```
## Objective
Help customers reset their passwords securely while providing a smooth experience.
```

This focuses the agent on the goal, not just the steps.

### Write Clear Steps

Use numbered steps for the main procedure:

```
## Steps
1. Greet the customer and confirm they need password help
2. Ask for their registered email address
3. Look up the account using [Account Search]
4. Verify identity by asking security question
5. Send password reset email using [Password Reset Tool]
6. Confirm the email was sent and explain next steps
```

**Tips:**

* Use action verbs: "Ask", "Check", "Use", "Explain"
* Be specific but not over-prescriptive
* Include what information to gather

### Add Conditional Guidance

Handle different scenarios:

```
## Handling Different Situations

### If the account is not found
- Ask the customer to verify the email spelling
- Check for common typos (gmail vs gmal, etc.)
- If still not found, offer to help create an account

### If the account is locked
- Explain that the account has security restrictions
- Escalate to the security team with context
- Provide the customer with an expected timeline

### If the customer can't access their email
- Offer alternative verification (phone, security questions)
- If alternatives fail, escalate to account recovery team
```

### Reference Tools

Embed tool references when the agent should take action:

```
Use the **[Order Lookup]** tool to find the customer's order.
```

The agent will know to call that specific tool at this step.

### Include Snippets

Insert reusable snippets for common procedures:

```
Type @, choose Snippets, and select "Verify Customer Identity".

Once verified, proceed with the password reset.
```

### Define Escalation Criteria

Be explicit about when to escalate:

```
## When to Escalate
- Customer explicitly asks to speak with a human
- Issue involves legal or compliance questions
- Customer has been unable to resolve after 3 attempts
- Sensitive account security concerns
```

## Runbook Template

Use this structure as a starting point:

```markdown theme={null}
## Objective
[What should this runbook accomplish?]

## Before You Start
[Any context the agent should know]

## Steps
1. [First action]
2. [Second action]
3. [Third action]
...

## Handling Variations

### If [scenario A]
[How to handle]

### If [scenario B]
[How to handle]

## Tools Used
- [Tool 1] — [When to use it]
- [Tool 2] — [When to use it]

## Escalation Criteria
- [Condition 1]
- [Condition 2]

## Closing
[How to wrap up the conversation]
```

## Testing Your Runbook

Before assigning to an agent, test it:

**1. Create a Test Agent**

Create an agent using this runbook (or update an existing one).

**2. Open Playground**

Go to **Test → Playground** and select the agent.

**3. Run Test Scenarios**

Try different conversation paths:

* Happy path (everything works)
* Error cases (account not found, etc.)
* Edge cases (unusual requests)
* Escalation triggers

**4. Review Execution**

Check the execution steps to see how the agent interpreted your instructions.

**5. Iterate**

Update the runbook based on what you observe.

## Best Practices

### Do

* **Be specific about goals** — Clear objectives help the agent make good decisions
* **Use natural language** — Write like you're training a human teammate
* **Cover edge cases** — Think about what could go wrong
* **Include examples** — Show what good responses look like
* **Test thoroughly** — Try many scenarios before deploying

### Don't

* **Don't over-prescribe** — Leave room for the AI to adapt
* **Don't assume context** — Be explicit about what information to gather
* **Don't forget escalation** — Always define when to hand off
* **Don't skip testing** — Real conversations will surprise you

## Next Steps

> [card] [Snippets](https://docs.duckie.ai/runbooks/snippets.md)
>
> Create reusable instruction blocks

> [card] [Tools](https://docs.duckie.ai/tools/overview.md)
>
> Learn about available tools

> [card] [Test Your Runbook](https://docs.duckie.ai/testing/playground.md)
>
> Validate in the playground


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.