Flows and Runs

Create flows from templates, execute them, inspect results, model what-if changes, and manage human-in-the-loop approvals.

Flows are the unit of work in AKOS: a directed graph of agent and tool nodes that executes a multi-step process. The CLI lets you scaffold flows from built-in templates, run them in several modes, inspect their output, and project the impact of model or configuration changes.

Creating a flow

Browse templates

agentskit-os flow new --list

Filter templates by persona:

agentskit-os flow new --list --persona developer

Scaffold a flow into your workspace config

agentskit-os flow new <template-id>

For example:

agentskit-os flow new summarize-slack-dms

This merges the template's flow (and any required agents) into your agentskit-os.config.yaml. If a flow with the same ID already exists, the command exits with an error unless you pass --replace.

flow new options

Flag	Description
`--list`	List available templates and exit
`--persona <p>`	With `--list`, filter/order templates for a persona
`--target <path>`	Config file to merge into (default: `agentskit-os.config.yaml`)
`--flow-id <slug>`	Override the scaffolded flow ID
`--replace`	Replace an existing flow with the same ID
`--estimate`	Print a hint to run a cost estimate after scaffolding
`--visual`	Also write a visual layout document under `.agentskitos/flows/`
`--visual-out <path>`	Write the visual layout document to a custom path

Running a flow

agentskit-os run agentskit-os.config.yaml

By default, flows run in dry_run mode — the flow graph is traversed and logged but no LLM calls or external side effects are made. This is safe for testing your configuration.

Run modes

Mode	Description
`dry_run`	Traverse the flow without LLM calls or side effects (default)
`real`	Execute fully with live LLM calls and tool actions
`durable`	Like `real`, but checkpointed so interrupted runs can be resumed

# Dry run (default)
agentskit-os run agentskit-os.config.yaml
 
# Live run
agentskit-os run agentskit-os.config.yaml --mode real
 
# Durable run (checkpointed)
agentskit-os run agentskit-os.config.yaml --mode durable --store ./run-checkpoints

Selecting a specific flow

When your config has multiple flows, specify which one to run:

agentskit-os run agentskit-os.config.yaml --flow summarize-slack-dms

Resuming an interrupted run

agentskit-os run agentskit-os.config.yaml \
  --mode durable \
  --store ./run-checkpoints \
  --resume <run-id>

--resume requires --store.

Cost estimate

Print an estimated cost and exit without executing the flow:

agentskit-os run agentskit-os.config.yaml --estimate

run options

Flag	Description
`--flow <id>`	Flow ID to execute (required when config has multiple flows)
`--mode <mode>`	Run mode: `dry_run`, `real`, `durable` (default: `dry_run`)
`--workspace <id>`	Override workspace ID
`--store <dir>`	Checkpoint directory for durable mode
`--resume <runId>`	Resume an existing run (requires `--store`)
`--estimate`	Print cost estimate and exit
`--force`	Skip budget limit check
`--strict`	In `real` mode, error when LLM credentials are missing instead of falling back
`--quiet`	Suppress per-node event output

Listing past runs

agentskit-os runs list

Shows recent runs with their flow ID, status, cost, and token counts.

Add --json for structured output. Use --limit <n> to control how many results are returned.

Explaining a run

After a coding agent run that captured artifact bundles, use explain to get a plain-English step-by-step walkthrough:

agentskit-os explain --artifact-dir ./run-artifacts

Filter to a specific run ID:

agentskit-os explain --artifact-dir ./run-artifacts --run-id <run-id>

Output as structured JSON:

agentskit-os explain --artifact-dir ./run-artifacts --json

The --artifact-dir should point to the directory passed to --capture-run-artifacts when the run was started.

What-if analysis

Project how a change to token budget, latency, cost, or pass rate would affect your historical runs without re-running them.

Prepare a JSON file of past run snapshots:

[
  { "id": "run-1", "costUsd": 0.005, "latencyMs": 900, "passed": true },
  { "id": "run-2", "costUsd": 0.007, "latencyMs": 1200, "passed": false }
]

Then project the impact:

# What if we switched to a model that costs 30% less?
agentskit-os whatif runs.json --cost 0.7
 
# What if tokens were reduced by 20% and latency improved by 10%?
agentskit-os whatif runs.json --tokens 0.8 --latency 0.9
 
# What if pass rate dropped by 5 percentage points?
agentskit-os whatif runs.json --pass -0.05

Options:

Flag	Description
`--tokens <m>`	Token count multiplier (e.g. `0.7` = 30% fewer tokens)
`--latency <m>`	Latency multiplier
`--cost <m>`	Cost multiplier
`--pass <d>`	Pass-rate delta in the range `[-1, 1]`
`--json`	Emit JSON instead of the summary table

Human-in-the-loop (HITL) approvals

When a flow escalates a decision to a human reviewer, use hitl to list and act on pending escalations via the running workspace sidecar.

List escalations

# All escalations
agentskit-os hitl list
 
# Filter by status
agentskit-os hitl list --status open
agentskit-os hitl list --status approved
agentskit-os hitl list --status rejected

Approve an escalation

agentskit-os hitl approve <escalation-id>
 
# With a note and signer
agentskit-os hitl approve <escalation-id> \
  --note "Reviewed and looks correct" \
  --signer alice@example.com

Reject an escalation

agentskit-os hitl reject <escalation-id> --note "Data quality issue — re-run after fix"

--note is required when rejecting.

Reassign an escalation

agentskit-os hitl reassign <escalation-id> bob@example.com

Submit a counter-proposal

agentskit-os hitl modify <escalation-id> "Use the revised budget figure of 42000"

All HITL commands require the workspace sidecar to be running (agentskit-os serve).

Runs retention

To prune old run records:

agentskit-os runs retention prune

This command removes run records beyond the configured retention policy. Use --dry-run to preview what would be deleted.

Flows and Runs

On this page