cargo-orchestration

Cargo CLI — 編排

Cargo 平台的執行時期操作。

你想執行什麼？

需要執行某個東西？
├── 一個動作，一筆記錄       → action execute
├── 一個動作，多筆記錄       → action execute-batch
├── 多個動作串聯
│   ├── 一次性 / 臨時        → run create --nodes (一筆記錄)
│   │                          batch create --nodes (多筆記錄)
│   └── 可重複使用的工作流程  → 建立一個 tool，然後執行 run create --workflow-uuid
│                             或 batch create --workflow-uuid
└── 對話式 AI 代理           → message create

術語： 一個編排 tool 是已儲存的隨選工作流程（透過 tool list 列出）。一個 action 是單一操作，你無需建立工作流程即可執行——它可以嵌入已儲存的編排工具（kind: "tool"）、呼叫第三方連接器（kind: "connector"）、呼叫 AI 代理（kind: "agent"），或執行內建平台操作（kind: "native"）。

正在組合節點圖？偏好內建動作 + 表達式。 使用 Cargo 已提供的動作加上範本表達式；避免使用 python、script (JS) 和原始 HTTP 節點，除非你真的沒有其他選擇。重塑資料 → variables；呼叫 LLM 並取得解析後的 JSON → 原生 agent 節點；呼叫 API → 整合的專用 connector action；路由 → branch/filter/switch。請參閱 references/node-selection.md。

參考資料：

references/examples/actions.md — action execute 和 execute-batch 範例
references/examples/tools.md — tool（隨選工作流程）範例
references/examples/plays.md — play（區段驅動自動化）範例
references/examples/agents.md — AI 代理聊天範例
references/examples/templates.md — 預建工作流程範本
references/examples/queries.md — orchestration query execute (ClickHouse: runs/batches/spans/records) SQL 範例。關於 storage query（工作區儲存），請參閱 cargo-storage 技能。
references/examples/segments.md — 區段擷取和篩選範例
references/nodes.md — 完整節點建立指南（種類、原生動作、表達式、驗證、路由）
references/node-selection.md — 如何選擇正確的節點並避免不必要的 python 節點（決策表、原生 LLM agent 節點、範本表達式限制、靜默未定義的陷阱、透過 runContext 檢查節點資料、Pyodide 沙箱限制、delay 後保留的內容、群組結果存取）
references/filter-syntax.md — 完整的篩選條件參考
references/polling.md — 非同步輪詢模式、錯誤處理、重試策略
references/response-shapes.md — 完整的 JSON 回應結構
references/troubleshooting.md — 常見錯誤，以及「除錯工作流程執行」章節（針對執行成功但輸出錯誤的情況：錯誤分支路由、空的下游值）

事後診斷？ 如需基於這些表面的有序取證執行手冊——追蹤單次執行、按根本原因分組掃描批次錯誤、分析 play 的點數花費——請載入 cargo-diagnostics 技能。

先決條件

請參閱 ../cargo/references/prerequisites.md 了解安裝、登入（--oauth / --token）、JSON 輸出慣例和錯誤格式。在執行以下任何指令前，請先使用 cargo-ai whoami 驗證工作階段。

先探索資源

大多數指令需要 UUID。在執行前務必先探索它們。

cargo-ai orchestration play list            # 所有 play（name, workflowUuid, modelUuid, segmentUuid）
cargo-ai orchestration tool list            # 所有 tool（name, workflowUuid, description）
cargo-ai orchestration workflow list        # 所有 workflow（僅 uuid — 無 name）
cargo-ai orchestration template list       # 所有 workflow 範本（slug, name, kind）
cargo-ai ai agent list                     # 所有 agent（uuid, name）
cargo-ai ai template list                  # 所有 AI agent 範本（slug, name, languageModelSlug）
cargo-ai storage model list                # 所有 model（uuid, name, slug, columns）
cargo-ai storage dataset list              # 所有 dataset
cargo-ai segmentation segment list         # 所有 segment（uuid, name, modelUuid）
cargo-ai connection connector list         # 所有 connector

Plays vs tools： 兩者都由工作流程支援。play 是區段驅動的自動化——它對區段中的資料變更（新增、更新、刪除記錄）做出反應。tool 是隨選工作流程——手動觸發、透過 API 觸發，或按 cron 排程觸發。工作流程沒有 name 欄位；使用 play list 或 tool list 來尋找名稱並提取 workflowUuid。

在 UI 中檢視： play 位於 app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID>，tool 位於 app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID>。從 cargo-ai whoami 的 workspace.uuid 取得 <WORKSPACE_UUID>。

正在設計新的 tool 或 play？ 先檢查範本——它們是針對常見自動化模式（豐富化管道、CRM 同步、潛在客戶評分）預建的節點圖，是絕佳的起點。使用 cargo-ai orchestration template list 列出範本，並使用 cargo-ai orchestration template get <slug> 檢查特定範本。範本按 kind 標記，因此你可以立即找到適合 tool（"kind":"tool"）或 play（"kind":"play"）的範本。完整指南請參閱 references/examples/templates.md。

相容性規則：

• run create — 僅適用於 tool 工作流程（或無 workflowUuid）。Play 工作流程會回傳 playNotCompatible。
• batch create — 允許的資料種類取決於工作流程類型：
  • Play 工作流程：segment, change, filter, recordIds
  • Tool 工作流程（或無 workflowUuid）：file, records

快速參考

# 單一動作
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"<uuid>","config":{}}' --data '{"domain":"acme.com"}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' --records '[{...},{...}]'
cargo-ai orchestration action get-output-schema --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' # → {"schema": <JSON Schema>} 不執行

# 工作流程（串聯多個動作）
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{"company":"Acme","domain":"acme.com"}'
cargo-ai orchestration run create --data '{"domain":"acme.com"}' --nodes '[...]'
cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"segment","segmentUuid":"..."}'

# AI 代理
cargo-ai ai message create --chat-uuid <uuid> --parts '[{"type":"text","text":"..."}]'

# 資料
cargo-ai orchestration query execute "SELECT count() FROM runs WHERE status='error'" # ClickHouse: spans, runs, batches, records
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}' --fetching-limit 100
# 針對工作區儲存（Companies, Contacts, …）的 SQL，請參閱 cargo-storage 技能：`storage query execute`

輪詢非同步操作

所有操作都是非同步的。要嘛輪詢直到終端狀態，要嘛傳遞 --wait-until-finished 來阻塞。

action execute 回傳一個 run。action execute-batch 回傳一個 batch。它們以相同方式輪詢：

結果類型	輪詢指令	間隔	完成時機
Run	run get <uuid>	2s	status 為 success、error 或 cancelled
Batch	batch get <uuid>	5s	status 為 success、error 或 cancelled
Agent 訊息	message get <uuid>	2s	status 為 success 或 error

對於長時間執行的批次（1000+ 筆記錄），在第一分鐘後將間隔增加到 10-15 秒。

執行動作

執行單一動作——無需工作流程或節點圖。

# 一個動作，一筆記錄 → 回傳一個 run
cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' \
  --data '{"domain":"acme.com"}' \
  --wait-until-finished

# 一個動作，多筆記錄 → 回傳一個 batch
cargo-ai orchestration action execute-batch \
  --action '{"kind":"tool","toolUuid":"<tool-uuid>","config":{}}' \
  --records '[{"domain":"acme.com"},{"domain":"globex.com"}]' \
  --wait-until-finished

動作種類：tool, connector, agent, native。請參閱 references/examples/actions.md 了解所有動作種類、參數、重試設定、回應形狀和端到端範例。

解析動作的輸出結構（不執行）

永遠不要猜測動作的輸出。 兩個免費來源——無需執行，無需點數：

1. 連接器動作： 整合目錄內嵌輸出結構——integration get <slug>（和 integration list）回傳 actions.<actionSlug>.output.schema 以及輸入 config.jsonSchema。並非每個動作都會宣告。
2. 任何動作種類（tool / connector / agent / native）——使用與 action execute 相同的 --action 物件來解析：

cargo-ai orchestration action get-output-schema \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}'
# → {"schema": {"type": "object", "properties": {...}}}  — JSON Schema 位於頂層 "schema" 鍵下

未宣告輸出結構的動作會失敗並顯示 "Action has no output schema."（非零退出碼，狀態 404）——這是回退到檢查實際執行中 runContext 的信號。使用這些來：

• 在連接圖表之前，知道下游節點可以讀取哪些欄位（{{nodes.<slug>.<field>}}）。
• 查看 agent 動作的真實輸出信封——預設的自由文字 agent 解析為 {"schema":{"type":"object","properties":{"answer":{"type":"string"}}}}，這就是為什麼下游引用需要 {{nodes.<slug>.answer...}}。
• 將動作的輸出對應到儲存欄位，無需一次性的執行。

請參閱 references/examples/actions.md（「解析動作的輸出結構」）了解每個種類的驗證範例以及回應/錯誤形狀。

建立一個 run

Run 透過工作流程處理單一記錄。當你需要透過節點圖串聯多個動作，或執行現有的工具工作流程時，使用 run create。

Runs 僅適用於 tool 工作流程。 Play 工作流程會回傳 playNotCompatible——請改用 batch create。

cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"company":"Acme","domain":"acme.com"}'
# → 使用以下指令輪詢：cargo-ai orchestration run get <run-uuid>

# 或同步等待——阻塞直到 run 達到終端狀態並回傳最終結果
cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"company":"Acme","domain":"acme.com"}' \
  --wait-until-finished

也支援 --release-uuid 來固定特定版本。

取消 runs：

cargo-ai orchestration run cancel --workflow-uuid <uuid> --uuids run-uuid-1,run-uuid-2

請參閱 references/examples/tools.md 了解檔案上傳、監控和取消。請參閱 references/nodes.md 了解自訂節點圖。

建立一個 batch

Batch 一次處理多筆記錄。允許的資料種類取決於工作流程類型：

• Play 工作流程：segment, change, filter, recordIds
• Tool 工作流程（或無 workflowUuid）：file, records

# Play 工作流程——在區段上執行
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"segment","segmentUuid":"..."}'

# Tool 工作流程——在檔案上執行
cargo-ai orchestration batch create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"kind":"file","s3Filename":"..."}'
# → 使用以下指令輪詢：cargo-ai orchestration batch get <batch-uuid>

# 或同步等待——阻塞直到 batch 達到終端狀態並回傳最終結果
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"segment","segmentUuid":"..."}' \
  --wait-until-finished

下載結果： 從 batch get 取得 releaseUuid，然後執行 cargo-ai orchestration release get <release-uuid> 來尋找 nodes[].slug，接著執行 cargo-ai orchestration batch download --uuid <batch-uuid> --output-node-slug <slug>。

取消 batch：

cargo-ai orchestration batch cancel <batch-uuid>

請參閱 references/examples/plays.md 和 references/examples/tools.md 了解篩選、記錄 ID、檔案上傳、監控和取消。

傳送訊息給 AI 代理

cargo-ai ai agent list                                    # 1. 尋找 agent
cargo-ai ai chat create \                                 # 2. 建立聊天
  --trigger '{"type":"draft"}' \
  --agent-uuid <agent-uuid> --name "Research session"
cargo-ai ai message create \                              # 3. 傳送訊息
  --chat-uuid <chat-uuid> \
  --parts '[{"type":"text","text":"Find the VP of Sales at Acme Corp"}]'
# → 提取 assistantMessage.uuid，使用以下指令輪詢：cargo-ai ai message get <uuid>
#   當 .message.status 為 "success"（讀取 .parts）或 "error"（讀取 .errorMessage）時完成

也支援 --actions、--resources、--language-model-slug、--temperature、--max-steps 和 --wait-until-finished（阻塞直到助理訊息達到終端狀態）。請參閱 references/examples/agents.md 了解多輪對話、動作/資源注入和模型選擇。

檢查記錄

記錄是工作流程處理的個別項目。使用這些指令來列出、計數、下載或取消工作流程中的記錄。

# 列出工作流程的記錄
cargo-ai orchestration record list --workflow-uuid <uuid> --limit 50

# 按批次或狀態篩選
cargo-ai orchestration record list --workflow-uuid <uuid> --batch-uuid <uuid> --statuses error

# 計數記錄
cargo-ai orchestration record count --workflow-uuid <uuid>

# 將記錄下載為檔案
cargo-ai orchestration record download --workflow-uuid <uuid>

# 取得每個節點的執行指標
cargo-ai orchestration record get-metrics --workflow-uuid <uuid>

# 取消記錄
cargo-ai orchestration record cancel --workflow-uuid <uuid> --ids record-id-1,record-id-2

查詢編排歷史（orchestration query）

使用 orchestration query execute 對編排執行時期資料表——spans、runs、batches、records——執行 SQL。用於對工作流程執行進行臨時分析（錯誤率、吞吐量、最慢節點），無需 run get-metrics / run count 的工作流程範圍篩選。

cargo-ai orchestration query execute "SELECT count() FROM runs WHERE status = 'error'"
cargo-ai orchestration query execute "SELECT status, count() FROM batches GROUP BY status"
cargo-ai orchestration query execute "SELECT * FROM spans ORDER BY execution_started_at DESC LIMIT 10"

資料表在引用時無需結構描述前綴——只需 spans、runs、batches 或 records。工作區範圍會自動套用。查詢是唯讀的；DDL、資料表函數、字典存取器和內省都被拒絕。請參閱 references/examples/queries.md 了解結構描述、範例查詢和限制。

擷取區段資料

從區段中檢索即時記錄。重要： 需要 --model-uuid（不是 --segment-uuid）。從 segment list 取得 modelUuid。篩選 JSON 使用 conjonction（不是 conjunction）——這是故意的。

cargo-ai segmentation segment fetch \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}' \
  --fetching-limit 100 --fetching-offset 0

支援 --sort、--enrich 和 --sync。請參閱 references/filter-syntax.md 了解完整的篩選語法，以及 references/examples/segments.md 了解篩選、分頁、排序、註冊篩選器和豐富化。

管理區段：

# 更新區段的名稱或篩選器
cargo-ai segmentation segment update --uuid <segment-uuid> --name "Updated Name"
cargo-ai segmentation segment update --uuid <segment-uuid> --filter '{"conjonction":"and","groups":[...]}'

# 移除區段（如果連結到工作流程則失敗）
cargo-ai segmentation segment remove <segment-uuid>

使用工作流程範本

範本是針對常見自動化模式（豐富化管道、CRM 同步、潛在客戶評分）預建的節點圖。使用 template list 瀏覽，使用 template get <slug> 檢查，填入佔位符，驗證並執行。

cargo-ai orchestration template list              # 列出可用範本
cargo-ai orchestration template get <slug>        # 取得範本節點 + 設定

請參閱 references/examples/templates.md 了解完整指南，包括佔位符慣例和端到端範例。

驗證和測試節點

在執行自訂節點圖之前，務必先驗證。

cargo-ai orchestration node validate --nodes '[...]'
# → { "outcome": "valid" } 或 { "outcome": "notValid", "invalidNodes": [...] }

對於除錯，使用 node compute（乾執行表達式）或 node execute（即時測試，消耗點數）。對於完成時 status: success 但產生錯誤輸出的執行（錯誤分支、空的下游值），僅使用 run get 中的 run.executions[].title 作為快速摘要——它可能被截斷——並讀取 runContext.<nodeSlug>（在同一 run get <run-uuid> 回應的頂層回傳）來驗證欄位層級資料。請參閱 references/troubleshooting.md → 「除錯工作流程執行」和 references/nodes.md 了解完整的節點建立指南、驗證錯誤碼和範例。

說明

每個指令都支援 --help：

cargo-ai orchestration run create --help
cargo-ai orchestration template list --help
cargo-ai orchestration node validate --help
cargo-ai ai message create --help
cargo-ai orchestration query execute --help