Playbooks AI
Write what your AI agent should do in English Markdown; Playbooks compiles it into a semantic instruction set and runs it on an LLM.
- Source repo
- playbooks-ai/playbooks
- Stars
- ★ 94
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude APIOpenAI API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- AI developers prototyping multi-step conversational flows by writing Markdown and running
playbooks run - Not a fit if
- Teams that cannot send prompts to an external LLM provider
- Users wanting a visual drag-and-drop workflow builder
- Shops unwilling to run a Python 3.12 environment
- Website
- runplaybooks.ai ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-08-11latest release v0.7.4 (2026-02-02)
- Source review
- 43/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Playbooks is a semantic programming system for AI agents: programs are Markdown files (.pb) that a compiler turns into a semantic instruction set, which a runtime executes on an LLM with a real call stack, step debugging and verifiable control flow. # declares an agent, ## declares a playbook, and a playbook runs when its trigger fires. Natural-language steps and Python code live in the same program and call each other — an English Main playbook can call a Python process_countries function that calls the English GetCountryFact playbook once per item, all sharing one call stack and variables. When a playbook returns, its execution trace collapses into the return value, so context does not grow without bound. The primary entry point is the playbooks CLI, with a browser playground and a VS Code language extension for breakpoint debugging.
Reads .pb Markdown programs; the compiler parses agents (#), playbooks (##), triggers (e.g. At the beginning under ### Triggers) and step lists. The runtime walks the call stack, handing an English step to the LLM to interpret and execute, and can invoke Python code blocks embedded in the same file (@playbook-decorated functions). Python can call back into natural-language playbooks with await GetCountryFact(country) and emit output via await Say("user", ...). The CLI's playbooks run executes a program, -v prints the session log and --snoop=true shows messages passing between agents; playbooks playground launches a browser UI for running programs and reading execution logs.
- AI developers prototyping multi-step conversational flows by writing Markdown and running
playbooks run - Process owners who want to read the logic that actually executes instead of a spec that drifts from implementation
- Teams mixing English decision steps with Python data handling in one program, e.g. looping over countries and calling the model per item
- Debugging sessions where you set breakpoints on English steps and inspect variables and the call stack in VS Code
- Projects needing bigger abstractions such as event-driven triggers and multi-agent collaboration without hand-building orchestration graphs
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install playbooks
- Environment variables
ANTHROPIC_API_KEY- Config files
.env.env.example- Runtime
- Python 3.12+
How do you install or deploy this agent?
Requires Python 3.12+ and an Anthropic API key. Install with pip and export the key (a .env file also works; .env.example lists other supported providers):
pip install playbooksexport ANTHROPIC_API_KEY=your-anthropic-api-keyHow do you use this agent?
Create hello.pb with an agent (#), a playbook (##), a trigger and English steps:
# Hello world
This is a hello world demo for the playbooks system
## Hello world demo
This playbooks demo prints a hello playbooks message
### Triggers
- At the beginning
### Steps
- Greet the user with a hello playbooks message
- Tell the user that this is a demo for the playbooks system
- Say goodbye to the user
- End programRun it, optionally with the session log or agent-to-agent message snooping:
playbooks run hello.pbplaybooks run hello.pb -vplaybooks run hello.pb --snoop=trueOpen the browser playground to run programs and read execution logs:
playbooks playgroundFor debugging, install the “Playbooks Language Support” extension in VS Code, open a .pb file and set a breakpoint on an English step.
What are this agent's strengths and limitations?
- The program is readable Markdown, so the process owner can review the real logic rather than a separate spec
- English steps and Python share one call stack and variable set and call each other (
await GetCountryFact(...),await Say(...)) - Real call stack, breakpoints and variable inspection make execution verifiable instead of trusting the model to follow instructions
- A playbook's execution trace collapses into its return value on return, keeping context bounded
- The README shows a 29-line implementation versus a 272-line equivalent in a traditional framework
- The documented quickstart depends on an Anthropic API key, i.e. a paid external model service and network access
- Requires Python 3.12+, so older environments need upgrading
- Semantic execution depends on model quality, so step interpretation is less deterministic than plain code
- No complete offline or self-hosted model path is documented; other providers are only referenced via
.env.example - VS Code debugging needs a separate extension install and the playground is a separately launched process
How does this agent compare with similar options?
The README explicitly compares Playbooks with a traditional agent framework: the same country-facts agent is 29 lines of Markdown plus Python in Playbooks, while the linked traditional-framework implementation is 272 lines requiring orchestration graphs, state machines, retry logic and output parsers, which Playbooks delegates to the runtime and the LLM. No specific competing framework is named.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Playbooks AI This agent | 43 · Major gaps | CLIFree + model costs | ★ 94 | 3mo ago | Python | Claude API |
| Generative AI with LangChain | 41 · Major gaps | Library / SDKFree + model costs | ★ 1.5k | 3mo ago | Jupyter Notebook | OpenAI API · Claude API |
| OPC — One Person Company | Insufficient evidence | Agent plugin / skillFree + model costs | ★ 199 | 18d ago | JavaScript | Claude Code |
| Hello-Agents | 53 · Major gaps | Web appFree + model costs | ★ 88k | 8d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows a locally run framework using a user-supplied ANTHROPIC_API_KEY, CLI diagnostics to stderr, and a debug server defaulting to 127.0.0.1 — restrained defaults. However debug/server.py uses eval() for breakpoint and hit conditions (with __builtins__ restricted), and the framework sends data to external LLM and observability services via litellm/langfuse/redis/fastmcp with no documented data-flow, retention, or sensitive-data policy in README or CLAUDE.md. No rollback/undo mechanism is described. Attribution rests on README badges and an MIT copyright line from an unverified publisher. Each scores 1; rollback scores 0 for total absence of evidence.
main.py and cli.py show a clear compile/load/execute layering, pyproject pins dependency ranges, and CI includes a lint workflow, so dependency availability is adequate (2). Failure messaging is thin: only a few explicit raises (duplicate frontmatter keys, multiple cli_entry), while several CLI paths swallow exceptions (load_public_json_from_program returns None on any error), limiting diagnosability (1).
README clearly targets developers orchestrating agents in natural language, with hello world, hybrid Python/English, VSCode debugging, and playground scenarios (2). Capability boundaries — how much the LLM may improvise versus what compilation constrains, and safety limits — appear only scattered in CLAUDE.md without explicit statements; trigger precision relies on LLM semantic judgment with no documented ambiguity handling; environment fit is limited to Python 3.12+ and an Anthropic key with other providers only referenced via .env.example. These score 1.
README has a complete information architecture (install, run, debug, docs, license, contributing) with concrete install steps (2) and rich examples (2); LICENSE is full MIT text (3). Versioning is weak: the version appears only in pyproject (0.7.4) and CHANGELOG is referenced but not included in the packet (1). Naming stability is partial — .pb/.pbasm/public.json concepts differ between README and CLAUDE.md, and CLAUDE.md is truncated (1). No known-limitations or FAQ section (0). Maintenance responsibility points only to CONTRIBUTING and an unverified publisher (1).
The hello world and hybrid-call examples are directly runnable, giving good output usability (2). The marginal-value claim (29 lines vs 272) is clear but supported only by the project's own docs, not independently corroborated (2). Cost-benefit is under-addressed: every compile and run calls an LLM, the stack is heavy (litellm/langfuse/redis), and README does not discuss token cost, latency, or offline use (1).
Most strong README claims (verifiable execution, context collapsing, the 272-line comparison) point to external docs rather than in-repo checkable material, so claim_traceability is 1. CLAUDE.md broadly agrees with README on architecture, but contains volatile 'from git status' content and is truncated, limiting cross-source corroboration (1). Fact/inference separation is weak: the 'Software 3.0' vision is interleaved with concrete implementation without marking what is shipped versus roadmap (1).
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The debug server evaluates breakpoint conditions with eval(); although builtins are restricted, treat it as a potential code-execution surface and enable cautiously in production.
- The framework communicates with external LLM and observability services via litellm/langfuse/redis/fastmcp; README documents no data flow, log retention, or sensitive-data handling, so assess exfiltration risk before use.
- Several CLI paths silently swallow exceptions, which can make failures hard to diagnose.
- Publisher identity is unverified and maintenance responsibility/update path is unclear; CLAUDE.md contains volatile git-status content and is truncated.
- No known-limitations section and no discussion of token cost, latency, or offline availability.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
[v0.7.4] - 2026-02-01 Added Examples - Adaptive Waiting Example - Added example demonstrating adaptive waiting patterns for agents - Nativity Playbook - New nativity.pb example playbook Agent System - Unified Message Batching - Implemented unified RollingMessageCollector for batching all agent messages including direct and meeting broadcasts. Human messages now trigger immediate flush of pending batches for responsive interaction Performance …View on GitHub ↗ -
Release notes excerpt
[v0.7.3] - 2025-12-19 Added Agent Communication - Progressive Timeout Notifications - Agents waiting for responses had no visibility into delays. Added wait mechanism with periodic timeout checks that collects interrupt messages from other sources (user, other agents) and returns combined notification. The LLM decides whether to continue waiting or take alternative action—no hard maximum wait time MCP Integration …View on GitHub ↗ -
Release notes excerpt
[v0.7.2] - 2025-12-17 Added Telemetry & Observability - Event-Driven Langfuse Integration - Direct Langfuse calls created tight coupling between business logic and telemetry. Introduced comprehensive event handler system with LangfuseEventHandler class that subscribes to semantic business events and translates them to appropriate spans, observations, and traces …View on GitHub ↗
FAQ
Does running it cost money?
How do natural language and Python interact?
.pb file can embed Python code blocks; @playbook-decorated functions are callable from English steps, and Python can await an English playbook such as GetCountryFact and output with Say, all on one call stack and variable set.Can I verify what actually ran?
-v prints the session log and --snoop=true shows inter-agent messages, and a playbook's trace collapses into its return value.Which model providers are supported?
.env.example lists other supported providers, without enumerating them in the text.Can I debug it in an IDE?
.pb file and inspect the call stack and variables.Is Playbooks AI open source?
Is Playbooks AI safe to use?
Is Playbooks AI still maintained?
Who makes Playbooks AI?
What is Playbooks AI's official website?
Thanks — we use this to improve the page.