Skip to content

Python Playbooks

Playbooks programs are composed of agents (markdown H1s). Each agent can have multiple markdown playbooks (H2s) and Python playbooks (Python functions).

Overview

  • A Python playbook is an async function decorated with @playbook
  • It can call markdown or Python playbooks, and be called by them. Python and markdown playbooks execute on the same call stack.
  • You can add triggers=[...] and public=True when needed
  • By convention, Python playbooks are named with PascalCase.

💡 Consider using an MCP server to implement simple python based tools that do not need trigger support or the ability to call Markdown playbooks.

Create a Python playbook

Define an async function decorated with @playbook inside a ``python block in your.pb`:

# Order management agent

```python
@playbook
async def CalculateShipping(weight: float, destination: str) -> float:
    """
    Calculate shipping costs based on weight and destination.

    Args:
        weight (float): The weight of the package
        destination (str): The destination of the package

    Returns:
        float: The shipping cost
    """
    ...    
    return base_rate + weight_cost + destination_surcharge
```

The @playbook decorator

The @playbook decorator registers a Python function as a playbook that can be called by other playbooks or triggered based on conditions.

```python
@playbook(
    triggers=["When user provides payment information"],
    public=True
)
async def ValidatePaymentInfo(amount: float, card_info: dict) -> bool:
    """
    Validate payment information.

    Args:
        amount (float): The amount of the payment
        card_info (dict): The payment information

    Returns:
        bool: True if the payment information is valid, False otherwise
    """
    ...
    return True
```

Decorator parameters

The @playbook decorator accepts several parameters that control the playbook's behavior and metadata.

Reserved parameters
  • triggers: A list of trigger conditions (as strings) that will cause the playbook to execute
Standard metadata
  • public: A boolean indicating whether the playbook should be available to other agents to call
  • export: A boolean indicating whether the playbook's implementation can be exported to other agents
  • remote: A dictionary containing remote service configuration
  • type: mcp, playbooks, etc.
  • url: Remote service URL
  • transport: transport protocol to use for the remote service
Custom metadata

All other keyword arguments become metadata attached to the playbook. This metadata can be used for documentation, configuration, etc.

See Metadata for more details.

Calling other playbooks

Use await when calling other markdown or Python playbooks.

# Example agent

```python
@playbook
async def PythonPlaybook1():
    number = await MarkdownPlaybook(100) # call a markdown playbook
    number = await PythonPlaybook2(number) # call a python playbook

    return double(number) # call a normal python function

def double(n):
    return n * 2
```

## MarkdownPlaybook($num)
### Steps
- return PythonPlaybook3($num) # call a python playbook

```python
import math

@playbook
async def PythonPlaybook2(n):
    return n * n

@playbook
async def PythonPlaybook3(n):
    return math.pow(n, 3)

```

Error handling

When called from markdown playbooks, return a user‑readable error string on failure; the LLM will handle it. Catch exceptions inside Python playbooks. Between Python playbooks, you may raise exceptions and handle them as usual.