Series 4 - Bài 2: Orchestrator Pattern

Orchestrator Pattern là pattern phổ biến nhất trong multi-agent system — và cũng là pattern dễ implement sai nhất.

Sai lầm phổ biến nhất: để orchestrator làm cả orchestration lẫn execution. Một orchestrator tốt không làm gì ngoài plan và coordinate.

Pattern overview

         User
          │
          ▼
 ┌───────────────────┐
 │   ORCHESTRATOR   │
 │                  │
 │  Nhận task       │
 │  Tạo plan        │
 │  Delegate tasks  │
 │  Monitor results │
 │  Aggregate và    │
 │  synthesize      │
 └─────┬─────┬─────┘
        │         │
  delegate    delegate
        │         │
        ▼         ▼
 ┌──────────┐ ┌──────────┐
 │  WORKER A │ │  WORKER B │
 │           │ │           │
 │  Executes │ │  Executes │
 │  specific │ │  specific │
 │  subtask  │ │  subtask  │
 └──────────┘ └──────────┘

Orchestrator: Vai trò và giới hạn

Orchestrator làm chỉ những việc này:

1. Task Analysis:
   Nhận user request
   Understand độ phức tạp và scope
   Quyết định có cần phân tận không

2. Planning:
   Break task thành subtasks
   Xác định dependencies giữa subtasks
   Quyết định order và parallelism

3. Delegation:
   Chọn worker đúng cho từng subtask
   Format task description rõ ràng
   Set expectations và output format

4. Monitoring:
   Track progress của từng worker
   Phát hiện khi worker stuck hoặc fail
   Quyết định retry hay escalate

5. Synthesis:
   Tổng hợp kết quả từ nhiều workers
   Resolve conflicts giữa outputs
   Generate final response cho user

Orchestrator không làm:

• Thực thi bất kỳ task cụ thể nào
• Đọc files, chạy commands
• Làm domain work

Worker Agents: Specialized execution

Worker Design:

  Mỗi worker có:
  • Specialized system prompt (domain expert)
  • Specific tool set (chỉ có tools cần cho domain)
  • Clear input format (từ orchestrator)
  • Clear output format (trả về orchestrator)

Ví dụ:

  Backend Worker:
    Tools: read_file, write_file, run_command, search_files
    System: "Expert NestJS engineer. Focus on correctness."
    Input: { task, files_to_modify, constraints }
    Output: { files_changed, summary, tests_passed }

  Security Worker:
    Tools: read_file, search_files, grep_content
    System: "Security auditor. Focus on vulnerabilities."
    Input: { files_to_audit, risk_areas }
    Output: { issues, severity, recommendations }

Orchestrator System Prompt: Khác với worker

Orchestrator system prompt tập trung vào:

  Role:
  "You are a technical project manager for code tasks.
   You do NOT write code or modify files directly.
   Your job: analyze, plan, delegate, synthesize."

  Planning guidance:
  "Break tasks into independent subtasks when possible.
   Identify dependencies — what must complete before what.
   Choose the right specialist for each subtask."

  Delegation format:
  "When delegating, always specify:
   - Clear task description
   - Files relevant to the subtask
   - Expected output format
   - Constraints from user"

  Synthesis guidance:
  "When aggregating results:
   - Verify consistency between worker outputs
   - Highlight conflicts for user attention
   - Summarize what was done and what wasn't"

Communication Protocol: Format hóa handoff

Việc orchestrator-worker communicate phải có format rõ ràng:

Orchestrator → Worker (Task Assignment):
{
  task_id: "task_001",
  type: "code_refactor",
  description: "Refactor processLoan() in loan.service.ts
                to handle edge case when amount = 0.",
  relevant_files: ["src/loan/loan.service.ts",
                   "src/loan/loan.service.spec.ts"],
  constraints: [
    "Do not add new dependencies",
    "Run tests after changes",
    "Keep function signature unchanged"
  ],
  expected_output_format: {
    files_modified: ["list of files"],
    summary: "what was done",
    tests_result: "pass/fail with details",
    issues_found: ["anything unexpected"]
  }
}

Worker → Orchestrator (Task Result):
{
  task_id: "task_001",
  status: "success",
  files_modified: ["src/loan/loan.service.ts",
                   "src/loan/loan.service.spec.ts"],
  summary: "Added guard clause for amount <= 0.
            Returns InvalidAmountError.",
  tests_result: "pass: 52/52 tests",
  issues_found: ["Found unrelated TODO comment
                  at line 89, left as-is"]
}

Format hóa handoff giảm ambiguity và giúp orchestrator synthesize chính xác hơn.

Orchestrator Tools

Orchestrator có tool set khác worker:

Orchestrator tools:

  delegate_task(worker_type, task_spec) → task_id
    Gửi task cho một worker loại cụ thể

  get_task_status(task_id) → status | result
    Check task đã xong chưa

  list_available_workers() → worker types
    Biết được specializations có sẵn

  request_clarification(question) → user answer
    Hỏi user khi task ambiguous

  report_progress(summary) → void
    Update user về tiến độ

Không có read_file, write_file trong orchestrator. Nếu orchestrator có các tools này, nó sẽ bị tempted để làm execution work — phá vỡ separation.

Trade-off: Centralized Orchestrator vs Decentralized

Centralized Orchestrator (một orchestrator, nhiều workers):
  + Clear authority
  + Dễ debug (một điểm quyết định)
  + Consistent planning
  - Single point of failure
  - Orchestrator có thể trở thành bottleneck
  - Khó scale khi nhiều tasks concurrent

Decentralized (workers tự coordinate):
  + Không có central bottleneck
  + Scale tốt hơn
  - Khó debug (không có single execution path)
  - Conflict resolution phức tạp
  - Nhất quán khó đảm bảo

Với một số lượng workers nhỏ (≤8), centralized orchestrator là đơn giản hơn và reliable hơn. Chỉ cân nhắc decentralized khi scale thực sự đòi hỏi.

Kết luận

• Orchestrator chỉ làm: plan, delegate, monitor, synthesize. Không làm execution.
• Workers chuyên biệt: system prompt, tools, input/output format rõ ràng.
• Format hóa handoff (task assignment và result) giảm ambiguity và tăng orchestration quality.
• Orchestrator tools khác worker tools — không có execution tools trong orchestrator.
• Centralized orchestrator đơn giản hơn cho small systems — decentralized chỉ khi có real scale need.