cargo-orchestration

Cargo CLI — オーケストレーション

Cargo プラットフォームの実行時操作です。

何を実行しますか？

Need to run something?
├── Don't know the action yet    → action list <keywords>
├── One action, one record       → action execute
├── One action, many records     → action execute-batch
├── Multiple actions chained
│   ├── One-off / ad-hoc         → run create --nodes (one record)
│   │                              batch create --nodes (many records)
│   └── Reusable workflow        → build a tool, then run create --workflow-uuid
│                                  or batch create --workflow-uuid
├── Conversational AI agent      → message create
└── Testing ONE node of a
    workflow you're building     → node execute (debug only — see below)

多数のレコードを処理する場合（action execute-batch、batch create）は、まずサンプルを実行してください。 10〜20 件のレコードを実行し、観測したコストとヒット率を報告してから、対象レコード数とクレジットの見積もりを明示して、全件の実行についてユーザーの承認を得てください。バッチの作成 → サンプルの確認を参照してください。

ノードの種類にかかわらず、実行 1 回につき 0.01 クレジット、つまり 100 回につき 1 クレジットがかかります。 branch、filter、switch、variables などにはプロバイダー料金はかかりませんが、無料ではありません。料金は実行ごとに発生するため、グラフのコストは次の 2 つの項目から成ります。 (プロバイダー料金 × レコード数) + (ノード数 × レコード数 ÷ 100)。ステップが多くアクションが少ないグラフでは、後者の項目が支配的になります。この料金はノード単位のフィールドには一切表示されません。executions[].creditsUsedCount にも、spans.execution_credits_used_count にも表示されず、billing usage get-metrics --unit orchestration.executions でのみ確認できます。承認依頼では両方の項目を提示してください（../cargo-gtm/references/cost-discipline.md §1）。

JSON を手書きする前に、アクションを探してください。 cargo-ai orchestration action list <keywords> は、インテグレーションカタログ、Cargo ネイティブアクション、ワークスペースツール、エージェントを 1 回の呼び出しで検索します。無料で、何も実行しません。各検索結果には、そのまま貼り付けられる action オブジェクト（connectorUuid があらかじめ設定済み）、アクションのクレジットコスト、オートコンプリート用スラッグが含まれます。--kind connector|native|tool|agent、--integration-slug <slug>、--limit で絞り込めます（デフォルト値はありません。省略すると、該当する結果がすべて返されます）。unknown command と表示された場合は、CLI が古いため、更新してください。

何かを実行する場合は、node execute ではなく action execute をデフォルトで使用してください。 node execute は、ワークフローにすでに含まれているノード向けのデバッグ機能です。--workflow-uuid、--release-uuid、--node、--computed-config、および --context（クライアント側で 5 つすべてが必須）を指定する必要があり、通常の実行と同じ料金がかかります。ドメインデータの補完、コネクターアクションの呼び出し、ツールやエージェントの実行など、単に操作の出力が必要な場合は、--action と --data に小さなペイロードを指定して action execute または action execute-batch を使用してください。node execute を使用するのは、グラフ全体を実行する前に 1 つのノードの動作を検証する場合に限ってください。

用語： オーケストレーションのツールとは、保存済みのオンデマンドワークフローです（tool list で一覧表示）。アクションとは、ワークフローを作成せずに実行する単一の操作です。保存済みのオーケストレーションツール（kind: "tool"）を組み込む、サードパーティコネクターを呼び出す（kind: "connector"）、AI エージェントを呼び出す（kind: "agent"）、またはプラットフォームの組み込み操作を実行する（kind: "native"）ことができます。

ノードグラフを組み立てる場合は、専用アクションと式を次の順序で使ってください：

1. 専用アクション。 まず action list <keywords> で検索します（無料）。コネクターアクション、ネイティブアクション（agent、modelUpsert、branch、group など）、ツールが見つかります。
2. 式で処理をつなぎます。値が必要なフィールドに、整形、ペイロード、条件、配列などを記述するインライン JavaScript です。
3. HTTP。手順 1 でその API に対応するアクションが見つからない場合に限ります。
4. script ノード。ロジックを式に収められない場合に限ります。

references/node-selection.mdを参照してください。 説明するのではなく、グラフを表示してください。 ドラフトをデプロイする前と、ワークフローやプレイの内容をユーザーから尋ねられたときは、次のコマンドで図を描いてください。 cargo-ai orchestration node diagram --workflow-uuid <uuid> --format ascii --raw （無料で、何も実行しません。--format には CLI ≥ 1.0.56、コマンド自体には ≥ 1.0.54 が必要です。） ルーティング、フォールバックのエッジ、課金対象のステップは、ユーザーが実際に承認する内容です。文章では、この3つすべてがわかりにくくなります。出力先に合わせて形式を選んでください。 ascii は、ターミナルやチャットの返信で人が読める図を表示します。mermaid（デフォルト）はソースコードで、PR、ドキュメント、またはレンダリングに対応したページに貼り付ける場合にのみ適しています。ソース、ASCII の凡例、コストの表示、重複したスラッグに関する落とし穴については、references/node-diagram.md を参照してください。

参考資料：

references/examples/actions.md — アクションの実行と一括実行の例 references/examples/tools.md — ツール（オンデマンドのワークフロー）の例 references/examples/plays.md — プレイ（セグメント駆動型の自動化）の例 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-diagram.md — ノードグラフを Mermaid フローチャートとして描画（node diagram）：すべてのソース（ワークフロー／ドラフト／リリース／実行／生のノード）、有料ノードの表示、失敗したノードの強調、図のキーに slug ではなく uuid を使う理由 references/node-selection.md — 専用アクションと式を使って構築（アクション → 式 → HTTP → script の順）：式はインライン JavaScript です。ロジックを記述する場所（単一フィールドへのインライン記述、共有の variables ノード、または script）、コード／HTTP より優先すべきネイティブアクション、式の落とし穴（空のパスが黙って返される、ISO 文字列が Date として届く）、expression eval を使ったテストについて説明します。 references/filter-syntax.md — フィルター条件の完全なリファレンス references/polling.md — 非同期ポーリングのパターン、エラー処理、再試行戦略 references/response-shapes.md — JSON レスポンス構造の全容 references/troubleshooting.md — よくあるエラーに加え、成功しても誤った出力になる実行（誤った分岐へのルーティング、後続ノードの値が空）のための「ワークフロー実行のデバッグ」セクション

事後に原因を調査しますか？ これらの機能を基盤とする、順序立てられたフォレンジック用ランブック（1件の実行を追跡する、根本原因ごとにまとめてバッチのエラーを調べる、プレイのクレジット消費を分析する）を利用するには、cargo-diagnostics スキルを読み込んでください。

ブートストラップ

すでにサインイン済みで（cargo-ai whoami がワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは JSON を stdout に出力します。失敗すると 0 以外の終了コードを返し、{"error": "...", "status": ..., "body": ...} を stderr に出力します（API 独自の errorMessage または reason は error と body の中に含まれます）。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。スキル一式をインストールしている場合は、../cargo/references/prerequisites.md に CLI のバージョン指定、トークンのスコープ、管理者専用の機能が記載されています。

まずリソースを確認する

ほとんどのコマンドでは UUID が必要です。操作を行う前に、必ず確認してください。

cargo-ai orchestration action list <query>  # actions across connectors, native, tools, agents (+ credits)
cargo-ai orchestration play list            # all plays (name, workflowUuid, modelUuid, segmentUuid)
cargo-ai orchestration play list --is-enabled --schedule-type cron   # filter: --is-enabled / --is-disabled, --schedule-type dbt|cron|realtime|dependency|watch, --model-uuid, --segment-uuid
cargo-ai orchestration tool list            # all tools (name, workflowUuid, description)
cargo-ai orchestration workflow list        # all workflows (uuid only — no name)
cargo-ai orchestration template list       # all workflow templates (slug, name, kind)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai ai template list                  # all AI agent templates (slug, name, languageModelSlug)
cargo-ai storage model list                # all models (uuid, name, slug, columns)
cargo-ai storage dataset list              # all datasets
cargo-ai segmentation segment list         # all segments (uuid, name, modelUuid)
cargo-ai connection connector list         # all connectors

プレイとツールの違い： どちらもワークフローを基盤としています。プレイはセグメント駆動型の自動化で、セグメント内のデータ変更（レコードの追加、更新、削除）に応じて動作します。ツールはオンデマンドのワークフローで、手動、API、または cron スケジュールによって起動します。ワークフローには name フィールドがありません。名前を確認して workflowUuid を取得するには、play list または tool list を使用してください。

UI で確認する： プレイは app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID> に、ツールは app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID> にあります。cargo-ai whoami の workspace.uuid から <WORKSPACE_UUID> を取得してください。

新しいツールやプレイを設計していますか？ まずテンプレートを確認してください。テンプレートは、一般的な自動化パターン（エンリッチメントパイプライン、CRM 同期、リードスコアリングなど）向けにあらかじめ構築されたノードグラフで、優れた出発点になります。cargo-ai orchestration template list でテンプレートを一覧表示し、cargo-ai orchestration template get <slug> で特定のテンプレートを確認できます。テンプレートには kind のタグが付いているため、ツール向け（"kind":"tool"）またはプレイ向け（"kind":"play"）のものをすぐに見つけられます。詳しいガイドは references/examples/templates.md を参照してください。

互換性ルール：

• run create — ツールのワークフローでのみ動作します（または workflowUuid がない場合）。プレイのワークフローでは playNotCompatible が返されます。
• batch create — 使用できるデータ種別はワークフローの種類によって異なります。
  • プレイのワークフロー：filter、recordIds、segment、change が使用できます。プレイの起動には filter を使用してください。segment には単独のセグメントのみを指定し、play list の segmentUuid は使用しないでください。file は拒否され（invalidDataKind）、プレイのものとは異なるモデルの filter または recordIds も拒否されます（modelDoesNotBelongToPlay）。
  • ツールのワークフロー（または workflowUuid がない場合）：通常は file または records を使用します。モデルに基づく種別はツールでは拒否されません。

クイックリファレンス

# Find an action (free — no run, no credits)
cargo-ai orchestration action list enrich company
cargo-ai orchestration action list send --kind connector --integration-slug slack

# Single actions
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"<uuid>"}' --data '{"domain":"acme.com"}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany"}' --records '[{...},{...}]'
cargo-ai orchestration action get-output-schema --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany"}' # → {"schema": <JSON Schema>} without executing
cargo-ai orchestration action execute --action '{"kind":"connector","integrationSlug":"aiArk","actionSlug":"enrichCompany"}' --data '{"domain":"example.com"}' --dry-run   # free, no account: validates --data, sample output + price

# Workflows (chain multiple actions)
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 preview --workflow-uuid <uuid> --data '<same as batch create>'   # free: count + up to 200 sample records, creates nothing
cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"filter","modelUuid":"...","filter":{"conjonction":"and","groups":[]}}'

# Plays and tools themselves (settings, health alert, removal) — references/examples/plays.md
cargo-ai orchestration play update <play-uuid> --is-disabled
cargo-ai orchestration play update <play-uuid> --health-threshold 90 --health-alert-actions '[...]'
cargo-ai orchestration play remove <play-uuid>
cargo-ai orchestration tool remove <tool-uuid>

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

# Data
cargo-ai orchestration query execute "SELECT count() FROM runs WHERE status='error'" # ClickHouse: spans, runs, batches, records
cargo-ai orchestration trace list --started-after <iso> --statuses error,degraded   # one row per trigger, across child runs; also trace count / trace get <uuid>
cargo-ai orchestration span list --execution-started-after <iso> --batch-uuid <uuid> --execution-statuses error   # node executions without SQL; also span count
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}' --fetching-limit 100
# For SQL against workspace storage (Companies, Contacts, …), see the cargo-storage skill: `storage query execute`

非同期操作のポーリング

すべての操作は非同期です。終端状態になるまでポーリングするか、--wait-until-finished を指定して完了まで待機してください。

action execute は実行を返します。action execute-batch はバッチを返します。どちらも同じ方法でポーリングします。

結果の種類	ポーリングコマンド	間隔	完了条件
実行	run get <uuid>	2s	status が success、error、cancelled、または skipped（run.finishedAt が設定されている）
バッチ	batch get <uuid>	5s	status が success、error、cancelled、または skipped（batch.finishedAt が設定されている）
エージェントメッセージ	message get <uuid>	2s	status が success、error、または cancelled

長時間実行されるバッチ（1000 件以上のレコード）では、最初の 1 分が経過した後、間隔を 10～15s に延ばしてください。

アクションを実行する

ワークフローやノードグラフを必要とせず、単一のアクションを実行します。

まず検索 — action list

cargo-ai orchestration action list enrich company          # all kinds
cargo-ai orchestration action list --kind tool             # this workspace's tools
cargo-ai orchestration action list send --kind connector --integration-slug slack

無料で、何も実行しません。すべての検索語が一致する必要があります（AND）。アクションのスラッグまたは名前への一致はインテグレーションへの一致より上位に、インテグレーションへの一致は説明への一致より上位にランク付けされます。{query, totalMatches, results[]} を返します。各結果には、name、description、score、execute ／ execute-batch ／ get-output-schema にそのまま貼り付けられる action オブジェクト、そのインテグレーションに対応するワークスペースの connectors、課金対象のアクションの場合は料金表である credits、および ID を選択する必要がある設定フィールド（HubSpot のオブジェクトタイプや Slack のチャンネルなど）を示す autocompletes が含まれます。--limit を指定しない限り、一致するすべての項目を返します。

# One action, one record → returns a run
cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany"}' \
  --data '{"domain":"acme.com"}' \
  --wait-until-finished

# One action, many records → returns a batch
cargo-ai orchestration action execute-batch \
  --action '{"kind":"tool","toolUuid":"<tool-uuid>"}' \
  --records '[{"domain":"acme.com"},{"domain":"globex.com"}]' \
  --wait-until-finished

アクションの種類は tool、connector、agent、native です（ホストされたワーカーを workerUuid、method、path で呼び出す worker もあります）。すべてのアクションの種類、パラメーター、再試行設定、レスポンスの形式、エンドツーエンドの例については、references/examples/actions.md を参照してください。

トップレベルのアクションには config はありません。省略してください。 入力は --data ／ --records に指定します。execute と execute-batch には config キーを一切含めずにアクションを渡します。 action list が返す形式そのものなので、その結果をそのまま貼り付けられます。 （"config": {} も引き続き受け付けられ、問題はありません。）

get-output-schema にも同じ組み合わせを渡します。 action list のアクションオブジェクトに加え、 アクションの出力が入力に依存する場合は --data も渡します。返されるフィールドは HubSpot のオブジェクトタイプや対象のシートによって決まります （--data には CLI ≥ 1.0.67 が必要です。config なしの --action は 1.0.66 から利用できます）。 ワークフローの ノード、アラートの --actions、プレイの healthAlertActions、エージェントまたは MCP サーバーの --actions には、引き続き config を指定します。これはノードの設定であり、アクションの入力ではありません。

不明な入力は実行前に拒否されます。config に入れた入力は除去されます。 action execute と execute-batch は、何も作成する前に、コネクターまたはネイティブアクションの入力をスキーマと照合します （MCP の execute_action* ツールとエージェントのアクション呼び出しも同様です）。宣言されていないキーは、トップレベルでも宣言済みオブジェクト内のネストされたキーでも、 その名前を示す invalidData エラーになります（Unknown field: secs。バッチでは Record 1: Unknown field: fields.job_titles となり、不正なレコードが1つあるとバッチ全体が拒否されます）。バッチレコードのトップレベルにある余分な列は引き続き受け付けられます。ツールアクションはチェックされず、ワークフローノード内の不明なキーは引き続きエラーなしで破棄されます。config キーは別扱いです。以前は A top-level action does not use action.config… と返していたガードがなくなったため、config はそれを示すエラーなしで除去され、その中の入力は一切届きません。必須入力のあるアクションは、その入力がないため拒否され、必須入力のないアクションは何もせずに実行されます。目に見える理由もなく呼び出し結果が空の場合は、まずここを確認してください。

execute-batch はレコードごとに課金されます。 まず --records の10～20件分のスライスを渡し、レコードあたりの実測コストとヒット率を報告してから、残りを送信する承認（全レコード数とクレジットの見積もりを含む）を得てください。バッチの作成と同じゲートです。

アクションの出力スキーマを解決する（実行せずに）

アクションの出力を決して推測しないでください。 実行もクレジットも不要な、無料の情報源が2つあります。

1. コネクターアクション： インテグレーションカタログには出力スキーマがインラインで含まれています。integration get <slug>（および integration list）は、入力の config.schema（フォームUI用の config.jsonSchema は、多くのアクションで欠落しています）と並んで actions.<actionSlug>.output.schema を返します。出力スキーマを宣言していないアクションもあります。
2. あらゆる種類のアクション（tool／connector／agent／native）：action execute と同じ --action オブジェクトを使って解決します。

cargo-ai orchestration action get-output-schema \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany"}'
# → {"schema": {"type": "object", "properties": {...}}}  — the JSON Schema is under the top-level "schema" key

# When the output depends on the inputs, pass them exactly as `execute` takes
# them (--data needs CLI >= 1.0.67):
cargo-ai orchestration action get-output-schema \
  --action '{"kind":"connector","integrationSlug":"hubspot","actionSlug":"findRecords"}' \
  --data '{"objectType":"contacts"}' 

出力スキーマを宣言していないアクションは Not found: actionHasNoOutput で失敗します（終了コードは0以外、ステータスは404、本文は {"reason":"actionHasNoOutput"}）。これは、実際の実行から runContext を確認するよう切り替える合図です。次の用途に使えます。

• グラフを接続する前に、後続ノードが読み取れるフィールド（{{nodes.<slug>.<field>}}）を把握できます。
• agent アクションの実際の出力エンベロープを確認できます。デフォルトの自由記述型エージェントは {"schema":{"type":"object","properties":{"answer":{"type":"string"}}}} に解決されます。そのため、後続の参照には {{nodes.<slug>.answer...}} が必要です。
• 試しの実行をせずに、アクションの出力をストレージの列にマッピングできます。

種類ごとの検証済みサンプルとレスポンス／エラーの形式については、references/examples/actions.md の「アクションの出力スキーマを解決する」を参照してください。

ドライラン — 入力と料金を確認（無料、アカウント不要）

cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"aiArk","actionSlug":"enrichCompany"}' \
  --data '{"domain":"example.com"}' --dry-run

何も実行せず、プロバイダーも呼び出しません。--data をアクションの入力スキーマに対してクライアント側で検証し、実行完了時と同じ形式のサンプル出力を表示します — {run: {status: "success", executions: [...]}, runContext: {action: <sample>}, runComputedConfigs: {action: <your --data>}, dryRun: {sample: true, estimatedCredits, creditsFormula, note}}。常に公開カタログを読み取るため、サインアウト中でも動作します（通知はstderrに出力され、stdoutはJSONのままです）。

• 対象はコネクターアクションとネイティブアクションのみです。 tool／agent は拒否されます（ワークスペース独自のワークフローを実行するためです）。connectorUuid は不要です。
• スキーマとの不一致は、不正な使用方法として終了します — --data does not match the inputs of `<action>`. と errors[] を返します（例：Missing required field: x）。実際の呼び出しで何も返ってこなかったとき、最初に実行するチェックです。
• 値はダミーですが、形式と料金は実際のものです。 サンプルデータは出力スキーマから生成されます。estimatedCredits は1回の呼び出しの料金を示します（ユニット料金／パッケージ料金では1ユニットまたは1ブロック。どちらかは creditsFormula に記載）。0.01のノード実行料金は含まれません。
• 設定に依存する出力は表示できません — … has no fixed output schema: what it returns depends on its configuration, so a dry run cannot show it. サインイン後は、action get-output-schema --data … で解決できます。オープンスキーマのアクションは空のオブジェクトを表示します（classify は answers: {} を表示します）。

サインアウト中でも、カタログを参照できます。orchestration action list（コネクターアクションとネイティブアクションのみ — ツールとエージェントにはワークスペースが必要）、connection integration list|get|get-documentation、connection action search、さらに project plan／project types が利用できます。実行を伴う操作にはすべてサインインが必要です（cargo-ai login --email …、無料クレジット100）。

実行を作成する

実行では、1つのレコードをワークフローに通して処理します。ノードグラフを使って複数のアクションを連結する場合、または既存のツールワークフローを実行する場合は、run create を使用します。

実行できるのはツールワークフローのみです。 プレイワークフローは playNotCompatible を返します。その場合は代わりに batch create を使用してください。

cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"company":"Acme","domain":"acme.com"}'
# → Poll with: cargo-ai orchestration run get <run-uuid>

# Or wait synchronously — blocks until the run reaches a terminal state and returns the final result
cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"company":"Acme","domain":"acme.com"}' \
  --wait-until-finished

特定のリリースに固定するための --release-uuid もサポートしています。

実行のキャンセル：

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

ファイルのアップロード、監視、キャンセルについては references/examples/tools.md を参照してください。カスタムノードグラフについては references/nodes.md を参照してください。

バッチを作成する

まずサンプルを実行し、全件の登録前に確認を求めます（必須）。 バッチはデータソース内のすべてのレコードにワークフローを適用するため、ミスがあると、その影響と請求が同時に発生します。初回の実行でセグメント、ファイル、モデル全体を登録してはいけません。10～20件のレコードでサンプルを実行し、費用と結果を報告してから、質問にレコード数とクレジットの見積もりを含め、全件の登録についてユーザーの承認を求めてください。手順は以下のとおりです。費用に関するルールは../cargo-gtm/references/cost-discipline.mdを参照してください。

サンプルの確認手順

1. まず対象件数を数えます（無料）。 推測に基づいて見積もりを伝えてはいけません。

cargo-ai orchestration batch preview --workflow-uuid <uuid> --data '<the exact batch create --data>'
#   → {outcome:"previewed", count, records (≤ 200), isRefreshing} — creates no batch, bills nothing
cargo-ai segmentation segment get <segment-uuid>          # → recordsCount (also on `segment list`)
cargo-ai storage query execute "SELECT count() FROM <dataset>.<model>"   # for a filter/model source
# For a file source: wc -l on the CSV, minus the header row.

batch previewは、バッチと同じ--dataを読み取る唯一の件数確認方法です。そのため、フィルターの入力ミスは処理開始前に誤った件数として判明します。これは対象件数を確認するもので、料金を見積もるものではありません。change、filter、segment、recordIds、file、recordsのソースをプレビューします。runs、group、scheduleはcount: 0, records: []を返しますが、これは対象が空であることを意味しません。isRefreshing: trueの場合はモデルの更新が進行中で、最新の書き込みが含まれていない可能性があります。エラーはworkflowNotFound／segmentNotFound（404）、failedToFetchFromClient（400）です。

2. 正確なワークフローと設定で、10～20件のレコードを実行します。 データの種類ごとにサンプルを作成します。

# Play workflow, segment source → reuse the segment's own filter, capped by `limit`
cargo-ai segmentation segment get <segment-uuid>          # → copy .filter and .modelUuid
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"filter","modelUuid":"<modelUuid>","filter":<segment.filter>,"limit":15}' \
  --wait-until-finished

# Play workflow, explicit records → pick 10–20 ids
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"recordIds","modelUuid":"<modelUuid>","ids":["id-1","…","id-15"]}'

# Tool workflow, inline records → slice the array
cargo-ai orchestration batch create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"kind":"records","records":[ /* first 15 only */ ]}'

# Tool workflow, file → upload a truncated CSV (header + 15 rows), not the full file
head -n 16 leads.csv > leads-sample.csv
cargo-ai workspaceManagement file upload --file ./leads-sample.csv

limitはkind: "filter"でサンプリングするためのパラメーターです。kind: "segment"とkind: "change"にはlimitがありません。常に全件が登録されるため、サンプルにはfilterまたはrecordIdsを使い、承認済みの全件実行に限ってsegmentに切り替えてください。

3. サンプルの結果を報告してから、確認を求めます。 確認には、ユーザーが判断するために必要な2つの数値を含めてください。

Sample: 15 of 1,240 records · 6.2 credits (0.41/record) · 13/15 enriched (87%)
Full enrollment: 1,225 remaining records ≈ 502 credits (balance: 780)

Enroll all 1,225? Or:
  1. Enroll all 1,225 (≈502 cr, leaves ~278)
  2. Trim scope — e.g. the 610 records with a domain set (≈250 cr)
  3. Stop here and review the sample output first

明示的な返答を待ってください。未回答の質問がある状態で全件を登録してはいけません。また、サンプルの承認を全件実行の承認と見なしてはいけません。有料ノードがなく、かつ対象が少ない場合、またはユーザーがこのセッションですでに対象範囲を指定し、費用を承認している場合に限り、この確認手順を省略できます。

バッチでは複数のレコードを一度に処理します。使用できるデータの種類はワークフローの種類によって異なります。

• Playワークフロー：filter、recordIds、segment、change（fileはinvalidDataKindで拒否されます。他のモデルに対するfilter／recordIdsはmodelDoesNotBelongToPlayで拒否されます）
• Toolワークフロー（またはworkflowUuidが指定されていない場合）：通常はfile、records

Playを実行するにはfilterを使用します。モデルを直接クエリします。segmentで指定できるのは、segmentation segment listに表示される単独のセグメントだけです。play listが返すsegmentUuidを渡すと拒否されます（segmentLinkedToPlay、または古いバックエンドではnoRecords）。これは、Playで生成されたセグメントにはレコード数が設定されないためです。

# Play workflow — run over the play's model (empty filter = all rows)
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"filter","modelUuid":"...","filter":{"conjonction":"and","groups":[]}}'

# Tool workflow — run on a file
cargo-ai orchestration batch create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"kind":"file","s3Filename":"..."}'
# → Poll with: cargo-ai orchestration batch get <batch-uuid>

# Or wait synchronously — blocks until the batch reaches a terminal state and returns the final result
cargo-ai orchestration batch create \
  --workflow-uuid <play.workflowUuid> \
  --data '{"kind":"filter","modelUuid":"...","filter":{"conjonction":"and","groups":[]}}' \
  --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>を実行します。

バッチのキャンセル：

cargo-ai orchestration batch cancel <batch-uuid>

フィルタリング、レコードID、ファイルのアップロード、モニタリング、キャンセルについては、references/examples/plays.mdおよびreferences/examples/tools.mdを参照してください。

AI エージェントにメッセージを送信する

cargo-ai ai agent list                                    # 1. Find the agent
cargo-ai ai chat create \                                 # 2. Create a chat
  --trigger '{"type":"draft"}' \
  --agent-uuid <agent-uuid> --name "Research session"
cargo-ai ai message create \                              # 3. Send a message
  --chat-uuid <chat-uuid> \
  --parts '[{"type":"text","text":"Find the VP of Sales at Acme Corp"}]'
# → Extract assistantMessage.uuid, poll with: cargo-ai ai message get <uuid>
#   Done when .message.status is "success" (read .parts), "error" (read .errorMessage) or "cancelled"

--actions、--resources、--language-model-slug、--temperature、--max-steps、--wait-until-finishedにも対応しています（アシスタントのメッセージが最終ステータスに達するまで処理をブロックします）。複数ターンの会話、アクション／リソースの注入、モデルの選択については、references/examples/agents.mdを参照してください。

レコードを確認する

レコードは、ワークフローで処理される個々の項目です。これらのコマンドを使って、ワークフロー内のレコードを一覧表示、カウント、ダウンロード、キャンセルできます。

record download-outputsは、run download-outputsに対応するレコード単位のコマンドです。実行ごとではなく、レコードごとに1行を出力します。--limit／--offsetでページ分割できるため（CLI ≥ 1.0.90）、1つのファイルに収まらない件数もエクスポートできます。すべてのデータを一度に取得してタイムアウトするのではなく、一定の範囲に分けて順に取得してください。

# List records for a workflow
cargo-ai orchestration record list --workflow-uuid <uuid> --limit 50

# Filter by batch or status
cargo-ai orchestration record list --workflow-uuid <uuid> --batch-uuid <uuid> --statuses error

# Records (or runs, with `run list`) touched in a window — --updated-after / --updated-before
# catch a retried or resumed record that --created-after misses
cargo-ai orchestration record list --workflow-uuid <uuid> --updated-after 2026-10-22T00:00:00Z
cargo-ai orchestration run list --workflow-uuid <uuid> --updated-after 2026-10-22T00:00:00Z --statuses error

# Count records
cargo-ai orchestration record count --workflow-uuid <uuid>

# Download records as a file
cargo-ai orchestration record download --workflow-uuid <uuid>

# Download one output node's data, per record, paging through a large set
cargo-ai orchestration record download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --limit 1000 --offset 2000

# Get per-node execution metrics
cargo-ai orchestration record get-metrics --workflow-uuid <uuid>

# Cancel records
cargo-ai orchestration record cancel --workflow-uuid <uuid> --ids record-id-1,record-id-2

クエリオーケストレーション履歴（オーケストレーションクエリ）

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 では conjunction ではなく conjonction を使用します。これは意図的なものです。

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 を参照してください。

セグメントを管理する：

# Update a segment's name or filter
cargo-ai segmentation segment update --uuid <segment-uuid> --name "Updated Name"
cargo-ai segmentation segment update --uuid <segment-uuid> --filter '{"conjonction":"and","groups":[...]}'

# Remove a segment (fails if linked to a workflow)
cargo-ai segmentation segment remove <segment-uuid>

ワークフローテンプレートを使用する

テンプレートは、一般的な自動化パターン（エンリッチメントパイプライン、CRM 同期、リードスコアリング）向けに事前構築されたノードグラフです。template list で一覧を確認し、template get <slug> で詳細を調べて、プレースホルダーを入力し、検証して実行します。

cargo-ai orchestration template list              # list available templates
cargo-ai orchestration template get <slug>        # get template nodes + config

プレースホルダーの規則とエンドツーエンドの例を含む詳細なガイドについては、references/examples/templates.md を参照してください。

ノードを検証してテストする

カスタムノードグラフは、実行前に必ず検証してください。

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

次に、デプロイ前に必ず表示して確認してください。validate でわかるのは、グラフの形式が正しいことまでであり、ユーザーが依頼したとおりに動作することではありません。

cargo-ai orchestration node diagram --nodes '[...]' --format ascii --raw   # free, runs nothing

同じコマンドで、デプロイ済みのワークフロー（--workflow-uuid）、ドラフト（--draft）、リリース（--release-uuid）、または実行で使用されたグラフ（--run-uuid）を描画できます。references/node-diagram.md を参照してください。

デバッグには、node compute（式のドライラン）または node execute（既存のワークフロー内の単一ノードのライブテスト）を使用します。node execute には --workflow-uuid、--release-uuid、--computed-config が必要で、クレジットを消費します。ノードレベルのデバッグ以外には action execute を使用してください。status: success で完了しているのに出力が誤っている実行（誤った分岐に進む、下流の値が空になるなど）では、run get の run.executions[].title は簡易的な要約としてのみ使用してください。切り詰められている場合があるため、フィールドレベルのデータを確認するには、同じ run get <run-uuid> レスポンスのトップレベルで返される runContext.<nodeSlug> を参照してください。詳細については、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