Orchestration

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Orchestration là lớp đa agent có cấu trúc của Orca: một Run (namespace + inbox coordinator), Task, Dispatch, worker được giám sát, message, và decision gate.

Dùng nó khi bạn cần quyền sở hữu, theo dõi hoàn thành, hoặc một DAG. Với prompt một lần, dùng orca terminal send. Với việc bàn giao toàn quyền sở hữu mà không cần giám sát, dùng lệnh worktree/terminal từ skill orca-cli.

Mô hình cốt lõi

Run - namespace và inbox nhà bền vững. Không bao giờ tự lên lịch hay đặt worker.
Task - một work item có spec, dependency, và trạng thái: pending, ready, dispatched, completed, failed, hoặc blocked.
Dispatch - một lần thử của một task trên một terminal; là thẩm quyền vòng đời cho worker_done / heartbeat.
Message - thư trong inbox (status, dispatch, worker_done, escalation, question, heartbeat, …).
Decision gate - một câu hỏi do coordinator sở hữu, chặn một task cho tới khi được giải quyết.

Thẩm quyền hoàn thành đến từ context dispatch đang active. Message worker completion và heartbeat nên gồm cả taskId lẫn dispatchId.

ID task in trên terminal, như task_..., là link click được. Click vào đó hỏi runtime Orca về dispatch hiện tại của task và focus vào terminal được gán, kể cả khi task nằm trên một runtime remote hoặc SSH.

Vòng lặp giám sát ưu tiên

orca orchestration run-create --objective "Split checkout QA and summarize blockers" --json
orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
orca orchestration worker-start --task <taskId> --worktree current --agent codex --json
# hoặc worktree mới:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# tuỳ chọn model / effort riêng cho worker (chỉ Claude, Codex, Cursor; không dùng cùng --terminal):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json

--model chấp nhận ID model opaque của provider cho Claude, Codex, và Cursor. --effort cần --model và chỉ áp dụng khi agent/model đó hỗ trợ mức đó. Cả hai flag không kết hợp được với --terminal (dùng lại một pane có sẵn). Override chỉ áp dụng cho lần khởi chạy đó và hiện dưới launch.requested / launch.effective trong receipt khởi động. Khởi động kiểu federated cần một worker host công bố hỗ trợ launch-preference.

Chờ hoàn thành (xử lý mọi message trong một Delivery, rồi ack):

orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
orca orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

Worker completion (từ pane worker; kèm ID đã inject):

orca orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx" \
  --json

worker_done yêu cầu --outcome succeeded|failed.

Kiểm tra / khôi phục:

orca orchestration worker-show --dispatch <dispatchId> --json
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
orca orchestration worker-stop --dispatch <dispatchId> --json
# Sau một worker_done đã accept: dùng lại cùng terminal cho một Dispatch tiếp theo, hoặc release nó
# (archive output có thể kiểm tra được, rồi chỉ đóng terminal agent do coordinator sở hữu đó):
orca orchestration worker-release --dispatch <dispatchId> --json
# Giữ một worker đã settle vẫn sống để debug khi user yêu cầu giữ lại:
orca orchestration worker-retain --dispatch <dispatchId> --json
# việc đặt lại retry tường minh - --retry-of không kế thừa --on/worktree:
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json

Đừng để terminal worker đã xong việc mở chỉ để đọc lại output - dùng worker-read sau worker-release. Đừng thay bằng một terminal close chung chung khi release trả về release_pending hoặc release_unknown; làm theo action khôi phục trong receipt.

Worker federated (tuỳ chọn)

orca orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json

Các lệnh sau định tuyến theo Dispatch ID; không lặp lại --on.

Dispatch cấp thấp (topology tuỳ chỉnh)

orca worktree create --name billing-audit --agent codex --json
orca terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <taskId> --to <workerHandle> --inject --json

Ghi chú về messaging

check mặc định là Delivery cũ nhất chưa ack của Run đang gắn. Replay cho tới khi --ack.
--peek / --all không tiêu thụ thư.
Địa chỉ nhóm: @all, @idle, @claude, @codex, @opencode, @gemini, @droid, @grok, @cursor, @worktree:<id> - không bao giờ dùng cho worker_done / heartbeat.
Đóng ngoặc kép địa chỉ nhóm trong PowerShell: --to "@all".

orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
orca orchestration send --to @idle --subject "Anyone free?" --json
orca orchestration send --to @codex --subject "Codex agents only" --json

Trong lúc một wait đang active, CLI phát ra các dòng heartbeat JSON nhỏ vào stderr mỗi 15 giây. Stdout vẫn là kết quả lệnh cuối cùng.

Hợp đồng với worker

Worker được dispatch nhận một preamble hướng dẫn cách giao tiếp với coordinator:

Gửi worker_done đúng một lần, kể cả khi thất bại, kèm --outcome.
Kèm một --body tóm tắt ngắn: đã làm gì, phát hiện gì, và còn lại gì.
Kèm cả task ID lẫn dispatch ID để các lần retry cũ không hoàn thành nhầm dispatch.
Gửi message heartbeat trong lúc làm việc chạy dài.
Dùng orca orchestration ask cho câu hỏi cần chặn thay vì prompt TUI local.

orca orchestration ask \
  --to <coordinatorHandle> \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

Với --json, ask in ra một object JSON duy nhất để worker có thể pipe vào jq -r .answer.

Decision gate

Dùng ask cho câu hỏi worker gửi tới coordinator. Dùng gate tường minh khi coordinator đã tạo một task DAG và muốn chặn một task cho tới khi có quyết định được ghi lại:

orca orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]' \
  --json

orca orchestration gate-resolve --id <gateId> --resolution "yes" --json

Khôi phục

orca orchestration dispatch-show --task <taskId> --json
orca orchestration dispatch-show --task <taskId> --preamble --json
orca orchestration task-list --json
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json

Chỉ reset khi bạn chủ đích bỏ hẳn state orchestration:

orca orchestration reset --tasks --json
orca orchestration reset --messages --json
orca orchestration reset --all --json

reset ảnh hưởng tới state orchestration toàn cục của runtime. Đừng chạy nó khi một coordinator khác đang active, trừ khi đó chính là mục đích dọn dẹp.

Chọn đúng lệnh

Dùng orca terminal send cho một prompt nhẹ tới agent bạn đang theo dõi trực tiếp.

Dùng orca orchestration worker-start (hoặc dispatch --inject) khi một worker phải báo worker_done, hỏi qua coordinator, và được theo dõi bằng task ID.

Dùng orca orchestration run-create + task + worker khi bạn muốn một namespace Run bền vững và một vòng lặp đa agent được giám sát - không phải lệnh orchestration run đã bị gỡ.

Hướng dẫn đầy đủ

Flag lệnh thay đổi theo app. Sau khi cài, agent nên chạy:

orca skills get orchestration --full

Phuc Tran

Software Engineer | Learning Claude