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.

Stars
★ 94
Last updated
3mo ago
License
MIT
Primary language
Python

At a glance

How it runs
CLIFramework
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
Python 3.12+Anthropic API keypipShell / CLINetwork accessLocal filesystem
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)

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.

  1. AI developers prototyping multi-step conversational flows by writing Markdown and running playbooks run
  2. Process owners who want to read the logic that actually executes instead of a spec that drifts from implementation
  3. Teams mixing English decision steps with Python data handling in one program, e.g. looping over countries and calling the model per item
  4. Debugging sessions where you set breakpoints on English steps and inspect variables and the call stack in VS Code
  5. 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 playbooks
export ANTHROPIC_API_KEY=your-anthropic-api-key

How 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 program

Run it, optionally with the session log or agent-to-agent message snooping:

playbooks run hello.pb
playbooks run hello.pb -v
playbooks run hello.pb --snoop=true

Open the browser playground to run programs and read execution logs:

playbooks playground

For 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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
43/ 100 5-point scale 2.2 / 5
Trust 8/29
Reliability 8/14
Adaptability 8/18
Convention 9/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust8 / 29 · 1.4/5

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.

Reliability8 / 14 · 2.9/5

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).

Adaptability8 / 18 · 2.2/5

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.

Convention9 / 18 · 2.5/5

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).

Effectiveness7 / 13 · 2.7/5

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).

Verifiability3 / 8 · 1.9/5

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).

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 11, 2026 Reviewed revision 1f6ee0cc760f
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/playbooks.svg)](https://followagents.com/en/agents/playbooks)
<a href="https://followagents.com/en/agents/playbooks"><img src="https://followagents.com/badge/playbooks.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.7.4
    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 ↗
  2. v0.7.3
    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 ↗
  3. v0.7.2
    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?
The software is MIT-licensed and open source, but execution needs an LLM provider — the quickstart uses an Anthropic API key — so you pay per model usage.
How do natural language and Python interact?
A .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?
The README states the runtime keeps a real call stack with step execution, breakpoints and variable inspection; -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?
The README uses an Anthropic API key in its examples and says .env.example lists other supported providers, without enumerating them in the text.
Can I debug it in an IDE?
Yes — install the “Playbooks Language Support” VS Code extension, then set breakpoints on English steps in a .pb file and inspect the call stack and variables.
Is Playbooks AI open source?
Yes. The source code is on GitHub (playbooks-ai/playbooks) under the MIT licence.
Is Playbooks AI safe to use?
FollowAgents' FARS review (Nov 11, 2026) scored Playbooks AI 8/29 on trust and safety. The review did not find these safety controls in the source: rollback or recovery path. Before giving it real accounts or data: Back up first, or work on a git branch or snapshot, so its changes can be undone.
Is Playbooks AI still maintained?
Development has slowed: the latest commit on GitHub is from 2026-08-11, within the last six months but not the last 30 days. The latest release is v0.7.4 (2026-02-02).
Who makes Playbooks AI?
Playbooks AI is published on GitHub by the account playbooks-ai. FollowAgents has not verified which person or company is behind that account.
What is Playbooks AI's official website?
The project's GitHub repository lists https://runplaybooks.ai as its website. That link is set by the repository owner; the source code itself is on GitHub (playbooks-ai/playbooks).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts