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 条记录，报告实际成本和命中率，然后请用户批准完整批次的处理，并说明记录数和预计积分。请参阅创建批次 → 抽样关卡。

每次节点执行都需要 0.01 积分——每 100 次执行 1 积分——无论节点是什么。 branch、filter、switch、variables 等节点没有服务商定价，但 并非免费：费用按执行次数计算，因此图的成本包含两部分： (provider cost × records) + (nodes × records ÷ 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 原生操作、 工作区工具和 Agent——免费，且不会运行任何操作——每条结果都包含可直接粘贴的 action 对象（其中已填入 connectorUuid）、操作的积分成本以及自动补全别名。可使用 --kind connector|native|tool|agent、--integration-slug <slug>、--limit 缩小范围（无默认值：省略后会返回所有匹配结果）。若出现 unknown command，说明 CLI 版本过旧——请更新。

运行操作时，默认使用 action execute，而不是 node execute。 node execute 是用于调试工作流中已有节点的调试接口： 它需要 --workflow-uuid、--release-uuid、--node、--computed-config 和 --context（客户端会强制要求这五项），且计费方式与任何实时调用相同。如果你只想获取某项操作的输出——丰富域名数据、调用连接器 操作、调用工具或 Agent——请使用带有精简 --action + --data 负载的 action execute / action execute-batch。只有在运行完整图之前验证单个节点的行为时，才使用 node execute。

术语：编排工具是已保存的按需工作流（通过 tool list 列出）。操作是指无需构建工作流即可执行的单个操作——它可以嵌入已保存的编排工具（kind: "tool"）、调用第三方连接器（kind: "connector"）、调用 AI Agent（kind: "agent"），或运行平台内置操作（kind: "native"）。

要组合节点图？请按以下顺序使用专用操作和表达式构建：

1. **专用操作。**先使用 action list <keywords> 搜索（免费）：连接器操作、 原生操作（agent、modelUpsert、branch、group……）、工具。
2. 表达式用于衔接。在需要该值的字段中编写内联 JavaScript：重塑数据、构造负载、设置条件、处理数组。
3. HTTP，仅当第 1 步未找到适用于该 API 的操作时使用。
4. script 节点，仅当逻辑无法用表达式实现时使用。

请参阅 references/node-selection.md。 展示图表，而非文字描述。 部署草稿前，以及用户询问工作流或 play 的作用时，都要绘制图表： cargo-ai orchestration node diagram --workflow-uuid <uuid> --format ascii --raw （免费，不会运行任何内容；--format 需要 CLI ≥ 1.0.56，命令本身需要 ≥ 1.0.54）。 用户真正要批准的是路由、回退边，以及哪些步骤会产生费用；文字描述会把这三者都简化掉。根据输出去向选择格式： ascii 会渲染成可在终端或聊天回复中阅读的图形；mermaid（默认格式）是源代码，只有在你要粘贴到 PR、文档或能渲染它的页面中时才合适。源、ASCII 图例、费用标记以及重复 slug 陷阱：references/node-diagram.md。

参考资料：

references/examples/actions.md — action execute 和 execute-batch 示例 references/examples/tools.md — tool（按需工作流）示例 references/examples/plays.md — play（由 segment 驱动的自动化）示例 references/examples/agents.md — AI agent 聊天示例 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 — segment 获取与筛选示例 references/nodes.md — 节点创建完整指南（类型、原生操作、表达式、验证、路由） references/node-diagram.md — 将节点图绘制为 Mermaid 流程图（node diagram）：支持每种来源（workflow / draft / release / run / 原始节点）、标记付费节点、高亮失败节点，并说明图表为何以 uuid 而非 slug 为键 references/node-selection.md — 使用专用操作 + 表达式构建（按 action → expression → HTTP → script 的顺序）：表达式是内联 JavaScript，说明逻辑的放置位置（内联在一个字段中、放在共享的 variables 节点中，或放在 script 中）、优先于代码/HTTP 的原生操作，以及表达式陷阱（静默的空路径、作为 Date 到达的 ISO 字符串、使用 expression eval 进行测试） references/filter-syntax.md — 完整的筛选条件参考 references/polling.md — 异步轮询模式、错误处理、重试策略 references/response-shapes.md — 完整的 JSON 响应结构 references/troubleshooting.md — 常见错误，以及针对运行成功但输出错误（分支路由错误、下游值为空）的“调试工作流运行”部分

事后诊断？ 如需使用这些功能执行有序的取证操作手册——追踪一次运行、按根因分组扫描批次错误、分析 play 的积分消耗——请加载 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；失败时以非零状态退出，并将 {"error": "...", "status": ..., "body": ...} 输出到 stderr（API 自身的 errorMessage 或 reason 位于 error 和 body 中）。任何会创建 run 或 batch 的操作都是异步的——请传入 --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

**Play 与工具：**两者都由工作流提供支持。Play 是由分段驱动的自动化流程，会对分段中的数据变化作出响应（记录添加、更新或移除）。工具是按需执行的工作流，可手动触发、通过 API 触发，或按 cron 计划触发。工作流没有 name 字段；使用 play list 或 tool list 查找名称并提取 workflowUuid。

**在界面中查看：**Play 位于 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>。

**要设计新的工具或 Play？**请先查看模板——它们是为常见自动化模式（数据丰富流程、CRM 同步、潜在客户评分）预先构建的节点图，是很好的起点。使用 cargo-ai orchestration template list 列出模板，并使用 cargo-ai orchestration template get <slug> 查看特定模板。模板带有 kind 标签，可立即找到适用于工具（"kind":"tool"）或 Play（"kind":"play"）的模板。完整指南请参阅 references/examples/templates.md。

兼容性规则：

• run create——仅适用于工具工作流（或未提供 workflowUuid 的情况）。Play 工作流会返回 playNotCompatible。
• batch create——允许的数据类型取决于工作流类型：
  • Play 工作流：filter、recordIds、segment、change。使用 filter 触发 Play；segment 仅接受独立分段，不能使用 play list 中的 segmentUuid。不接受 file（invalidDataKind）；对于不属于该 Play 的模型，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）
Agent 消息	message get <uuid>	2s	status 为 success、error 或 cancelled

对于长时间运行的批次（1000 条以上记录），第一分钟后将间隔延长至 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）；匹配到操作 slug 或名称的结果排名高于集成，集成又高于描述。 返回 {query, totalMatches, results[]}，其中每个结果都包含 name、 description、score、一个可直接粘贴到 execute / execute-batch / get-output-schema 中的 action 对象、该集成的工作区 connectors、credits（操作计费时的费用表），以及 autocompletes（需要选择 ID 的配置字段，例如 HubSpot 对象类型或 Slack 频道）。除非传入 --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（以及 worker，它会通过 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、Play 的 healthAlertActions，以及 Agent 或 MCP 服务的 --actions 中仍然会用到 config；那是节点的 配置，而不是操作的输入。

运行前会拒绝未知输入；放在 config 中的输入会被剥除。 action execute 和 execute-batch 会在创建任何内容之前，根据 schema 检查 connector 或 native 操作的输入（MCP 的 execute_action* 工具和 Agent 的操作调用也会这样做）：未声明的键——无论位于顶层，还是嵌套在 已声明的对象中——都会导致 invalidData，并指出该键（例如 Unknown field: secs；批量操作中会显示 Record 1: Unknown field: fields.job_titles，并且任何一条记录出错都会导致整个批次被拒绝）。批次记录中的额外顶层列仍会通过检查，tool 操作不受检查，而在工作流节点中，未知键仍会被 静默丢弃。config 键则不同：之前会返回 A top-level action does not use action.config… 的防护机制已移除，因此 config 会被剥除， 不会产生指出该键的错误，其输入也永远不会传入——需要输入的操作会因缺少该字段而被拒绝， 不需要输入的操作则不会执行任何操作。如果调用在没有明显原因的情况下返回空结果，请先检查这一点。

execute-batch 按记录计费。 先传入一组包含 10–20 条记录的 --records，报告观察到的单条记录费用和命中率，并在发送其余记录前征得批准（附上完整记录数和积分估算）——与创建批次的审批要求相同。

解析操作的输出架构（不执行）

绝不要猜测操作会输出什么。 有两个免费来源——无需运行，也不消耗额度：

1. 连接器操作： 集成目录内含输出架构——integration get <slug>（以及 integration list）会在输入 config.schema 旁返回 actions.<actionSlug>.output.schema（表单 UI 版本 config.jsonSchema 在许多操作中缺失）。并非每个操作都会声明输出架构。
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（非零退出码，状态码 404，响应体 {"reason":"actionHasNoOutput"}）——这是应转而检查真实运行的 runContext 的信号。可通过以下方式了解：

• 在连接工作流图之前，确定下游节点可以读取哪些字段（{{nodes.<slug>.<field>}}）。
• 查看 agent 操作的真实输出封装——默认的自由文本 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 估算一次调用的价格（按单位 / 套餐计价时，分别按一个单位或一个区块计算——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（仅连接器和原生操作——工具和 Agent 需要工作区）、connection integration list|get|get-documentation、connection action search，以及 project plan / project types。运行任何内容都需要登录（cargo-ai login --email …，可获得 100 个免费额度）。

创建运行

一次运行会通过工作流处理单条记录。需要通过节点图串联多个操作，或运行现有工具工作流时，请使用 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. 报告样本结果，然后询问。 确认信息必须包含用户做决定所需的两个数字：

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

使用 filter 触发 play——它会直接查询模型。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 Agent 发送消息

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 的记录粒度对应命令：每条记录占一行，而不是每个运行占一行。它支持使用 --limit / --offset 分页（CLI ≥ 1.0.90），可用于导出大到无法装入单个文件的集合——按固定大小分段遍历，而不是一次请求全部记录导致超时。

# 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 对编排运行时表运行 SQL：spans、runs、batches、records。可用于工作流执行的临时分析（错误率、吞吐量、最慢节点），无需使用 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。

管理分段：

# 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（对现有工作流中的单个节点进行实时测试——需要 --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