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（名称、workflowUuid、modelUuid、segmentUuid）
cargo-ai orchestration tool list            # 所有 tool（名称、workflowUuid、描述）
cargo-ai orchestration workflow list        # 所有 workflow（仅 uuid — 无名称）
cargo-ai orchestration template list       # 所有工作流模板（slug、名称、kind）
cargo-ai ai agent list                     # 所有 agent（uuid、名称）
cargo-ai ai template list                  # 所有 AI 代理模板（slug、名称、languageModelSlug）
cargo-ai storage model list                # 所有 model（uuid、名称、slug、列）
cargo-ai storage dataset list              # 所有 dataset
cargo-ai segmentation segment list         # 所有 segment（uuid、名称、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）在输入 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","config":{}}'
# → {"schema": {"type": "object", "properties": {...}}}  — JSON Schema 位于顶级 "schema" 键下

未声明输出模式的操作失败并返回 "Action has no output schema."（非零退出，状态 404）——这是回退到从实际运行检查 runContext 的信号。使用这些可以：

• 在连接图之前知道下游节点可以读取哪些字段（{{nodes.<slug>.<field>}}）。
• 查看 agent 操作的真实输出信封——默认的自由文本代理解析为 {"schema":{"type":"object","properties":{"answer":{"type":"string"}}}}，这就是下游引用需要 {{nodes.<slug>.answer...}} 的原因。
• 无需一次性运行即可将操作的输出映射到存储列。

参见 references/examples/actions.md（“解析操作的输出模式”）获取每种类型的验证示例以及响应/错误形状。

创建运行

运行通过工作流处理单条记录。当需要通过节点图串联多个操作，或运行现有工具工作流时，使用 run create。

运行仅适用于工具工作流。 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>

# 或同步等待——阻塞直到运行达到终端状态并返回最终结果
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 了解自定义节点图。

创建批处理

批处理一次处理多条记录。允许的数据种类取决于工作流类型：

• 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>

# 或同步等待——阻塞直到批处理达到终端状态并返回最终结果
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>。

取消批处理：

cargo-ai orchestration batch cancel <batch-uuid>

参见 references/examples/plays.md 和 references/examples/tools.md 了解过滤、记录 ID、文件上传、监控和取消。

向 AI 代理发送消息

cargo-ai ai agent list                                    # 1. 查找代理
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