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

<Steps>
  <Step title="Navigate to Runbooks">
    Go to **Build → Runbooks** in your dashboard.

    {/* Screenshot: Runbooks page with Create Runbook button */}
  </Step>

  <Step title="Click Create Runbook">
    Click **Create Runbook** to open the editor.
  </Step>

  <Step title="Name Your Runbook">
    Give it a clear, descriptive name:

    * Good: "Password Reset Procedure", "Refund Request Handler"
    * Avoid: "Runbook 1", "Support"
  </Step>

  <Step title="Write Your Instructions">
    Use the editor to write your runbook content.

    {/* Screenshot: Runbook editor with rich text, tool references, and snippet insertion */}
  </Step>

  <Step title="Save">
    Click **Save** to save your runbook.
  </Step>
</Steps>

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

{/* Screenshot: Tool reference insertion UI in the runbook editor */}

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

{/* Screenshot: Snippet insertion dropdown in the runbook editor */}

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

<Steps>
  <Step title="Create a Test Agent">
    Create an agent using this runbook (or update an existing one).
  </Step>

  <Step title="Open Playground">
    Go to **Test → Playground** and select the agent.
  </Step>

  <Step title="Run Test Scenarios">
    Try different conversation paths:

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

  <Step title="Review Execution">
    Check the execution steps to see how the agent interpreted your instructions.
  </Step>

  <Step title="Iterate">
    Update the runbook based on what you observe.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="Snippets" icon="puzzle-piece" href="/runbooks/snippets">
    Create reusable instruction blocks
  </Card>

  <Card title="Tools" icon="wrench" href="/tools/overview">
    Learn about available tools
  </Card>

  <Card title="Test Your Runbook" icon="flask" href="/testing/playground">
    Validate in the playground
  </Card>
</CardGroup>