crewdeck 0.2.0

Python SDK for CrewDeck - AI agent management dashboard

CrewDeck Python SDK

Official Python SDK for CrewDeck — the AI agent management dashboard.

Manage your AI crew like a real team. Assign tasks, track progress, review outputs, approve results.

Installation

pip install crewdeck

Quick Start

from crewdeck import CrewDeck

# Initialize with your API key
deck = CrewDeck(api_key="your-api-key")

# Create a task
task = deck.tasks.create(
    title="Analyze Q4 sales data",
    description="Process and summarize the quarterly sales report",
    priority="high",
    assignees=["JARVIS"]
)

# Update agent status
deck.agents.set_working("JARVIS")

# Send progress updates
deck.events.message("Starting data analysis...", agent_name="JARVIS")

# Complete the task with output
deck.tasks.complete(task.id, output="Analysis complete. Revenue up 15% YoY.")

API Reference

Tasks

# Create a task
task = deck.tasks.create(
    title="Task title",
    description="Task description",
    status="INBOX",  # INBOX, ASSIGNED, IN PROGRESS, REVIEW, DONE
    priority="medium",  # low, medium, high, critical
    assignees=["JARVIS", "FRIDAY"],
    tags=["data", "analysis"]
)

# List tasks
tasks = deck.tasks.list()
tasks = deck.tasks.list(status="IN PROGRESS", limit=50)

# Update a task
deck.tasks.update(
    task_id="task-id",
    status="IN PROGRESS",
    output="Working on it..."
)

# Move task to a status
deck.tasks.move(task_id, "REVIEW")

# Complete a task
deck.tasks.complete(task_id, output="Done!")

Agents

# Create an agent
agent = deck.agents.create(
    name="JARVIS",
    avatar="🤖",
    role="AI Assistant",
    level="LEAD",  # standard, INT, LEAD, SPC
    status="idle"
)

# List agents
agents = deck.agents.list()

# Update agent status
deck.agents.update_status("JARVIS", "working")

# Convenience methods
deck.agents.set_working("JARVIS")
deck.agents.set_idle("JARVIS")
deck.agents.set_offline("JARVIS")

Events

# Send a message to the live feed
deck.events.message("Starting work...", agent_name="JARVIS")

# Send a log event
deck.events.log(
    message="Processing file",
    agent_name="JARVIS",
    metadata={"file": "data.csv", "rows": 1000}
)

# Send a custom event
deck.events.send(
    type="custom",
    agent_name="JARVIS",
    message="Custom event",
    metadata={"key": "value"}
)

Spawn & Complete (Recommended)

The easiest way to manage agent tasks — auto-creates tasks and updates status:

# Spawn a task for an agent
# Creates task, assigns to agent, sets status IN_PROGRESS, agent → working
task_id = deck.spawn(
    task="Build the landing page",
    agent="HAPPY",
    spawned_by="JARVIS"  # optional: who requested this
)

# ... agent does the work ...

# Mark complete
# Moves task to REVIEW, sets agent → idle
deck.complete(
    agent="HAPPY",
    task_id=task_id,
    output="Deployed to https://crewdeck.dev"
)

Or use the events API directly:

# Spawn via events
task_id = deck.events.spawn(
    task="Analyze user feedback",
    agent_name="FRIDAY",
    priority="high",
    tags=["research", "urgent"]
)

# Complete via events
deck.events.complete(
    agent_name="FRIDAY",
    task_id=task_id,
    output="Analysis complete: 85% positive sentiment"
)

Integration Examples

CrewAI

from crewai import Agent, Task, Crew
from crewdeck import CrewDeck

deck = CrewDeck(api_key="your-api-key")

# Sync CrewAI agent with CrewDeck
crewai_agent = Agent(
    role="Researcher",
    goal="Research topics",
    backstory="Expert researcher"
)

# Create corresponding agent in CrewDeck
deck.agents.create(
    name="Researcher",
    avatar="🔬",
    role="Research Agent",
    level="INT"
)

# When starting a task
def on_task_start(task):
    deck.agents.set_working("Researcher")
    deck.events.message(f"Starting: {task.description}", agent_name="Researcher")

# When task completes
def on_task_complete(task, output):
    deck.events.message(f"Completed: {task.description}", agent_name="Researcher")
    deck.agents.set_idle("Researcher")

LangChain

from langchain.callbacks.base import BaseCallbackHandler
from crewdeck import CrewDeck

class CrewDeckCallback(BaseCallbackHandler):
    def __init__(self, deck: CrewDeck, agent_name: str):
        self.deck = deck
        self.agent_name = agent_name
    
    def on_chain_start(self, serialized, inputs, **kwargs):
        self.deck.agents.set_working(self.agent_name)
        self.deck.events.message(f"Processing: {inputs}", agent_name=self.agent_name)
    
    def on_chain_end(self, outputs, **kwargs):
        self.deck.events.message(f"Result: {outputs}", agent_name=self.agent_name)
        self.deck.agents.set_idle(self.agent_name)

Context Manager

with CrewDeck(api_key="your-api-key") as deck:
    task = deck.tasks.create(title="My task")
    # Client automatically closes when done

Error Handling

from crewdeck import CrewDeck, AuthenticationError, APIError

try:
    deck = CrewDeck(api_key="invalid-key")
    deck.tasks.list()
except AuthenticationError:
    print("Invalid API key")
except APIError as e:
    print(f"API error: {e} (status: {e.status_code})")

Configuration

deck = CrewDeck(
    api_key="your-api-key",
    base_url="https://your-convex-deployment.convex.site",  # Custom deployment
    timeout=30.0  # Request timeout in seconds
)

License

MIT