2.5 KiB
Workflow System Model
Use this before choosing commands. The platform separates authoring, binding, and execution so agents can plan with stable records instead of improvising tool calls.
Core Objects
- Source: an owner of callable capabilities, such as
wf.std, a configured Python source, an MCP connection, or a future provider type. - Capability: a graph-facing callable contract exposed by a source. It has input/output schemas and outcomes. Build workflows from workflow capabilities, not raw provider internals.
- Draft workspace: mutable, revisioned authoring state. Use it when you are building or editing a workflow interactively.
- Artifact: immutable saved workflow or wrapper version. Use it when the graph should become durable and reusable.
- Deployment: mutable environment binding for an artifact version. It maps logical sources used by the artifact to concrete sources available now.
- Run: durable execution record for a deployment. It stores status, output, diagnostics, and a bounded trace history.
Why Bindings Exist
A workflow artifact should not hard-code every concrete account or source instance. It records logical source requirements. A deployment decides which live source satisfies each requirement.
Example:
artifact requires: logical.source
deployment binds: logical.source -> concrete.source
Platform sources such as wf.std are special: they can be omitted or self-bound.
Configured sources usually need explicit deployment bindings.
Authoring Paths
Use the guided draft path when editing step-by-step:
wf draft create <workspace_id> --capability <capability>
wf draft set-input ...
wf draft set-output ...
wf draft validate <workspace_id>
wf draft save <workspace_id> --artifact <artifact_id> --version 1 --title <title>
Use direct plan import only when you already have a complete workflow plan:
wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version 1 --title <title>
Draft shape and direct plan shape are different. Drafts use steps/routes/use;
direct plans use nodes/edges/node.
Execution And Trace
wf run start executes a deployment and returns a run summary. trace_count is
the number of stored trace frames for that run, not a success score. In a
three-node serial workflow, a successful run commonly has trace_count: 3.
Use trace commands only with explicit bounds:
wf run trace <run_id> --from 0 --limit 25