Agent TeamsAgent Teams

# Spawn specialized agents
subagents spawn research-lead "Academic research on transformer optimization"
subagents spawn code-review "Review Python ML pipeline code" 
subagents spawn docs-writer "Document API endpoints"

# Check running agents
subagents list

# Steer agent direction
subagents steer research-lead "Focus on recent 2024 papers"

# Terminate when done
subagents kill docs-writer

# Organization with active agent teams
Research Team: ~200K tokens/day × 30 days × $0.045 avg = $270/month
Coding Team: ~150K tokens/day × 22 workdays × $0.025 avg = $82.5/month  
Writing Team: ~100K tokens/day × 30 days × $0.020 avg = $60/month

# Total estimated monthly cost: ~$412.5
# Compared to 2 full-time employees: ~$8,000+/month
ROI: 20x cost savings with 24/7 availability

# แบบ run-and-return (fire-and-forget)
subagents spawn research-lead 
  "Research transformer optimization papers from 2024"
  --mode run --timeout 600

# แบบ interactive session
subagents spawn code-reviewer 
  "Review the ML pipeline code in ./src/"  
  --mode session --label "code-review-v1"

# แบบ batch processing
subagents spawn translator 
  "Translate all .md files in ./docs/ to Thai"
  --mode run --label "docs-translation"

# Main orchestrator receives complex request
User: "Build a customer feedback analysis dashboard"

# Orchestrator analyzes and delegates
subagents spawn tech-lead 
  "Design architecture for feedback analysis dashboard
   - React frontend with data visualization
   - Python backend with NLP sentiment analysis  
   - Database schema for feedback storage
   - API design for frontend-backend communication"

# Tech-lead further delegates to specialists
subagents spawn backend-dev
  "Implement Python FastAPI backend:
   - Sentiment analysis endpoint using transformers
   - CRUD operations for feedback data
   - Database models with SQLAlchemy
   - Authentication and rate limiting"

subagents spawn frontend-dev  
  "Build React dashboard:
   - Responsive layout with Tailwind CSS
   - Charts using Chart.js or D3
   - Real-time updates via WebSocket
   - Filtering and search functionality"

subagents spawn test-engineer
  "Create comprehensive test suite:
   - Unit tests for backend API endpoints
   - Integration tests for database operations
   - Frontend component testing with Jest
   - End-to-end testing with Playwright"

# Conditional spawning based on results
if research_findings.confidence_score < 0.8:
    subagents spawn fact-checker 
      "Verify claims in research report: ${findings_file}"

# Sequential dependency chains
research_done = subagents spawn research-lead --wait
design_done = subagents spawn ui-designer 
  "Design based on: ${research_done.output_file}" --wait
subagents spawn frontend-dev 
  "Implement: ${design_done.mockups}"

# Parallel execution with synchronization
content_team = [
  subagents spawn writer --label "content-writer",
  subagents spawn editor --label "content-editor", 
  subagents spawn designer --label "visual-designer"
]
subagents wait content_team
subagents spawn publisher "Combine all content outputs"

# Check all running sub-agents
subagents list
┌─────────────┬──────────────┬─────────┬──────────┬─────────────┐
│ ID          │ Label        │ Status  │ Runtime  │ Progress    │
├─────────────┼──────────────┼─────────┼──────────┼─────────────┤
│ research-01 │ literature   │ running │ 5min 23s │ 📚 Paper 15/30 │
│ code-rev-02 │ backend      │ running │ 2min 45s │ 🔍 Function 8/12│
│ writer-03   │ documentation│ done    │ 12min 3s │ ✅ Complete    │
└─────────────┴──────────────┴─────────┴──────────┴─────────────┘

# Steer agent in new direction
subagents steer research-01 
  "Focus on papers with code implementations"

# Kill stuck or unnecessary agents  
subagents kill code-rev-02

# Get detailed status
subagents status research-01 --verbose

# Direct messaging between agents
sessions_send code-reviewer 
  "Please review the changes in commit abc123f"

# Broadcasting to multiple agents
sessions_broadcast writing-team
  "Style guide updated: use active voice, 1500-word max"

# Status updates with structured data
sessions_send orchestrator
  "{
    'task': 'backend-development', 
    'status': 'completed',
    'output_file': './src/api.py',
    'test_coverage': 95,
    'next_steps': ['frontend-integration', 'deployment']
  }"

# Research agent outputs structured findings
research-lead → outputs/research_findings.json
{
  "topic": "transformer optimization",
  "papers": [...],
  "key_insights": [...],
  "recommendations": [...]
}

# Writing agent consumes research data
technical-writer → read outputs/research_findings.json
technical-writer → generates/technical_report.md

# Code agents share implementation artifacts
backend-dev → src/models/transformer.py
frontend-dev → read src/models/ (for API integration)
test-engineer → tests/test_transformer.py (based on implementation)

# Memory layered by scope
Global Memory: Company coding standards, style guides
Project Memory: Current project context, decisions made  
Team Memory: Team-specific patterns, lessons learned
Agent Memory: Individual agent's learning and preferences

# Cross-pollination examples
code-reviewer learns from previous reviews → improves suggestions
research-lead remembers effective search strategies → better results
writer adapts style based on feedback → consistent voice

# State-based coordination
Project State: "research" → "design" → "implementation" → "testing" → "deployment"

# Event-driven triggers
on research_complete:
  spawn technical-writer "Write implementation guide"
  spawn ui-designer "Create user interface mockups"

on code_review_passed:
  spawn test-engineer "Run comprehensive test suite"
  spawn docs-writer "Update API documentation"

# Dependency management
backend_api.depends_on(database_schema, auth_system)
frontend_ui.depends_on(backend_api, design_mockups)
deployment.depends_on(backend_api, frontend_ui, tests_passed)

# Tech Lead Agent (Opus) analyzes requirements
Analysis:
- Backend API: Python FastAPI + transformers library
- Database: PostgreSQL for feedback storage  
- Frontend: React dashboard with Chart.js
- Infrastructure: Docker containerization
- Testing: Unit + integration + E2E tests

Architecture Decision:
- Microservices approach: API + Dashboard + DB
- CI/CD pipeline with GitHub Actions
- Monitoring with logging and metrics

# Output: architecture_plan.md

# Tech Lead spawns specialized agents simultaneously

subagents spawn backend-dev
  "Implement FastAPI backend for sentiment analysis:
   - Endpoint: POST /analyze with text input
   - Use huggingface transformers (sentiment-pipeline)
   - PostgreSQL models with SQLAlchemy  
   - Async processing for large batches
   - Input validation and error handling
   - OpenAPI documentation generation"

subagents spawn frontend-dev  
  "Build React sentiment dashboard:
   - Text input form for new feedback analysis
   - Real-time chart showing sentiment distribution
   - Historical trends visualization
   - Responsive design with Tailwind CSS
   - API integration with error handling
   - Loading states and user feedback"

subagents spawn db-specialist
  "Design database schema:
   - feedback table: id, text, sentiment, confidence, timestamp
   - users table: id, name, email (if needed)
   - indexes for performance on timestamp queries
   - Migration scripts with Alembic
   - Sample data for testing"

subagents spawn devops-engineer
  "Setup deployment infrastructure:
   - Dockerfile for FastAPI backend
   - Docker-compose for local development
   - GitHub Actions CI/CD pipeline  
   - Environment configuration management
   - Health check endpoints"

# Backend Developer Output
Files Created:
- src/main.py (FastAPI application)
- src/models.py (SQLAlchemy models)  
- src/sentiment.py (sentiment analysis logic)
- src/database.py (database connection)
- requirements.txt (dependencies)
- .env.example (environment template)

# Frontend Developer Output  
Files Created:
- src/App.js (main dashboard component)
- src/components/SentimentChart.js  
- src/components/FeedbackForm.js
- src/api/sentimentApi.js (API client)
- package.json (dependencies)
- tailwind.config.js (styling setup)

# Database Specialist Output
Files Created:
- migrations/001_initial_schema.sql
- migrations/002_add_indexes.sql  
- scripts/seed_sample_data.sql
- database_design.md (documentation)

# DevOps Engineer Output
Files Created:
- Dockerfile (backend container)
- docker-compose.yml (full stack)
- .github/workflows/ci.yml (CI pipeline)
- deploy.sh (deployment script)

# Tech Lead spawns code reviewer
subagents spawn code-reviewer
  "Review all code from backend, frontend, and devops teams:
   - Check adherence to coding standards
   - Security vulnerabilities scan  
   - Performance optimization suggestions
   - Integration compatibility review
   - Documentation completeness check"

# Code Reviewer Findings
Issues Found:
- Backend: Missing input validation on text length
- Frontend: No error boundary for API failures  
- Database: Missing foreign key constraints
- DevOps: Production secrets hardcoded

Recommendations:
- Add pydantic validators for input
- Implement React error boundaries
- Update database schema with constraints  
- Use environment variables for secrets

# Spawn testing agents after code review fixes

subagents spawn test-engineer
  "Create comprehensive test suite:
   - Backend: pytest with test_main.py, test_sentiment.py
   - Frontend: Jest tests for components
   - Integration: API endpoint testing
   - E2E: Playwright full user journey tests
   - Performance: Load testing with locust"

subagents spawn docs-writer  
  "Generate project documentation:
   - API documentation from OpenAPI spec
   - Frontend component documentation  
   - Deployment guide with step-by-step instructions
   - User manual for dashboard usage
   - Developer setup guide"

# Tech Lead coordinates final assembly
Integration Tasks:
- Merge all code into main repository
- Run complete test suite (all tests pass ✅)
- Deploy to staging environment  
- Smoke test critical user journeys
- Generate final project report

# Deliverables
Output Files:
- sentiment_analysis_api/ (complete codebase)
- docker-compose.yml (one-command setup)  
- README.md (comprehensive setup guide)
- API_DOCS.md (endpoint documentation)
- USER_GUIDE.md (dashboard usage)
- deployment_report.pdf (project summary)

# Total Time: ~45 minutes (vs 2-3 days for single developer)
# Quality: Enterprise-grade with comprehensive testing

# Workaround patterns ที่ใช้ได้
File-based coordination: agents write status to shared files
Message queues: use workspace files as message buffers  
Polling strategies: periodic check for updates (not ideal)
Gateway coordination: main agent as message broker

# Memory sharing strategies
Explicit context passing: include relevant memory in spawn messages
Shared knowledge files: maintain project_context.md 
Memory consolidation: periodic sync sessions between agents
Vector embeddings: use semantic search for knowledge retrieval

# Cost control measures
Max concurrent agents: limit to 5-10 simultaneously
Budget per task: set token limits for each spawned agent
Smart caching: reuse responses for similar tasks
Model tiering: use cheaper models for routine tasks
Monitoring: track costs in real-time with alerts

# Decision Framework
Use Multi-Agent When:
✅ Task complexity > 30 minutes of work
✅ Requires multiple skill sets  
✅ Quality is critical (code, research, publications)
✅ Parallel execution provides benefits
✅ Ongoing project with multiple iterations

Use Single Agent When:
❌ Task duration < 5 minutes
❌ Single domain expertise sufficient  
❌ Quick draft or exploratory work
❌ Simple Q&A or information lookup
❌ Real-time conversation requirements

1. Why One Agent Is Not Enough

Now that we have met OpenClaw in the first post, you have probably started using a single agent and found yourself thinking "okay, this is good, but…" — because something is still not right, is it?

The generalist AI problem: one agent that has to do everything is like one person being programmer, researcher, writer, designer and project manager all at once. It is good at many things, but not truly expert at any of them.

Consider what that costs:

• Task Switching Overhead: moving from coding mode to research mode to writing mode means a context switch every single time
• Quality Inconsistency: sometimes it writes good code, sometimes it writes a good research paper — but never dependably
• Memory Conflicts: context belonging to a coding project can interfere with research in an entirely different domain
• Prompt Engineering Complexity: the more jobs you hand it, the more tangled the instructions become — and sometimes confusing

This is exactly why no real company puts one employee on everything — they build teams of specialists instead

2. Multi-Agent Architecture — How the Work Gets Divided

Multi-Agent Architecture is not simply having several AIs around. It is designing a system of intelligent agents in which each one has a specialization and they collaborate to get complex work done

Core Concepts:

🎭 Agent Specialization: each agent carries the domain expertise and the personality that its work calls for — a research agent that is strong at finding and synthesizing information, say, or a code-review agent with a deep grasp of coding standards

🎯 Orchestrator Pattern: a main agent, or orchestrator, acts as project manager: it takes the request from the user, breaks it into subtasks, and delegates each one to the right specialist

📡 Communication Protocol: agents talk to each other through structured messages, shared files in the workspace, and shared memory — so knowledge earned on one job can be spent on another

🧠 Collective Intelligence: the team's combined result is usually better than what a single agent produces, because of the diverse perspectives and specialized knowledge in the room

Compared with a team of people:

3. Agent Team Architecture

OpenClaw Multi-Agent Implementation:

📊 sessions_spawn: the main function for creating sub-agents — you give it a label, a model, instructions, and a mode (run vs session)

# Spawn specialized agents
subagents spawn research-lead "Academic research on transformer optimization"
subagents spawn code-review "Review Python ML pipeline code"
subagents spawn docs-writer "Document API endpoints"

# Check running agents
subagents list

# Steer agent direction
subagents steer research-lead "Focus on recent 2024 papers"

# Terminate when done
subagents kill docs-writer

🔄 Workflow Orchestration: the main agent takes a complex request → breaks it into subtasks → spawns the appropriate specialists → monitors progress → combines the results → delivers the final output

💾 Memory Sharing: agents share workspace files and the memory system, so what the research agent produces is available to the writing agent

⚡ Parallel Execution: multiple agents working in parallel cut total execution time dramatically

4. Designing a Team — Real Examples

From using OpenClaw across a number of organizations, we have identified the team patterns that are effective and hold up in practice. These are the five core teams that have proven themselves:

5. Model Routing & Cost Optimization

One of the decisive questions in a multi-agent architecture is picking the right AI model for each job — good quality at a cost that stays reasonable

Model Selection Strategy:

🧠 Claude Opus (Complex Reasoning):

• Orchestrator agents that have to plan and divide the work
• Code review and architecture decisions
• Research coordination and methodology design
• Quality assurance and final review
• Complex problem solving and creative tasks

⚡ Claude Sonnet (Execution & Routine):

• Content writing and documentation
• Code implementation and testing
• Data processing and analysis
• Translation and formatting
• Repetitive tasks and standard procedures

Cost Analysis Example (Monthly):

# Organization with active agent teams
Research Team: ~200K tokens/day × 30 days × $0.045 avg = $270/month
Coding Team: ~150K tokens/day × 22 workdays × $0.025 avg = $82.5/month
Writing Team: ~100K tokens/day × 30 days × $0.020 avg = $60/month

# Total estimated monthly cost: ~$412.5
# Compared to 2 full-time employees: ~$8,000+/month
ROI: 20x cost savings with 24/7 availability

Cost Optimization Strategies:

• Smart Caching: keep common responses and reuse them when a similar query turns up
• Batch Processing: group similar tasks so one agent handles them together
• Progressive Enhancement: start with Sonnet and escalate to Opus only when you have to
• Context Optimization: strip unnecessary context out of prompts
• Task Complexity Assessment: size up the work before choosing the model

6. sessions_spawn in Practice

Spawning sub-agents is the core feature that gives OpenClaw its multi-agent capabilities. These are the patterns and best practices that came out of real use:

Basic Spawning Patterns:

# run-and-return style (fire-and-forget)
subagents spawn research-lead
  "Research transformer optimization papers from 2024"
  --mode run --timeout 600

# interactive session style
subagents spawn code-reviewer
  "Review the ML pipeline code in ./src/"
  --mode session --label "code-review-v1"

# batch processing style
subagents spawn translator
  "Translate all .md files in ./docs/ to Thai"
  --mode run --label "docs-translation"

Orchestrator Delegation Example:

# Main orchestrator receives complex request
User: "Build a customer feedback analysis dashboard"

# Orchestrator analyzes and delegates
subagents spawn tech-lead
  "Design architecture for feedback analysis dashboard
   - React frontend with data visualization
   - Python backend with NLP sentiment analysis
   - Database schema for feedback storage
   - API design for frontend-backend communication"

# Tech-lead further delegates to specialists
subagents spawn backend-dev
  "Implement Python FastAPI backend:
   - Sentiment analysis endpoint using transformers
   - CRUD operations for feedback data
   - Database models with SQLAlchemy
   - Authentication and rate limiting"

subagents spawn frontend-dev
  "Build React dashboard:
   - Responsive layout with Tailwind CSS
   - Charts using Chart.js or D3
   - Real-time updates via WebSocket
   - Filtering and search functionality"

subagents spawn test-engineer
  "Create comprehensive test suite:
   - Unit tests for backend API endpoints
   - Integration tests for database operations
   - Frontend component testing with Jest
   - End-to-end testing with Playwright"

Advanced Patterns:

# Conditional spawning based on results
if research_findings.confidence_score < 0.8:
    subagents spawn fact-checker
      "Verify claims in research report: ${findings_file}"

# Sequential dependency chains
research_done = subagents spawn research-lead --wait
design_done = subagents spawn ui-designer
  "Design based on: ${research_done.output_file}" --wait
subagents spawn frontend-dev
  "Implement: ${design_done.mockups}"

# Parallel execution with synchronization
content_team = [
  subagents spawn writer --label "content-writer",
  subagents spawn editor --label "content-editor",
  subagents spawn designer --label "visual-designer"
]
subagents wait content_team
subagents spawn publisher "Combine all content outputs"

Monitoring & Control:

# Check all running sub-agents
subagents list
┌─────────────┬──────────────┬─────────┬──────────┬─────────────┐
│ ID          │ Label        │ Status  │ Runtime  │ Progress    │
├─────────────┼──────────────┼─────────┼──────────┼─────────────┤
│ research-01 │ literature   │ running │ 5min 23s │ 📚 Paper 15/30 │
│ code-rev-02 │ backend      │ running │ 2min 45s │ 🔍 Function 8/12│
│ writer-03   │ documentation│ done    │ 12min 3s │ ✅ Complete    │
└─────────────┴──────────────┴─────────┴──────────┴─────────────┘

# Steer agent in new direction
subagents steer research-01
  "Focus on papers with code implementations"

# Kill stuck or unnecessary agents
subagents kill code-rev-02

# Get detailed status
subagents status research-01 --verbose

7. Communication Patterns

Agent-to-agent communication is the heart of a multi-agent system. Design the communication patterns well and the team of agents genuinely works together

🔄 Message Passing Patterns:

# Direct messaging between agents
sessions_send code-reviewer
  "Please review the changes in commit abc123f"

# Broadcasting to multiple agents
sessions_broadcast writing-team
  "Style guide updated: use active voice, 1500-word max"

# Status updates with structured data
sessions_send orchestrator
  "{
    'task': 'backend-development',
    'status': 'completed',
    'output_file': './src/api.py',
    'test_coverage': 95,
    'next_steps': ['frontend-integration', 'deployment']
  }"

📁 File-based Communication:

Agents share artifacts through workspace files — a method that is both reliable and persistent:

# Research agent outputs structured findings
research-lead → outputs/research_findings.json
{
  "topic": "transformer optimization",
  "papers": [...],
  "key_insights": [...],
  "recommendations": [...]
}

# Writing agent consumes research data
technical-writer → read outputs/research_findings.json
technical-writer → generates/technical_report.md

# Code agents share implementation artifacts
backend-dev → src/models/transformer.py
frontend-dev → read src/models/ (for API integration)
test-engineer → tests/test_transformer.py (based on implementation)

🧠 Shared Memory Patterns:

Memory sharing lets agents learn from each other's work and hold context across sessions:

# Memory layered by scope
Global Memory: Company coding standards, style guides
Project Memory: Current project context, decisions made
Team Memory: Team-specific patterns, lessons learned
Agent Memory: Individual agent's learning and preferences

# Cross-pollination examples
code-reviewer learns from previous reviews → improves suggestions
research-lead remembers effective search strategies → better results
writer adapts style based on feedback → consistent voice

⚙️ Workflow Coordination:

# State-based coordination
Project State: "research" → "design" → "implementation" → "testing" → "deployment"

# Event-driven triggers
on research_complete:
  spawn technical-writer "Write implementation guide"
  spawn ui-designer "Create user interface mockups"

on code_review_passed:
  spawn test-engineer "Run comprehensive test suite"
  spawn docs-writer "Update API documentation"

# Dependency management
backend_api.depends_on(database_schema, auth_system)
frontend_ui.depends_on(backend_api, design_mockups)
deployment.depends_on(backend_api, frontend_ui, tests_passed)

8. A Real Example: The Coding Team Pipeline

Let us walk a Coding Team through a job from start to finish, so the shape of a multi-agent workflow becomes concrete:

📋 Initial Request:

User: "Build an API for sentiment analysis of customer feedback, with a dashboard to display the results"

🎯 Step 1: Tech Lead Planning

# Tech Lead Agent (Opus) analyzes requirements
Analysis:
- Backend API: Python FastAPI + transformers library
- Database: PostgreSQL for feedback storage
- Frontend: React dashboard with Chart.js
- Infrastructure: Docker containerization
- Testing: Unit + integration + E2E tests

Architecture Decision:
- Microservices approach: API + Dashboard + DB
- CI/CD pipeline with GitHub Actions
- Monitoring with logging and metrics

# Output: architecture_plan.md

⚡ Step 2: Parallel Delegation

# Tech Lead spawns specialized agents simultaneously

subagents spawn backend-dev
  "Implement FastAPI backend for sentiment analysis:
   - Endpoint: POST /analyze with text input
   - Use huggingface transformers (sentiment-pipeline)
   - PostgreSQL models with SQLAlchemy
   - Async processing for large batches
   - Input validation and error handling
   - OpenAPI documentation generation"

subagents spawn frontend-dev
  "Build React sentiment dashboard:
   - Text input form for new feedback analysis
   - Real-time chart showing sentiment distribution
   - Historical trends visualization
   - Responsive design with Tailwind CSS
   - API integration with error handling
   - Loading states and user feedback"

subagents spawn db-specialist
  "Design database schema:
   - feedback table: id, text, sentiment, confidence, timestamp
   - users table: id, name, email (if needed)
   - indexes for performance on timestamp queries
   - Migration scripts with Alembic
   - Sample data for testing"

subagents spawn devops-engineer
  "Setup deployment infrastructure:
   - Dockerfile for FastAPI backend
   - Docker-compose for local development
   - GitHub Actions CI/CD pipeline
   - Environment configuration management
   - Health check endpoints"

🔄 Step 3: Parallel Development (30 minutes)

# Backend Developer Output
Files Created:
- src/main.py (FastAPI application)
- src/models.py (SQLAlchemy models)
- src/sentiment.py (sentiment analysis logic)
- src/database.py (database connection)
- requirements.txt (dependencies)
- .env.example (environment template)

# Frontend Developer Output
Files Created:
- src/App.js (main dashboard component)
- src/components/SentimentChart.js
- src/components/FeedbackForm.js
- src/api/sentimentApi.js (API client)
- package.json (dependencies)
- tailwind.config.js (styling setup)

# Database Specialist Output
Files Created:
- migrations/001_initial_schema.sql
- migrations/002_add_indexes.sql
- scripts/seed_sample_data.sql
- database_design.md (documentation)

# DevOps Engineer Output
Files Created:
- Dockerfile (backend container)
- docker-compose.yml (full stack)
- .github/workflows/ci.yml (CI pipeline)
- deploy.sh (deployment script)

🔍 Step 4: Code Review & Integration

# Tech Lead spawns code reviewer
subagents spawn code-reviewer
  "Review all code from backend, frontend, and devops teams:
   - Check adherence to coding standards
   - Security vulnerabilities scan
   - Performance optimization suggestions
   - Integration compatibility review
   - Documentation completeness check"

# Code Reviewer Findings
Issues Found:
- Backend: Missing input validation on text length
- Frontend: No error boundary for API failures
- Database: Missing foreign key constraints
- DevOps: Production secrets hardcoded

Recommendations:
- Add pydantic validators for input
- Implement React error boundaries
- Update database schema with constraints
- Use environment variables for secrets

🧪 Step 5: Testing & Quality Assurance

# Spawn testing agents after code review fixes

subagents spawn test-engineer
  "Create comprehensive test suite:
   - Backend: pytest with test_main.py, test_sentiment.py
   - Frontend: Jest tests for components
   - Integration: API endpoint testing
   - E2E: Playwright full user journey tests
   - Performance: Load testing with locust"

subagents spawn docs-writer
  "Generate project documentation:
   - API documentation from OpenAPI spec
   - Frontend component documentation
   - Deployment guide with step-by-step instructions
   - User manual for dashboard usage
   - Developer setup guide"

✅ Step 6: Final Integration & Delivery

# Tech Lead coordinates final assembly
Integration Tasks:
- Merge all code into main repository
- Run complete test suite (all tests pass ✅)
- Deploy to staging environment
- Smoke test critical user journeys
- Generate final project report

# Deliverables
Output Files:
- sentiment_analysis_api/ (complete codebase)
- docker-compose.yml (one-command setup)
- README.md (comprehensive setup guide)
- API_DOCS.md (endpoint documentation)
- USER_GUIDE.md (dashboard usage)
- deployment_report.pdf (project summary)

# Total Time: ~45 minutes (vs 2-3 days for single developer)
# Quality: Enterprise-grade with comprehensive testing

9. Limitations and Lessons Learned

After several months of running multi-agent systems on real projects, we have learned the limitations and the challenges worth knowing before you begin:

🔒 Sandbox Limitations

Isolation Problems: sub-agents run in sandbox environments that are separated from one another, which makes sharing state and coordinating harder than it looks

• File sharing happens through the workspace only — there is no direct shared memory
• Network access is limited — agents cannot reach every external service
• Process isolation — agents cannot monitor or control each other directly

# Workaround patterns that do work
File-based coordination: agents write status to shared files
Message queues: use workspace files as message buffers
Polling strategies: periodic check for updates (not ideal)
Gateway coordination: main agent as message broker

💾 Memory Isolation Issues

Context Loss: every agent has its own memory context, so transferring knowledge between agents is never seamless

• Agent A learns a new pattern, but Agent B never receives that knowledge
• Conversation history does not carry over between different agents
• Global project context has to be maintained by hand

# Memory sharing strategies
Explicit context passing: include relevant memory in spawn messages
Shared knowledge files: maintain project_context.md
Memory consolidation: periodic sync sessions between agents
Vector embeddings: use semantic search for knowledge retrieval

💰 Cost Control Challenges

Exponential Cost Growth: a multi-agent system can eat API budget exponentially if you are not careful

• Agent spawning with no upper bounds
• Recursive delegation with no termination conditions
• Over-communication between agents
• Inefficient prompt engineering that burns far too many tokens

# Cost control measures
Max concurrent agents: limit to 5-10 simultaneously
Budget per task: set token limits for each spawned agent
Smart caching: reuse responses for similar tasks
Model tiering: use cheaper models for routine tasks
Monitoring: track costs in real-time with alerts

🤖 When NOT to Use Multi-Agent

Multi-agent architecture is not a silver bullet. Sometimes a single agent, or a traditional approach, is simply better:

❌ Over-engineering Scenarios:

• Simple tasks: translating one sentence does not call for a translation team
• Linear workflows: work that has to proceed one sequential step at a time
• Single-domain tasks: work that needs no cross-functional expertise
• Time-sensitive: setting the agents up may take longer than doing it yourself
• Low-stakes outputs: draft emails and quick notes — a simple agent is plenty

# Decision Framework
Use Multi-Agent When:
✅ Task complexity > 30 minutes of work
✅ Requires multiple skill sets
✅ Quality is critical (code, research, publications)
✅ Parallel execution provides benefits
✅ Ongoing project with multiple iterations

Use Single Agent When:
❌ Task duration < 5 minutes
❌ Single domain expertise sufficient
❌ Quick draft or exploratory work
❌ Simple Q&A or information lookup
❌ Real-time conversation requirements

🔧 Technical Complexity

Debugging Nightmares: when eight agents are working at once, debugging a problem gets very hard

• You do not know which agent the problem came from
• Logs are scattered across multiple sessions
• Timing issues and race conditions
• Dependency hell between agents

10. Key Takeaways