ak orchestrate start

Launch một run mới đã được orchestrate từ file job graph đã validate với run ID mới, worker detached, sở hữu process group và chứng minh readiness bền vững.

Dùng ak orchestrate start để validate file job graph, sinh run ID opaque mới, và spawn một worker detached sở hữu process group của mọi job trong run đó. Lệnh block đến khi worker durably persist run state và chứng minh readiness, rồi in run ID và status ban đầu.

start luôn tạo run mới; retry cùng graph không tái dùng run ID cũ. Chỉ ak orchestrate resume mới tiếp tục một run có sẵn.

Cách dùng

ak orchestrate start <job-graph.json>

Cung cấp đúng một argument theo vị trí — path tới file JSON mô tả job graph. File được validate trước khi worker được spawn; graph không hợp lệ thoát với mã 1 và không có run state nào được ghi.

Cờ của lệnh

Các cờ dùng chung (--json, --no-interactive, --quiet, --verbose, --yes) được mô tả trong quy ước CLI. --json ngầm định --no-interactive và trả về envelope một object phù hợp để script trích xuất run-id.

Validate job graph

File graph phải cung cấp, cho mỗi job:

id — định danh opaque duy nhất trong graph.
command — executable để chạy.
args — array argument.
work_dir — working directory để launch.
env — mapping environment.
depends_on — id các job phải hoàn tất trước.

Validate là schema-strict. Field sai dạng, chu trình trong depends_on, hoặc job id không xác định sẽ từ chối graph trước khi worker được spawn.

Tác động filesystem

Khi launch thành công, worker ghi:

AGENTKIT_HOME/orchestrate/runs/<run-id>/state.json — run state bền vững.
AGENTKIT_HOME/orchestrate/runs/<run-id>/jobs/<job-id>/stdout.log và stderr.log — output bounded từng job.
AGENTKIT_HOME/orchestrate/runs/<run-id>/launch-graph.json — digest graph chính xác gắn với run này.
Một control socket dùng bởi ak orchestrate status, ak orchestrate resume và ak orchestrate stop.

Worker không persist prompt, argv thô, giá trị environment, hay secret ngoài những gì graph chỉ định capture.

Đầu ra dành cho người dùng và JSON

Thành công dạng người dùng in run ID và status ban đầu từng job. --json trả về:

{
  "action": "start",
  "run_id": "<opaque>",
  "graph_digest": "sha256:<hex>",
  "jobs": [
    { "id": "<job-id>", "state": "queued" }
  ]
}

Kết quả và mã thoát

Mã thoát	Ý nghĩa	Bước tiếp theo an toàn
`0`	Worker đã đạt readiness và persist run state.	Poll bằng `ak orchestrate status <run-id>`.
`1`	Job graph không hợp lệ hoặc worker không đạt được readiness.	Sửa graph hoặc đọc lý do được báo; không có run state nào được để lại khi validate thất bại.
`2`	Parse cờ thất bại.	Sửa các cờ.
`3`	Bị interrupt trước readiness.	Kiểm tra `AGENTKIT_HOME/orchestrate/runs/` xem run có bị dở dang không; chạy lại khi sẵn sàng.
`6`	Nền tảng không hỗ trợ (v1 yêu cầu Darwin).	Dùng subprocess do coordinator sở hữu trên nền tảng ngoài Darwin.

Xác minh launch

ak orchestrate status <run-id>

Đọc control socket của worker live để xác nhận process group vẫn sống dưới cùng identity đã verify mà start ghi lại.