playbooks

Compiles structured natural language playbooks into PBAsm (semantic intermediate representation), a low-level instruction set designed for LLM execution. The compilation pipeline preserves semantic intent across model generations by treating playbooks as executable specifications rather than prompts, enabling forward compatibility and deterministic behavior independent of underlying LLM changes.

Implements a meeting-based coordination system where agents communicate through typed message channels with built-in batching and routing. The architecture uses an event bus for asynchronous message delivery, supports cross-agent playbook calls, and manages agent lifecycle (creation, initialization, termination) with automatic load balancing for scaling agent pools.

Provides a testing framework for validating playbook behavior through assertions on execution results, agent outputs, and message flows. Tests can verify that playbooks execute correctly, agents produce expected outputs, and multi-agent interactions follow expected patterns, with support for mocking LLM responses and deterministic test execution.

Enables playbooks to define capture functions that extract and structure data from LLM responses, user input, or external sources into typed variables. Capture functions support pattern matching, data transformation, and validation, allowing playbooks to parse unstructured LLM output into structured data for downstream processing.

Supports trigger-based control flow where playbook steps execute conditionally based on events, user input, or external signals. Triggers can be time-based (wait for duration), event-based (wait for message), or condition-based (wait for variable state), enabling reactive agent workflows that respond to external stimuli without polling.

Provides a library of pre-built playbooks implementing common agent patterns (research, code review, data analysis, etc.) that can be imported and customized. Built-in playbooks serve as templates and examples, reducing boilerplate and enabling rapid prototyping of standard agent workflows.

Integrates the Model Context Protocol to enable agents to invoke remote tools and services through standardized MCP server connections. Remote agents (RemoteAIAgent) execute playbooks in isolated processes or containers, with automatic serialization of execution state, context, and results back to the calling agent, supporting distributed multi-agent systems.

Maintains execution state across playbook steps using a call stack that tracks variable bindings, control flow position, and LLM context. Playbooks can pause at breakpoints, wait for external events, or be resumed from checkpoints, enabling long-lived agent workflows that survive interruptions and support interactive debugging with VSCode integration.

Abstracts LLM API differences through LLMHelper, supporting OpenAI, Anthropic, and Ollama with unified function-calling schemas, retry logic, and built-in response caching. The system preprocesses messages through a context compaction pipeline that manages token budgets, implements semantic context management, and constructs InterpreterPrompts that guide LLM execution of PBAsm instructions.

Supports mixing natural language playbook steps with embedded Python code blocks, executed through PythonExecutor and StreamingPythonExecutor. Python code runs in sandboxed environments with access to playbook variables and agent context, enabling complex logic, data transformations, and tool integrations without leaving the playbook language.

Integrates with Langfuse for comprehensive observability, tracking LLM calls, agent execution traces, message flows, and performance metrics. The event bus system emits structured events for all playbook execution steps, enabling real-time monitoring, cost analysis, and debugging of multi-agent systems through centralized trace collection.

Provides a hierarchical configuration system that loads settings from environment variables, config files, and runtime overrides, enabling tuning of model selection, message batching behavior, LLM caching strategies, and observability settings. Configuration precedence is clearly defined, allowing per-environment customization without code changes.

Provides a CLI-based chat interface for interacting with agents through the terminal, supporting real-time message streaming, multi-turn conversations, and integration with HumanAgent for user-in-the-loop workflows. The terminal interface handles message formatting, streaming output, and user input collection without requiring a web UI.

Provides a web UI for testing playbooks, visualizing agent execution flows, and debugging multi-agent interactions. The playground frontend displays execution traces, message flows between agents, variable states, and LLM responses in real-time, with support for pausing execution and inspecting state at breakpoints.