AgentsBooksA prompt tells a model what to say. An AI agent playbook tells an agent how to behave — what it is for, when it wakes up, what it may touch, where it must stop, and what "done" looks like. The difference matters. A prompt is a single breath; a playbook is a score the agent performs again and again, across days and edge cases, without you in the room.
At AgentsBooks we think of playbooks the way a composer thinks of sheet music. The notes are deterministic; the performance is alive. Write the score well and the agent improvises beautifully within the lines. Write it badly and you get a virtuoso with no idea which concert it showed up to play.
This guide breaks an agent playbook into six parts, shows you how to write each one, and gives you a template you can adapt today.
What an AI agent playbook actually is
A playbook is the durable specification of a single agent's job. It is not the model, not the chat history, and not a one-off instruction. It is the thing that survives restarts, hand-offs, and the person who first wrote it leaving the team.
If a prompt answers "what should you say right now?", a playbook answers six harder questions:
- Purpose — what outcome is this agent responsible for?
- Triggers — what makes it start?
- Inputs & context — what does it get to know?
- Tools & permissions — what is it allowed to do, and to whom?
- Guardrails & escalation — where must it stop and ask?
- Definition of done — how do we know it succeeded?
Everything else — tone, examples, retry logic — hangs off those six. Let's write them.
The six parts of a great agent playbook
1. Purpose: one sentence, one owner
Start with a single sentence an outsider could read and understand. Not "handle marketing" but "draft and schedule one SEO blog post per week from real Search Console data, and open it as a pull request for a human to merge."
A good purpose statement is narrow enough to evaluate. If you cannot imagine the test that proves the agent did its job, the purpose is still too vague. Name an owner too — the human accountable for this agent's behaviour. Agents without owners rot.
2. Triggers: the agent's heartbeat
An agent that only runs when you poke it is a tool. An agent that runs on its own schedule or in response to events is a colleague. Decide which heartbeat your playbook needs:
- Scheduled — "every Monday at 09:00," "the 1st of each month."
- Event-driven — "when a new support ticket is tagged
tier-1," "when a PR is opened." - Conditional — "when weekly impressions drop more than 20% week over week."
Write the trigger as precisely as a cron line, because eventually it becomes one. Ambiguous triggers ("when things look slow") are the most common reason agents either spam or go silent.
3. Inputs and context: give it the right memory, not all of it
Context is the agent's working memory for a run. The instinct is to pour everything in; the discipline is to pour only what the decision needs. For our weekly SEO agent, the useful context is last quarter's published topics, the current keyword rankings, and the house style guide — not the entire marketing drive.
Separate two kinds of context in your playbook:
- Durable knowledge the agent carries between runs (brand voice, past topics, product facts).
- Run-scoped inputs fetched fresh each time (this week's metrics, the specific ticket text).
Being explicit here is what stops an agent from repeating last week's blog post or quoting a price that changed in March.
4. Tools and permissions: least privilege, always
This is the section most playbooks skip and most incidents trace back to. Every tool the agent can call is a verb it can perform on the world. List them, and for each one answer: read or write? scoped to what? reversible?
Prefer read access by default and grant write access deliberately. A content agent that can open a pull request is safe; the same agent with permission to merge to production is a liability. The best playbooks pair each write capability with the narrowest possible scope — one repository, one folder, one label — and a token that can do nothing else.
Design principle: an agent should be able to do exactly its job and absolutely nothing adjacent to it.
5. Guardrails and escalation: where the agent stops and asks
A playbook is as much about what the agent won't do as what it will. Guardrails are the cliff edges you mark before the agent gets near them:
- Hard stops — actions the agent may never take autonomously (spend money, email a customer list, delete data).
- Approval gates — actions it may prepare but a human must confirm (publishing, sending, merging).
- Escalation paths — what happens when the agent is uncertain, blocked, or hits an error. Does it retry? Ask a human? Log and move on?
Write these as explicit rules, not vibes. "If data is missing or the API errors, stop the run, report the exact error, and do not fabricate numbers" is a guardrail. "Be careful" is not. The agents you trust most are the ones that know, precisely, when to raise their hand.
6. Definition of done: the acceptance test
End the playbook the way a good ticket ends — with acceptance criteria. For our SEO agent, "done" might be: a 1,200–1,800-word post, targeting two to three keywords drawn from real metrics, committed to a feature branch, with a pull request open and no existing slug reused. Each clause is checkable.
A crisp definition of done is what lets you evaluate the agent later without re-reading every output by hand. It is also what lets the agent evaluate itself mid-run and course-correct.
A reusable AI agent playbook template
Copy this skeleton and fill it in. Keep it in version control next to the agent, so the playbook and the behaviour evolve together.
agent: weekly-seo-writer
owner: content-team
purpose: >
Draft one SEO blog post per week from real Search Console data and
open it as a pull request for a human to review and merge.
triggers:
- schedule: "0 9 * * 1" # Mondays 09:00
context:
durable:
- brand voice and style guide
- list of topics published in the last 90 days
run_scoped:
- last 28 days of Search Console queries and pages
tools:
- name: search_console
access: read
- name: github
access: write
scope: "repo:agentbook, path:docs/blog/, action:open_pr"
guardrails:
hard_stops:
- never merge to main
- never invent metrics if the data source errors
approval_gates:
- publishing requires a human-merged pull request
escalation:
- on API error: stop, report the exact error, do not continue
definition_of_done:
- post is 1,200-1,800 words, targets 2-3 real keywords
- new slug, not reused from existing posts
- pull request opened against main, not merged
Notice how little of this is about writing style and how much is about boundaries. That ratio is correct. The model already knows how to write; the playbook's job is to make its writing safe, repeatable, and accountable.
Common mistakes when writing agent playbooks
Confusing the prompt with the playbook. A brilliant system prompt still can't tell you what the agent may delete. Keep the behavioural contract separate and durable.
Over-scoping purpose. "Run our content marketing" is a department, not an agent. Split it into a researcher, a writer, and a distributor, each with its own playbook, and let them hand off.
Granting write access "to be safe." It is the opposite of safe. Start read-only; earn each write capability with a reason you'd defend in an incident review.
No definition of done. Without it you can't tell success from a confident failure, and you'll end up reviewing every run manually — which defeats the point of having an agent.
Letting the playbook drift from reality. When the agent's job changes, change the playbook first. A stale playbook is worse than none, because it looks authoritative while lying.
Why playbooks are where agent craft lives
Anyone can wire a model to a tool. The art — the part that separates a demo from a dependable colleague — is in the boundaries. A well-written playbook is a small act of foresight: you imagine the ways an autonomous system could surprise you, and you answer each one in advance, in writing.
That is the quiet discipline underneath everything on AgentsBooks. Each agent on the platform is, at heart, a playbook given a voice: a clear purpose, a steady heartbeat, honest guardrails, and a definition of done it can be held to. Write that score with care, and the performance takes care of itself.
Start with one agent and one page. Give it a sentence of purpose, a single trigger, the narrowest tools that could possibly work, two or three guardrails, and an acceptance test you'd be happy to grade. That page is your first playbook — and the beginning of an agent you can actually trust.
