Skip to content

Author playbooks

A Playbook tells the agent what to accomplish in one kind of situation and how to approach it.

This document describes authoring them: the parts of a Playbook, writing a when-to-use line the agent can act on, and the patterns that hold up in real conversations. Playbooks are edited at Build · Behavior · Playbooks.

The parts of a Playbook

Field What it does
Name The label you and the agent use for it. The agent hands off between Playbooks by name.
Description Operator-facing summary shown in lists. Not read by the agent.
When to use The activation context. The agent reads every Playbook's when-to-use on every turn to recognize which one fits the moment.
Body The agent-facing instructions for operating while this Playbook is active.
Needs The Capabilities this Playbook acts through, picked from the ones the agent has. Knowledge is available in every Playbook and is not listed here. See Needs.
Default Marks the Playbook the agent starts in and returns to. Exactly one Playbook is the default.
Goal The Goal a conversation works toward while this Playbook is active, with an optional unless/then condition. A Playbook's Goal takes priority over an Outreach's Goal or the agent's default.
Belongs to an Outreach A Playbook written inside an Outreach. The agent knows it exists only in conversations that Outreach started; everywhere else it is left out of the Playbook index, so the agent never switches into it from a message someone sent first. The opener, class and Goal live on the Outreach. The default Playbook cannot belong to an Outreach.
Also inline these templates An override for Message Templates you want the agent to see without referencing them anywhere in the Playbook. Referencing a Message Template in the when-to-use, body, or an example already makes it available; use this only for a Message Template this Playbook deploys but never references in its own text.

Writing a good when-to-use

The when-to-use is the most consequential sentence in the Playbook: it is how the agent decides where a conversation goes. Write it as the condition, not the content:

  • "When the lead has asked to talk to a person, see times, book a demo, or otherwise indicates readiness to schedule."
  • "When the user is asking about products, pricing, or capabilities."

Two Playbooks with overlapping when-to-use descriptions compete, and the agent may bounce between them. The console flags pairs that loop repeatedly, showing both descriptions side by side so you can sharpen the boundary. If you see routing mistakes in conversations, the fix is almost always in a when-to-use, not in a body.

Writing the body

The body is instructions to the agent for one phase of the conversation. What works:

  • State the goal of the phase first, then the approach. The agent performs better when it knows what the Playbook is for.
  • Say what to avoid as well as what to do. A short "What to avoid" list prevents the most common failure modes ("Don't re-qualify the lead — discovery already happened").
  • Describe the exit. You don't author exit rules — the agent leaves when another Playbook fits — but if the phase should wrap up a specific way, say so in the body ("once the call is booked, confirm the details and return to general help").
  • Keep voice out of it. Tone belongs in Personality; hard limits belong in Guardrails. The body is about this situation.

Reviewed, exact-wording messages (a booking confirmation, a legal notice, a carousel of your dining venues) should not be pasted into the body. Put them in Message Templates and reference them so the copy renders the same way every time. Three forms count as a reference: template:<id> written in the instructions, [[template: <id>]], or the Message Template's name in quotes:

When the user asks what there is to do, send them
[[template: activities-carousel]].

Plain prose that happens to contain the template's id or name does not count — write template:activities-carousel or put the name in quotes. Referencing a template anywhere in the Playbook's when-to-use, body, or an example is enough to make it available: the agent already sees a short index of every template on the agent (id, name, purpose) on every turn, and referencing one in this Playbook's text adds its full body to what the agent reads while the Playbook is active.

A template set to only when named can be sent only through a reference like this one, so a consent notice or disclaimer only ever goes out from the Playbook that names it; see When the agent may use a Message Template.

The body is instructions, not copy that gets sent, so it is never compiled. What the agent takes from the line above is the template id.

The same holds for pictures: name an item from the media library as image:<id> and the agent shows that item. Unknown ids are dropped, and lint reports them as template.ref.unknown or media.ref.unknown.

Suggesting tappable replies

To have the agent offer tappable chips, say so in the body. Plain English works:

After asking about dates, offer tappable options for This weekend,
Next week, and Just browsing.

So does AML, which is more concise and is the same markup you write in a Message Template:

End the turn with [[chips: Boat rentals | Dining | Activities]]

Both say the same thing. A body is instructions, so the markup is read as a description of how the reply should look, not as text to send. The agent renders the chips itself and adapts them to the channel, so you do not write a Message for chips alone. Write a Message when the words must be exact every time, such as a confirmation or a legal notice.

The same holds for a card, a carousel, or a showcase of Things: describe it in the body, in English or in AML, and the agent builds it.

One kind of markup does not belong in a Playbook: anything carrying live data the agent has to look up. A time picker is the example. Slot ids exist only after the agent checks availability during the conversation, so ids written into a body are invented and the picker books nothing. Say "offer times from the calendar" and let the agent fetch them. Behavior lint reports an authored picker as playbook.aml.livedata.

Needs

A Playbook's Needs is the explicit list of Capabilities it acts through while it's active: Scheduling, People (saving details to the Person record), Notifications, and each custom integration by name, picked from what the agent has. Needs are what the agent has at hand the moment the Playbook is active, which keeps it focused on the job. The agent also knows about every other Capability you've set up: when a person asks for one (a guest in Answer questions asks to book a tour), the agent loads it for that moment and carries on. A Capability that isn't set up is never offered, and the agent says so rather than promising it.

Knowledge is not a Need. Every agent has Knowledge (Sources, Facts, Things, collections, and business info), and the agent can search it and sees its business info and Things in every Playbook, whatever the Needs say. A Playbook that answers questions from Knowledge needs nothing listed for that.

An empty Needs list is a real, valid choice, not an oversight: it means this Playbook acts through none of the agent's Capabilities, which is correct for a purely conversational phase such as general help or answering questions.

When a Playbook is created or imported without Needs, Anychat fills in every Capability the agent can act through. Narrowing is a deliberate edit: open the Playbook, remove a Capability from Needs, and save. Lint flags a Needs entry that names a Capability the agent doesn't have, and the readiness card marks the Playbook not ready when something in its Needs isn't set up.

The Default Playbook

The default is the agent's home: the opening of a conversation, the "what does this person want?" phase, and where the agent returns when a task completes. Keep it general. It doesn't need to mention the other Playbooks — the agent sees every Playbook's when-to-use at all times and routes on its own.

Starting from the catalog

The Playbooks list can import entries from the Anychat catalog (the Schedule Sales Call Playbook, Escalate to Human, and others). An imported Playbook is copied onto your agent; edit it freely. The copy keeps a link to its catalog origin, so when Anychat publishes a new version the console shows an Update to latest option with a preview of what changed. Adopting the update is your choice, and if you've edited the copy the console marks it as diverged rather than silently overwriting your work.

Task mechanics

Exact mechanics (proposing appointment times, confirming a slot) are written in the Playbook's body, alongside its judgment and phase choreography, and the agent reads them only while the Playbook is active. Catalog Playbooks arrive with their mechanics already in the body. When the template your agent was created from publishes a new version, the agent's Behavior page offers a review: every changed section, including each Playbook's body, appears in a merge view where you take the template's change or keep yours.

Playbooks used to carry these mechanics as separate procedures edited beneath the body. They have been merged into the body: on every existing agent each procedure's text was appended, unchanged, under a Procedures heading, so the agent behaves exactly as before and you now edit it in one place. When a steps-exact path is what you want, use a deterministic path instead.

What's next