Skip to main content

​
Overview

As your team scales AI automation, you’ll deploy multiple workers with specialized roles. This guide covers patterns for effective AI-to-AI collaboration and workspace organization.

​
Worker Specialization Patterns

​
Role-Based Workers

Assign workers to specific functional areas:
  • Documentation Worker: Maintains docs, monitors PRs for doc needs
  • Support Worker: Handles customer tickets, creates bug reports
  • Code Review Worker: Reviews PRs, enforces code standards
  • DevOps Worker: Manages deployments, monitors infrastructure

​
Channel-Based Workers

Deploy workers dedicated to specific communication channels: 
# Example: Gil's channel-specific approach
workers:
  - name: github-worker
    channels: [github-prs, github-issues]
    tools: [github, linear]
    
  - name: slack-worker
    channels: [support-slack, team-slack]
    tools: [slack, zendesk]
    
  - name: email-worker
    channels: [support-email]
    tools: [gmail, intercom]
Benefits:
  • Clear separation of concerns
  • Prevents message duplication
  • Easier to debug and monitor
  • Scales horizontally

​
Hybrid Approach

Combine role-based and channel-based patterns: 
- name: frontend-github-worker
  role: frontend-specialist
  channels: [github-prs]
  filters:
    files: ['src/components/**', 'src/ui/**']

- name: backend-github-worker
  role: backend-specialist
  channels: [github-prs]
  filters:
    files: ['src/api/**', 'src/services/**']

​
Coordination Strategies

​
Shared Knowledge Base

Use a centralized knowledge base that all workers can access:
  • Product documentation
  • Code standards
  • Company policies
  • Common procedures
Implementation:
  • Store in version control (Git)
  • Use Mintlify or similar for docs
  • Reference in worker system prompts
  • Update through automated workflows

​
Inter-Worker Communication

Enable workers to collaborate on complex tasks: Pattern 1: Sequential Handoffs 
Support Worker → Creates ticket → DevOps Worker → Deploys fix
Pattern 2: Parallel Processing 
PR Created → Code Review Worker (reviews code)
          → Docs Worker (checks docs)
          → Security Worker (scans vulnerabilities)
Pattern 3: Escalation Chain 
L1 Worker (handles common issues)
  ↓ (if complex)
L2 Worker (handles advanced issues)
  ↓ (if critical)
Human Review

​
Avoiding Conflicts

Channel Isolation: One worker per channel prevents duplicate responses 
# Good: Clear ownership
worker-1:
  channels: [github-prs]
worker-2:
  channels: [slack-support]

# Avoid: Overlapping channels
worker-1:
  channels: [github-prs, slack-support]
worker-2:
  channels: [slack-support]  # Conflict!
Filter Scoping: Use filters when workers share channels 
worker-1:
  channels: [github-prs]
  filters:
    labels: [documentation]

worker-2:
  channels: [github-prs]
  filters:
    labels: [bug, feature]
Task Locks: Implement locking for shared resources 
# Example: Prevent concurrent edits to same file
with task_lock(f"edit:{file_path}"):
    worker.edit_file(file_path, changes)

​
Gil’s Proven Pattern

Gil from the Spinnable team successfully manages multiple workers with this approach:

​
Architecture

  1. Separate Workers by Channel
    • Each communication channel has a dedicated worker
    • No overlap in channel assignments
    • Clear ownership and accountability
  2. Shared Knowledge Base
    • Central docs repository (Mintlify)
    • All workers reference same knowledge
    • Version controlled for consistency
  3. Specialized Toolsets
    • Each worker has tools for their channel
    • Common tools (Linear, GitHub) shared across workers
    • Channel-specific tools isolated

​
Example Configuration

# github-worker
name: "GitHub Automation Worker"
channels:
  - github-prs
  - github-issues
tools:
  - github
  - linear
  - mintlify
knowledge_base: "https://docs.company.com"

# slack-worker
name: "Slack Support Worker"
channels:
  - support-slack
tools:
  - slack
  - linear
  - zendesk
knowledge_base: "https://docs.company.com"

# email-worker
name: "Email Support Worker"
channels:
  - support-email
tools:
  - gmail
  - linear
  - intercom
knowledge_base: "https://docs.company.com"

​
Monitoring and Observability

​
Key Metrics

Track these metrics per worker:
  • Response Time: How quickly worker responds to triggers
  • Success Rate: Percentage of tasks completed successfully
  • Human Escalations: How often worker needs help
  • Resource Usage: API calls, token consumption

​
Dashboards

Create dashboards showing: 
Worker Overview
├── Active Workers (3/5)
├── Tasks Last 24h (147)
├── Success Rate (94.2%)
└── Escalations (8)

Per-Worker Breakdown
├── github-worker
│   ├── PRs Reviewed: 23
│   ├── Issues Triaged: 45
│   └── Success Rate: 96%
├── slack-worker
│   ├── Messages Handled: 67
│   ├── Tickets Created: 12
│   └── Success Rate: 91%
└── email-worker
    ├── Emails Processed: 34
    ├── Auto-Resolved: 28
    └── Success Rate: 95%

​
Alerting

Set up alerts for:
  • Worker failures or crashes
  • High error rates (>10%)
  • Unusual activity patterns
  • Resource limit warnings

​
Best Practices

​
1. Start Simple

Begin with one or two workers:
  • Learn the patterns
  • Establish workflows
  • Build confidence
Then scale horizontally.

​
2. Clear Boundaries

Define clear responsibilities:
  • Document worker roles
  • Specify channel ownership
  • List tool permissions
  • Define success criteria

​
3. Regular Reviews

Schedule weekly reviews:
  • Analyze worker performance
  • Review escalated cases
  • Update knowledge base
  • Refine prompts and filters

​
4. Version Control Everything

Keep in version control:
  • Worker configurations
  • System prompts
  • Knowledge base
  • Filter rules
This enables:
  • Rollbacks when needed
  • Change tracking
  • Team collaboration
  • Disaster recovery

​
5. Human Oversight

Maintain human involvement:
  • Review critical decisions
  • Handle complex edge cases
  • Approve sensitive actions
  • Provide feedback for improvement

​
Scaling Considerations

​
When to Add Workers

Add new workers when:
  • Response times increase
  • Workers handle multiple unrelated domains
  • Team grows into new areas
  • Support volume increases

​
When to Consolidate

Consolidate workers when:
  • Workers are underutilized
  • Roles overlap significantly
  • Maintenance burden is high
  • Context sharing is critical

​
Common Pitfalls

​
Duplicate Responses

Problem: Multiple workers respond to same message Solution: Strict channel isolation or mutually exclusive filters

​
Knowledge Drift

Problem: Workers have inconsistent information Solution: Single source of truth knowledge base, automated sync

​
Over-Automation

Problem: Workers handle tasks better done by humans Solution: Clear escalation criteria, regular human review

​
Under-Monitoring

Problem: Workers fail silently or produce poor results Solution: Comprehensive logging, alerting, and dashboards

​
Next Steps

Worker Memory

Learn how workers remember information

Training & Feedback

Train your workers effectively

Managing Workers

Best practices for managing multiple workers

Tool Permissions

Configure permissions for your workers