Kanban - PraisonAI

Kanban enables agents to coordinate through persistent tasks, creating a shared workspace where work is tracked and distributed across multiple agents.

Quick Start

Create Agent with Kanban Tools

from praisonaiagents import Agent
from praisonaiagents.kanban import KanbanStoreProtocol

# Agent with kanban protocols (implementation needed from wrapper)
agent = Agent(name="Coordinator", instructions="Break tasks down")
result = agent.start("Create user auth system")

Add Worker Agent

from praisonaiagents import Agent
from praisonaiagents.kanban import VALID_KANBAN_STATUSES

worker = Agent(name="Worker", instructions="Claim and complete tasks")
result = worker.start("Find ready tasks")

How It Works

Task coordination happens through a SQLite-backed persistent store that all agents and the UI share.

Component	Purpose
Kanban Store	SQLite database storing tasks, comments, links
Agent Tools	8 functions for task CRUD operations
CLI Commands	Human interface for task management
Background Dispatcher	Auto-claims ready tasks for processing

Task Status Flow

Concepts

Task Statuses

Tasks flow through 8 defined states from creation to completion:

Boards

Boards provide workspace isolation for different projects or contexts:

DAG Links

Tasks form directed acyclic graphs through parent-child dependencies:

Claim/Release

Workers coordinate through atomic claim and release operations:

Agent Tools

Kanban tools are available through the SDK protocols. The wrapper implementation provides these agent tools:

Task Management

Tool	Purpose	Example
`kanban_create`	Create new task	`kanban_create("Implement auth", assignee="dev")`
`kanban_list`	Filter tasks	`kanban_list(status="ready", assignee="dev")`
`kanban_show`	Get task details	`kanban_show("task_abc123")`

Status Changes

Tool	Purpose	Example
`kanban_complete`	Mark task done	`kanban_complete("task_abc123", "Auth working")`
`kanban_block`	Block with reason	`kanban_block("task_abc123", "Need API keys")`

Coordination

Tool	Purpose	Example
`kanban_comment`	Add progress note	`kanban_comment("task_abc123", "50% complete")`
`kanban_link`	Create dependency	`kanban_link("design_task", "implement_task")`
`kanban_heartbeat`	Signal liveness	`kanban_heartbeat("task_abc123", "testing")`

Boards & Storage

Single Board (Default)

~/.praisonai/kanban.db

Multi-Board Layout

~/.praisonai/kanban/boards/
├── project-a/kanban.db
├── project-b/kanban.db
└── team-x/kanban.db

Environment Configuration

Variable	Effect	Example
`PRAISONAI_KANBAN_BOARD`	Select active board	`export PRAISONAI_KANBAN_BOARD=project-a`
`PRAISONAI_KANBAN_DB`	Override DB path	`export PRAISONAI_KANBAN_DB=/custom/path.db`

Common Patterns

Coordinator-Worker Pattern

# Coordinator breaks down requests
from praisonaiagents import Agent
from praisonaiagents.kanban import VALID_KANBAN_STATUSES

coordinator = Agent(
    name="Coordinator", 
    instructions="Break user requests into kanban tasks"
)

# Worker with heartbeat reporting
worker = Agent(
    name="Worker",
    instructions="Claim ready tasks, report progress via heartbeat"
)

Background Processing

# Background processing requires wrapper implementation
# The praisonaiagents.kanban protocols support:
# - Task claiming and status updates
# - Heartbeat reporting for long-running tasks
# - Multi-board coordination

Worker with Heartbeat

from praisonaiagents import Agent
from praisonaiagents.kanban import VALID_KANBAN_STATUSES

worker = Agent(
    name="Worker",
    instructions="""Claim ready tasks and report liveness via heartbeat. 
    Use kanban_heartbeat every 30 seconds during long-running work."""
)

# Worker claims task and reports progress
result = worker.start("Find ready tasks, claim one, and report progress")

Human-Agent Collaboration

# Human-agent collaboration pattern
# Requires wrapper implementation of:
# - CLI commands for task management
# - UI board visualization
# - Agent-to-store protocol bindings

Best Practices

Task Granularity

Create tasks that can be completed in 15-30 minutes. Break larger work into linked subtasks using kanban_link for proper dependency tracking.

Status Management

Move tasks through statuses systematically: todo → ready → running → done. Use blocked for dependencies and review for human approval.

Agent Coordination

Use kanban_heartbeat during long-running tasks to signal liveness. Add detailed comments with kanban_comment to track progress and decisions.

Board Organization

Use separate boards for different projects or contexts. Default board works well for single-project setups.

Async Jobs

Asynchronous job processing and queuing

Background Tasks

Async job processing and scheduling

CLI Dispatcher

Command-line task orchestration

Documentation Index

​Quick Start

​How It Works

​Task Status Flow

​Concepts

​Task Statuses

​Boards

​DAG Links

​Claim/Release

​Agent Tools

​Task Management

​Status Changes

​Coordination

​Boards & Storage

​Single Board (Default)

​Multi-Board Layout

​Environment Configuration

​Common Patterns

​Coordinator-Worker Pattern

​Background Processing

​Worker with Heartbeat

​Human-Agent Collaboration

​Best Practices

​Related