---
title: "Workflows overview"
description: "Declarative multi-step agent DAGs with attenuated subagents."
source: https://carina.nebutra.com/workflows/overview/
---

# Workflows overview

> Declarative multi-step agent DAGs with attenuated subagents.

A workflow is a declarative multi-step agent pipeline: a **dependency DAG** of steps, each delegated to an isolated, capability-attenuated subagent, with every step audited and (in streaming mode) resumable.

Source: `docs/workflows.md`. Schema: `protocol/schemas/workflow-graph.schema.json`.

## Topology

## Writing a workflow

Workflows live as JSON under `.carina/workflows/`:

```json title="review.json" showLineNumbers
{
  "name": "review",
  "description": "Scan changed files, review in parallel, then synthesize a report.",
  "steps": [
    {"id": "scan",   "agent": "scout",    "task": "List the files changed in the working tree."},
    {"id": "bugs",   "agent": "reviewer", "task": "Review for bugs:\n${scan}", "needs": ["scan"]},
    {"id": "perf",   "agent": "reviewer", "task": "Review for perf:\n${scan}", "needs": ["scan"]},
    {"id": "report", "agent": "writer",   "task": "Synthesize:\n${bugs}\n${perf}", "needs": ["bugs", "perf"]}
  ]
}
```

- `${step_id}` interpolates a completed dependency's whole output
- `needs` is the only required ordering constraint
- Steps with no shared dependency run in parallel

Example in-repo: `examples/workflows/review.json`.

  Each step runs under a child profile that cannot exceed the outer session's capabilities — so a parallel reviewer cannot gain network or secret access the parent never had.

## Running

```bash title="workflow.sh"
carina workflow run review
carina workflow run review "focus on auth"
carina workflow run review --session sess_123
carina workflow run review --background
carina workflow list
carina workflow status RUN_ID
carina workflow pause|resume|stop|restart RUN_ID
```

Without `--background`, the CLI polls until terminal state and exits non-zero for anything other than `completed`.

| Command | Behavior |
| --- | --- |
| `stop` | Cancel run context; durable run → `stopped` |
| `pause` | Stop admitting newly-ready nodes; running work may finish |
| `resume` | Release nodes that became ready while paused |
| `restart` | New run ID and attempt from a terminal run |

Also available over RPC (`workflow.run`, `workflow.list`, …) and via the agent tool:

```json title="tool-call.json"
{"tool":"workflow","workflow":"review","task":"..."}
```

## Execution modes

### BSP (default)

Runs steps in dependency **levels**: collect every ready step, wait for **all** to finish, then next level. Simple, but one slow step stalls siblings; a single failure aborts the whole run. Step ceiling: 64.

### Streaming

```json title="streaming.json"
"execution_mode": "streaming"
```

Dispatches a step the instant its own dependencies resolve. Higher step ceiling (1000). Failures isolate to dependents by default; `"fail_fast": true` on a step restores abort-everything. Use for uneven durations or large graphs.

Example: `examples/workflows/swarm-review.json`.

### Conditional edges

```json title="conditional.json"
{"id": "bugs", "agent": "reviewer", "needs": ["scan"],
 "when": {">": [{"var": "scan.count"}, 0]},
 "input": {"files": "${scan.files}"},
 "task": "Review the given files for correctness bugs."}
```

`input` resolves against a dependency's **JSON-parsed** output.

  Keep write capabilities off until after a human checkpoint when the pipeline can mutate code. See the [review tutorial](/workflows/tutorial-review/).

## Source of truth

- Narrative: `docs/workflows.md` · examples under `examples/workflows/`
- CLI: `carina workflow run|list|status|pause|resume|stop|restart`
- Related: [Sub-agents](/agents/sub-agents/) · [Policy](/concepts/policy/) · [Workers](/deployment/workers/)

## Next

- [Review tutorial](/workflows/tutorial-review/) — end-to-end pipeline
- [Common workflows](/getting-started/common-workflows/) — day-to-day recipes

---
Source: https://carina.nebutra.com/workflows/overview/
Markdown: https://carina.nebutra.com/workflows/overview/index.md