> ## Documentation Index
> Fetch the complete documentation index at: https://klaw.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Workflows

> Orchestrate multiple agents for complex tasks

## 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

```toml theme={null}
# ~/.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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
```

```bash theme={null}
# 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:

```go theme={null}
// 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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```markdown theme={null}
# ~/.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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion icon="target" title="Define clear boundaries">
    Each agent should have a specific, non-overlapping responsibility. Avoid agents that do "everything."
  </Accordion>

  <Accordion icon="message" title="Establish communication protocols">
    Define how agents share information—workspace files, specific channels, or structured handoffs.
  </Accordion>

  <Accordion icon="check" title="Verify handoffs">
    When one agent finishes, another should verify the output before continuing.
  </Accordion>

  <Accordion icon="gauge" title="Monitor and adjust">
    Track which patterns work well. Some tasks may be better with fewer, more capable agents.
  </Accordion>
</AccordionGroup>

## Example: Full Feature Development

### 1. Create the Team

```bash theme={null}
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

```toml theme={null}
[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!
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Orchestrator" icon="route" href="/docs/concepts/orchestrator">
    Deep dive into routing
  </Card>

  <Card title="Distributed Deployment" icon="server" href="/docs/guides/distributed-deployment">
    Scale multi-agent systems
  </Card>
</CardGroup>