Skip to main content
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: 
{{Include: 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: 
## 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

Snippets

Create reusable instruction blocks

Tools

Learn about available tools

Test Your Runbook

Validate in the playground