126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# Workflow Lifecycle Reference
|
|
|
|
Use this when an agent needs to go from available capabilities to a saved,
|
|
validated, runnable deployment.
|
|
|
|
## Primary Path
|
|
|
|
1. List sources.
|
|
- CLI: `wf source list`
|
|
2. List workflow capabilities.
|
|
- CLI: `wf cap list`
|
|
3. Inspect one capability.
|
|
- CLI: `wf cap inspect <name>`
|
|
4. Bootstrap a draft workspace.
|
|
- CLI: `wf draft create <workspace_id> --capability <capability>`
|
|
5. Inspect/patch/validate the workspace until valid.
|
|
- Use focused CLI commands (`set-name`, `set-route`, `set-input`, `set-output`)
|
|
for common edits.
|
|
- `set-input`, `set-output`, and `set-workflow-output` replace their ordered
|
|
canonical binding lists.
|
|
Repeated sources preserve fan-out to distinct targets. The `--merge`
|
|
variants are compatibility-only and cannot preserve canonical ordering or
|
|
repeated-source fan-out; existing literals are retained for input merges.
|
|
- `set-workflow-output` accepts ordered path/value bindings. Nested
|
|
`input.*` and `state.*` sources can project declared source schemas into
|
|
missing output fields; literals and `context.*` require declared targets.
|
|
`--clear` restores implicit same-name state fallback.
|
|
- Before mapping into a new workflow input, state, or output field, prefer
|
|
`wf draft bind --from ... --to ...` when it should mirror a capability
|
|
local input/output property. It declares the matching schema and merges
|
|
the binding in one revision-checked edit.
|
|
- When adding a new capability-backed step, prefer:
|
|
|
|
```bash
|
|
wf draft add capability ... --description "Step purpose" \
|
|
--input state.value=request.value --value request.format='"json"'
|
|
wf draft update capability ... --retry 0 --clear-timeout
|
|
wf draft validate <workspace_id>
|
|
```
|
|
|
|
Capability updates are presence-aware and preserve capability selection,
|
|
routes, and outputs. Input flags replace the complete canonical input
|
|
list; use `--bindings-file` for lossless path/value interleaving.
|
|
|
|
For control flow, use the corresponding typed `wf draft add <kind>`
|
|
command. Use raw `wf draft patch` only when changing structure that no
|
|
focused helper covers.
|
|
- Use JSON Patch only for general structural edits.
|
|
6. Save an artifact.
|
|
- Draft artifact:
|
|
`wf draft save <workspace_id> --artifact <artifact_id> --version 1 --title "Workflow Title"`
|
|
- Complete raw plan:
|
|
`wf artifact create-from-plan workflow.plan.json --artifact <artifact_id> --version 1 --title "Workflow Title" --outcome ok`
|
|
7. Save and validate a deployment.
|
|
- `wf deploy save <deployment_id> --artifact <artifact_id> --version 1 --binding <logical_source>=<concrete_source>` (or `wf deploy create` alias)
|
|
- `wf deploy validate <deployment_id>`
|
|
8. Run the deployment.
|
|
9. Inspect the run summary first; read bounded traces only when needed.
|
|
|
|
## Raw Plan Escape Hatch
|
|
|
|
Draft workspaces are the normal interactive authoring path. If a compiler,
|
|
fixture, or advanced client already has a complete raw JSON/YAML workflow plan,
|
|
use the CLI escape hatch instead of writing a helper script around the Python
|
|
API:
|
|
|
|
```bash
|
|
wf artifact create-from-plan workflow.plan.json \
|
|
--artifact <artifact_id> \
|
|
--version 1 \
|
|
--title "Workflow Title" \
|
|
--outcome ok \
|
|
--binding <logical_source>=<concrete_source>
|
|
```
|
|
|
|
Do not pass draft JSON to `artifact create-from-plan`. Drafts use `steps`,
|
|
`routes`, and step field `use`. Raw plans use `nodes`, `edges`, and node field
|
|
`node`. See `direct-plan-import.md` for the exact shape.
|
|
|
|
Then continue with the normal deployment and run steps:
|
|
|
|
```bash
|
|
wf deploy save <deployment_id> --artifact <artifact_id> --version 1
|
|
wf deploy validate <deployment_id>
|
|
wf run start <deployment_id> --input-file input.json
|
|
```
|
|
|
|
If artifact save returns `suggested_bindings`, include each suggestion as a
|
|
deployment binding:
|
|
|
|
```bash
|
|
wf deploy save <deployment_id> \
|
|
--artifact <artifact_id> \
|
|
--version 1 \
|
|
--binding <logical_source>=<concrete_source>
|
|
```
|
|
|
|
If no suggestion is present, do not guess an account-like source binding; inspect
|
|
sources and choose the concrete source explicitly.
|
|
|
|
## Object Model
|
|
|
|
- **Source**: owner of capabilities, such as `wf.std` or `everything.default`.
|
|
- **Workflow capability**: graph-ready `NodeSpec` or saved wrapper artifact.
|
|
- **Artifact**: immutable saved workflow or wrapper.
|
|
- **Deployment**: mutable binding from artifact version to concrete sources.
|
|
- **Run**: durable stopped execution record with status, output, and trace count.
|
|
|
|
## Result Handling
|
|
|
|
`wf run start` returns compact status by default. Capture `run_id` even for
|
|
completed or failed runs. Use:
|
|
|
|
- `wf run inspect <run_id>` for compact stored result.
|
|
- `wf run trace <run_id> --from 0 --limit 25` for explicit debug slices.
|
|
- `wf run resume <run_id>` only for interrupted runs.
|
|
|
|
Do not ask for unbounded traces.
|
|
|
|
## Interrupt Resume Contracts
|
|
|
|
An interrupted run can carry a self-describing resume contract. Treat
|
|
`interrupt.resume_schema` from `wf run inspect` as the source of truth for the
|
|
payload you pass to `wf run resume`. Do not read workflow source code just to
|
|
guess approval fields when the schema is present.
|