# Playbooks

> Give an agent a goal and the outcomes that count as done, and let it find its own way there.

Source: https://docs.vlayers.ai/build/playbooks

Kind: How-to guide

## What you'll learn

How to write a playbook: a reusable, goal-driven skill with a prompt, tools and named outcomes. You use one when a conversation cannot be drawn as a straight line but you still need to control when the call moves on.

## When to use one

There are three ways to get words out of an agent, from most to least controlled:

| Step | What you control |
|---|---|
| Scripted steps (Say, Ask, Confirm) | The exact words, in order. |
| A playbook | The goal and the outcomes. The model finds the path. |
| An AI reply | Nothing beyond the prompt: one free-form turn, no goal, no outcome. |

Use scripted steps for anything that must be said a specific way, such as disclosures and compliance lines. Use a playbook when the caller can take the conversation in several directions and you care about the outcome, not the wording.

## Prerequisites

- A flow to use it in, or a plan to deploy it on its own. See [Flow builder](https://docs.vlayers.ai/build/flow-builder).
- Any [tools](https://docs.vlayers.ai/build/tools) the playbook should call, already registered.

## Step 1: Create the playbook

Open **Dashboard → Playbooks** and create one. Fill in its parts:

```text
Name          lead_qualification
Description   Qualify an inbound lead and book a demo if they are a fit

Instructions  You are qualifying an inbound lead. Find out what they are
              trying to solve, roughly how big their team is, and whether
              they have a timeline. Be curious, not interrogative: one
              question at a time, and react to what they say.

Tools         lookup_account, book_demo

Outcomes      Booked demo      caller agreed to a demo
                required: email, company
              Not a fit        wrong size or no need
              Follow up later  interested but not now
                required: email
```

| Part | What it does |
|---|---|
| **Description** | What the model reads to decide whether this playbook applies. Write it for the model, not your team. |
| **Instructions** | How to pursue the goal: tone, what to ask, what to avoid. This is the prompt, so the advice in [Voice and turn-taking](https://docs.vlayers.ai/build/voice) applies. |
| **Tools** | Which tools it may call while it works. Unlike an AI reply, a playbook can look things up and act mid-conversation. |
| **Outcomes** | How it can end. Each outcome becomes an exit on the canvas. Give each a plain description: that is how the model decides which one it reached. |
| **Required variables** | Per outcome. The playbook cannot exit through that outcome until these are captured. |

Required variables are enforced by the engine, not by asking the model nicely. If "Booked demo" requires an email and the model tries to finish without one, the exit is refused and the conversation continues. That is what makes a goal-driven step safe in a real call.

## Step 2: Publish it

Publishing freezes a version. Flows keep the version they were deployed with, so improving a playbook never silently changes an agent that works.

## Step 3: Use it

Two ways:

- **In a flow:** add a **Playbook** step and pick the playbook by name. Its outcomes appear as exits; connect each to what happens next. "Booked demo" might lead to a confirmation, "Not a fit" to a polite close.
- **On its own:** deploy the playbook directly as a one-step agent when it is the whole job.

## Test it

A playbook is the least predictable step you can add, so test it most. In a [dry run](https://docs.vlayers.ai/build/testing), be unhelpful, change your mind, and answer a different question than the one asked. Check it still lands on a sensible outcome. A replay can word things differently, so reset and run it a few times.

## Common problems

| Problem | Fix |
|---|---|
| The agent improvises an ending | Add the unhappy outcomes too, such as "Not a fit" and "Wants a human". |
| The call never moves on | An outcome requires a value the caller cannot give. Require only what you truly need. |
| The playbook does too much | If it has eight outcomes, it is probably two playbooks with a **Branch by intent** step in front. |

Name outcomes as things that happened ("Booked demo"), not as next steps ("Send calendar invite").

## Next steps

- [Tools](https://docs.vlayers.ai/build/tools): Give a playbook something to look up.
- [Variables](https://docs.vlayers.ai/build/variables): Capture the values outcomes require.