71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
wf run trace <run_id> --from 0 --limit 25
|
|
```
|