playbooks 0.7.1

A framework for creating AI applications and agents using natural language programming

Playbooks is a framework and runtime for building verifiable multi-agent AI systems with Natural Language Programs.

Describe what your agents should do, not how to do it. Focus on agent behavior at a high level while the LLM handles implementation details and edge cases. Mix natural language and Python seamlessly on the same call stack. Get verifiable execution, full observability, and programs that business users can actually read and approve.

Here's a complete 29-line Playbooks program that orchestrates natural language and Python code together. Notice how the Main playbook (line 4) calls Python function process_countries (line 20), which then calls natural language playbook GetCountryFact (line 27).

# Country facts agent
This agent prints interesting facts about nearby countries

## Main
### Triggers
- At the beginning
### Steps
- Ask user what $country they are from
- If user did not provide a country, engage in a conversation and gently nudge them to provide a country
- List 5 $countries near $country
- Tell the user the nearby $countries
- Inform the user that you will now tell them some interesting facts about each of the countries
- process_countries($countries)
- End program

```python
from typing import List

@playbook
async def process_countries(countries: List[str]):
    for country in countries:
        # Calls the natural language playbook 'GetCountryFact' for each country
        fact = await GetCountryFact(country)
        await Say("user", f"{country}: {fact}")
```

## GetCountryFact($country)
### Steps
- Return an unusual historical fact about $country

This accomplishes the same task as implementations that are significantly longer and more complex using traditional agent frameworks.

What is Software 3.0?

Software 3.0 is the evolution from hand-coded algorithms (Software 1.0) and learned neural network weights (Software 2.0) to natural language as the primary programming interface.

In Playbooks, you write programs in human language that execute directly on large language models. The LLM acts as a semantic CPU that interprets and runs your instructions. Instead of translating business logic into formal code syntax or training models on data, you describe what you want in natural language, mix it seamlessly with Python when needed, and get verifiable, observable execution.

This changes how you build AI systems: business stakeholders can read and approve the actual program logic, AI systems become transparent rather than black boxes, and sophisticated agent behaviors become accessible without sacrificing control or understanding.

Why Playbooks?

• Think at a Higher Level : Focus on what your agent should do, not implementation mechanics. Define complex, nuanced behaviors without getting lost in orchestration details. The framework handles the low-level execution.

• Natural Exception Handling : The LLM handles edge cases and exceptional conditions smoothly without explicit code for every contingency. Your agents adapt to unexpected situations naturally.

• Powerful Abstractions : Multi-agent meetings for complex coordination. Triggers for event-driven behavior. Seamless mixing of natural language and Python. Abstractions that would take hundreds of lines in other frameworks are built-in.

• Readable by Everyone : Business stakeholders can read and approve the actual program logic. No more "black box" AI systems. What you write is what executes.

• Verifiable & Observable : Unlike prompt engineering where you hope the LLM follows instructions, Playbooks guarantees verifiable execution. Step debugging in VSCode, detailed execution logs, full observability.

Get Started in 10 Minutes

Build your first AI agent with Playbooks. You'll need Python 3.12+ and an Anthropic API key.

Install Playbooks

pip install playbooks

Run the Country Facts Example

Try the more advanced example from above:

playbooks run country-facts.pb

You can also use the Playground for interactive development:

playbooks playground

The Playground provides a visual interface to run programs, view execution logs, and iterate quickly.

Step Debugging in VSCode

For production development, install the Playbooks Language Support extension:

1. Open VSCode Extensions (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for "Playbooks Language Support"
3. Click Install

Now you can set breakpoints and step through your agent's execution, just like traditional code!

📚 Documentation

Visit our documentation for comprehensive guides, tutorials, and reference materials.

Changelog

See CHANGELOG.md for the latest updates.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

We welcome contributions! Please see CONTRIBUTING.md for details.