Multi-Agent Workflows

Overview

Complex tasks often require different expertise. klaw supports multi-agent workflows where specialized agents collaborate, each contributing their unique capabilities. This guide covers patterns for effective multi-agent orchestration.

Why Multi-Agent?

Single agents work well for focused tasks. But consider:

Task	Better Approach
”Fix this bug”	Single agent (coder)
“Research best practices, implement them, then write docs”	Multi-agent workflow
”Review PR for code quality, security, and performance”	Multiple specialized reviewers

Orchestrator Routing

The simplest multi-agent pattern uses the orchestrator to route messages:

Configure Orchestrator

# ~/.klaw/config.toml
[orchestrator]
mode = "hybrid"
default_agent = "assistant"

[[orchestrator.rules]]
pattern = "(?i)(code|bug|fix|implement|refactor)"
agent = "coder"

[[orchestrator.rules]]
pattern = "(?i)(research|find|search|compare)"
agent = "researcher"

[[orchestrator.rules]]
pattern = "(?i)(deploy|docker|kubernetes|infrastructure)"
agent = "devops"

Automatic Routing

Messages are automatically routed:

User: "Fix the authentication bug"
→ Routes to: coder

User: "Research best practices for error handling"
→ Routes to: researcher

User: "Deploy to production"
→ Routes to: devops

Manual Routing

Override with @agent syntax:

@researcher Find Go error handling patterns
@coder Implement those patterns
@devops Deploy the changes

Inline Delegation

The delegate tool lets a main agent spawn ephemeral sub-agents that execute immediately and return results. This is the primary mechanism for task decomposition within a single conversation.

┌─────────────────────────────────────────────────┐
│               Main Agent                         │
│  "Build a full-stack feature with tests"        │
└──────────────────┬──────────────────────────────┘
                   │ delegate (parallel)
     ┌─────────────┼─────────────┐
     │             │             │
     ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│Frontend │  │ Backend │  │  Tests  │
│Sub-Agent│  │Sub-Agent│  │Sub-Agent│
└────┬────┘  └────┬────┘  └────┬────┘
     │             │             │
     └─────────────┴─────────────┘
              Results returned
              to main agent

Using the delegate Tool

{
  "tool": "delegate",
  "input": {
    "task": "Create React components for user authentication",
    "tools": ["read", "write", "edit", "glob", "bash"],
    "system_prompt": "You are a frontend specialist. Use React and TypeScript."
  }
}

Key properties:

Sub-agents run inline — the main agent waits for the result
Each sub-agent gets its own tool set (configurable via allowlist)
Sub-agents can nest up to 3 levels deep
5-minute timeout per delegation
Output truncated at 30,000 characters

In Practice

User: Build a user profile feature with frontend, backend, and tests

Agent: I'll delegate each part to a specialized sub-agent:

╭─ delegate
│ Task: Create React components for user profile
│ Tools: [read, write, edit, glob, bash]
│ Result: Created ProfilePage.tsx, ProfileForm.tsx, ProfileAvatar.tsx
╰─

╭─ delegate
│ Task: Create /api/profile endpoint with CRUD operations
│ Tools: [read, write, edit, glob, bash]
│ Result: Created profile_handler.go, profile_routes.go
╰─

╭─ delegate
│ Task: Write tests for the profile feature
│ Tools: [read, write, edit, glob, bash]
│ Result: Created profile.test.tsx, profile_handler_test.go
╰─

All components complete. The feature is ready for review.

Persistent Agent Spawning

For long-lived agents that persist across conversations, use agent_spawn to create orchestrator bindings:

{
  "tool": "agent_spawn",
  "input": {
    "name": "frontend-worker",
    "task": "Create React components for user authentication",
    "model": "claude-sonnet-4-20250514"
  }
}

Use agent_spawn when you need agents that are routable via @agent syntax and persist beyond a single conversation. Use delegate when you need inline task execution within a conversation.

Workflow Patterns

Sequential Pipeline

Each agent’s output feeds the next:

Research → Implement → Review → Deploy

# Step 1: Research
klaw dispatch "Research authentication best practices" --agent researcher

# Step 2: Implement (with research context)
klaw dispatch "Implement auth based on research findings" --agent coder

# Step 3: Review
klaw dispatch "Review the authentication implementation" --agent reviewer

# Step 4: Deploy
klaw dispatch "Deploy the auth changes" --agent devops

Parallel Execution

Independent tasks run simultaneously. With the delegate tool, the LLM can issue multiple delegations in a single turn and they execute in parallel:

     ┌── Security Review ──┐
     │                     │
Task ├── Code Review ──────┼── Aggregate
     │                     │
     └── Performance Review┘

Via inline delegation:

Agent calls delegate("Review auth.go for vulnerabilities")
Agent calls delegate("Review auth.go for code quality")
Agent calls delegate("Review auth.go for performance")
→ All three sub-agents run in parallel
→ Results collected and aggregated

Or in Slack with orchestrator routing:

@security Review auth.go for vulnerabilities
@coder Review auth.go for code quality
@performance Review auth.go for performance issues

Supervisor Pattern

A coordinator agent manages workers:

// The supervisor delegates and aggregates
supervisor := agent.New(agent.Config{
    SystemPrompt: `You are a project coordinator.
    When given a task:
    1. Break it into subtasks
    2. Spawn appropriate agents for each
    3. Monitor progress
    4. Aggregate results
    5. Report completion`,
})

Creating Specialized Teams

Development Team

# Create team members
klaw create agent frontend \
  --skills code-exec \
  --task "React/TypeScript frontend development"

klaw create agent backend \
  --skills code-exec,database \
  --task "Go/Python backend development"

klaw create agent tester \
  --skills code-exec \
  --task "Writing and running tests"

klaw create agent reviewer \
  --skills code-exec,git \
  --task "Code review and quality assurance"

Research Team

klaw create agent researcher \
  --skills web-search,browser \
  --task "Primary research and data gathering"

klaw create agent analyst \
  --skills database,code-exec \
  --task "Data analysis and insights"

klaw create agent writer \
  --skills code-exec \
  --task "Writing reports and documentation"

DevOps Team

klaw create agent deployer \
  --skills docker,git \
  --task "Deployment and releases"

klaw create agent monitor \
  --skills web-fetch,api \
  --task "Monitoring and alerting"

klaw create agent incident \
  --skills docker,bash \
  --task "Incident response and troubleshooting"

Namespace-Based Teams

Organize agents into namespaces for isolation:

# Create namespaces
klaw create namespace frontend --cluster production
klaw create namespace backend --cluster production
klaw create namespace devops --cluster production

# Bind agents to namespaces
klaw create agent-binding react-dev \
  --namespace frontend \
  --agent frontend \
  --skills code-exec

klaw create agent-binding go-dev \
  --namespace backend \
  --agent backend \
  --skills code-exec,database

Dispatch to namespace:

klaw dispatch "Build login form" --namespace frontend
klaw dispatch "Create auth API" --namespace backend

Communication Patterns

Shared Context via Workspace

Agents share knowledge through workspace files:

# ~/.klaw/workspace/PROJECT.md

## Current Sprint
- Authentication feature in progress
- Frontend: @frontend-agent
- Backend: @backend-agent

## Decisions
- Using JWT for tokens
- Refresh token rotation every 7 days

## Blocking Issues
- None currently

Message Passing (Slack)

In Slack, agents can communicate via channels:

#engineering channel:
@coder I've completed the API endpoints for auth

#frontend channel:
@frontend The auth API is ready. Here's the spec: [link]

Task Dependencies

Use cron or dispatch with dependencies:

# Research must complete before implementation
klaw dispatch "Research OAuth providers" --agent researcher --id task-1

# This waits for task-1
klaw dispatch "Implement OAuth" --agent coder --depends-on task-1

Best Practices

Define clear boundaries

Each agent should have a specific, non-overlapping responsibility. Avoid agents that do “everything.”

Establish communication protocols

Define how agents share information—workspace files, specific channels, or structured handoffs.

Verify handoffs

When one agent finishes, another should verify the output before continuing.

Monitor and adjust

Track which patterns work well. Some tasks may be better with fewer, more capable agents.

Example: Full Feature Development

1. Create the Team

klaw create agent architect --skills code-exec --task "Design and planning"
klaw create agent coder --skills code-exec,git --task "Implementation"
klaw create agent tester --skills code-exec --task "Testing"
klaw create agent reviewer --skills code-exec,git --task "Code review"

2. Configure Orchestrator

[orchestrator]
mode = "hybrid"

[[orchestrator.rules]]
pattern = "(?i)(design|architecture|plan)"
agent = "architect"

[[orchestrator.rules]]
pattern = "(?i)(implement|build|create|fix)"
agent = "coder"

[[orchestrator.rules]]
pattern = "(?i)(test|coverage|qa)"
agent = "tester"

[[orchestrator.rules]]
pattern = "(?i)(review|check|verify)"
agent = "reviewer"

3. Execute the Workflow

User: We need a user registration feature

@architect: I'll design the registration flow...
[Creates design document]

@coder: Implementing based on the design...
[Creates registration code]

@tester: Writing tests for registration...
[Creates test suite]

@reviewer: Reviewing the implementation...
[Provides feedback]

@coder: Addressing review feedback...
[Updates code]

Feature complete!

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

Multi-Agent Workflows

Overview

Why Multi-Agent?

Orchestrator Routing

Configure Orchestrator

Automatic Routing

Manual Routing

Inline Delegation

Using the delegate Tool

In Practice

Persistent Agent Spawning

Workflow Patterns

Sequential Pipeline

Parallel Execution

Supervisor Pattern

Creating Specialized Teams

Development Team

Research Team

DevOps Team

Namespace-Based Teams

Communication Patterns

Shared Context via Workspace

Message Passing (Slack)

Task Dependencies

Best Practices

Example: Full Feature Development

1. Create the Team

2. Configure Orchestrator

3. Execute the Workflow

Next Steps

Orchestrator

Distributed Deployment

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

​Overview

​Why Multi-Agent?

​Orchestrator Routing

​Configure Orchestrator

​Automatic Routing

​Manual Routing

​Inline Delegation

​Using the delegate Tool

​In Practice

​Persistent Agent Spawning

​Workflow Patterns

​Sequential Pipeline

​Parallel Execution

​Supervisor Pattern

​Creating Specialized Teams

​Development Team

​Research Team

​DevOps Team

​Namespace-Based Teams

​Communication Patterns

​Shared Context via Workspace

​Message Passing (Slack)

​Task Dependencies

​Best Practices

​Example: Full Feature Development

​1. Create the Team

​2. Configure Orchestrator

​3. Execute the Workflow

​Next Steps

Orchestrator

Distributed Deployment

Overview

Why Multi-Agent?

Orchestrator Routing

Configure Orchestrator

Automatic Routing

Manual Routing

Inline Delegation

Using the delegate Tool

In Practice

Persistent Agent Spawning

Workflow Patterns

Sequential Pipeline

Parallel Execution

Supervisor Pattern

Creating Specialized Teams

Development Team

Research Team

DevOps Team

Namespace-Based Teams

Communication Patterns

Shared Context via Workspace

Message Passing (Slack)

Task Dependencies

Best Practices

Example: Full Feature Development

1. Create the Team

2. Configure Orchestrator

3. Execute the Workflow

Next Steps