cao-workflow

CAO Workflows

A CAO workflow is a Python script you write, validate, and — only after asking the user — run through cao workflow run. Each script drives one or more agent steps through CAO's shared substrate, so you can fan work out across agents, collect their results, and resume a run that was interrupted.

Your job as an author ends at a validated script file on disk. Authoring does NOT run the workflow. Never claim a workflow ran, or will run, when all you did was write it. Running is a separate step the user must approve (see Lifecycle step c).

When to use

Reach for this skill when the user asks to build or run a multi-step or parameterized workflow — for example:

• "Analyze every file in reports/ and summarize the findings."
• "Run a review pipeline: implement, then review, then verify."
• "Do the same batch job but with a different input directory each time."

If the work is a single one-off agent call, you don't need a workflow. Workflows earn their keep when there are multiple steps, fan-out, parameterization, or a need to resume.

The script API

Author scripts import from the cao_workflow package. This package runs only in the script subprocess and imports nothing from cli_agent_orchestrator.* — it talks to CAO over HTTP. Its public surface:

• step(provider, agent, prompt, *, recovery, step_id=None, timeout=None, **opts) -> StepHandle — run one agent step and declare what re-running it would mean. recovery is keyword-only with no default, so omitting it is a TypeError at the call. See "Declaring a recovery policy" below before you pick a value.
• run_step(provider, agent, prompt, *, step_id=None, timeout=None, **opts) -> StepHandle — the same call, declaring no policy. That is the only difference between the two. A recovery= passed to run_step lands in **opts; the server validates it, the shim does not — see below.
• StepHandle has five fields: .step_id, .terminal_id, .output, .status, and .replayed. .replayed qualifies .terminal_id. When it is True the server returned a stored result and ran nothing, and .terminal_id is the ORIGINAL id — it names a terminal that no longer exists. That flag is the only thing standing between you and reading, writing to, or waiting on a dead id, so check it before you touch .terminal_id.
• get_inputs() -> dict — the run's resolved inputs (see Parameterized workflows). Returns {} when nothing was declared; never raises on absence.
• emit_output(value) — print the run-level CAO_WORKFLOW_OUTPUT: sentinel (the run's return).
• ShimError (and ShimIdentityError, ShimTransportError, ShimHTTPError) — the failure hierarchy step and run_step raise. Failures surface unchanged — the shim never retries. A structured HTTP error with a non-empty string detail.kind prints as run-step returned HTTP <status> (<kind>): <message> (without the message suffix when absent); an unstructured error keeps the original run-step returned HTTP <status> text.