🤖 Multi-Agent Orchestration

👤 Who it's for: Developers / integrators
⏱️ Read time: ~8 minutes
💡 In one line: Multiple AIs collaborate like a team — more reliable and faster than a single AI.

Multi-agent orchestration is one of YingClaw's core features: automatically decompose complex tasks into subtasks, executed in parallel by multiple sub-agents, dramatically improving efficiency and throughput.

Core Concept

Each sub-agent has an isolated context and toolset — they don't interfere with one another, and the main agent only consumes the aggregated result.

Mandatory Four-Phase Workflow

Every complex task in YingClaw goes through four phases:

Phase	Tool	Output
1️⃣ Requirement Clarification	Conversation	Clear task description and constraints
2️⃣ Project Assessment	assess_workload	File count, size, complexity analysis
3️⃣ Plan Confirmation	todo	Step-by-step execution plan with unique IDs
4️⃣ Parallel Execution	delegate	Multiple sub-agents executing subtasks in parallel

Sub-Agent Types

Type	Role	Use Case
assistant	General assistant	Code review, document generation, data analysis
sales_manager	CRM management	Customer relationship management, sales process
sales_lead_only	Lead specialist	Lead discovery and follow-up

Core Tools

delegate — Dispatch Execution

Delegate subtasks to one or more sub-agents for parallel execution.

// Parallel delegation to multiple sub-agents
delegate({
  prompt: "Review the authentication module under src/auth/",
  agents: [
    { role: "Security Reviewer", task: "Check for security vulnerabilities" },
    { role: "Performance Analyst", task: "Analyze performance bottlenecks" },
    { role: "Documentation Checker", task: "Verify documentation completeness" }
  ]
})

todo — Task Tracking

Automatically manage task state transitions.

// Create a task plan
todo({
  todos: [
    { id: "step-1", content: "Scan project structure", status: "pending" },
    { id: "step-2", content: "Analyze dependencies", status: "pending" },
    { id: "step-3", content: "Generate optimization suggestions", status: "pending" }
  ]
})

Complete Example

This example shows the full delegate + todo workflow:

// Scenario: Comprehensive code review of a project

// Phase 2: Assess the project
assess_workload({ path: "src/" })
// → { files: 45, total_size_kb: 320, complexity: "medium" }

// Phase 3: Create a plan
todo({
  merge: false,
  todos: [
    { id: "s1", content: "Security review: Auth & authorization", status: "pending" },
    { id: "s2", content: "Performance: DB queries & caching", status: "pending" },
    { id: "s3", content: "Code style: Naming & structure", status: "pending" },
    { id: "s4", content: "Test coverage: Unit test completeness", status: "pending" }
  ]
})

// Phase 4: Parallel execution
delegate({
  prompt: "Comprehensive code review of src/",
  agents: [
    { role: "Security Expert", task: "Review auth, authorization, input validation" },
    { role: "Performance Engineer", task: "Analyze DB queries, N+1 issues, cache strategy" },
    { role: "Code Reviewer", task: "Check naming, structure, comment conventions" },
    { role: "Test Engineer", task: "Check test coverage, edge cases" }
  ]
})

// Todo statuses update automatically during execution:
// s1: pending → in_progress → completed
// s2: pending → in_progress → completed
// s3: pending → in_progress → completed
// s4: pending → in_progress → completed

Key Parameters

Parameter	Type	Description
prompt	string	Main task description
agents	array	List of sub-agents, each with role and task
role	string	Custom sub-agent role
max_iterations	number	Max tool invocation iterations per sub-agent
max_depth	number	Max depth for recursive agent delegation

Best Practices

Practice	Description
🎯 Small, focused subtasks	Each sub-agent handles one clear, small task
🔀 Parallelize independent steps	Execute independent subtasks simultaneously for maximum efficiency
📊 Update status promptly	Mark subtasks complete immediately for a clear global view
🛑 Set iteration limits	Use max_iterations to prevent infinite loops
💰 Control costs	Keep parallel agents to 5 or fewer, balancing efficiency and API cost

Next Steps

Multi-agent orchestration breaks complex tasks into manageable pieces. Dive deeper into 🔄 Workflow Engine for task lifecycle and error handling.