---
title: Flows
description: Anatomy of a flow — a DAG of nodes that drives agents to a goal.
---

A **flow** is a DAG (directed acyclic graph) of steps that drives one or more agents toward a goal. `@agentskit/os-flow` executes flows; `@agentskit/os-core` defines the schema.

## Key properties

- **DAG, not a chain.** Cycles are detected at compile time. Branches are first-class citizens.
- **Durable.** Every node writes a checkpoint before executing. A flow can resume after a crash, a redeploy, or a HITL pause — from exactly the point it paused.
- **Run-mode-aware.** Every node respects the `--mode` flag — sandbox, simulate, or live.
- **Time-travel debuggable.** Pick any historical checkpoint and re-execute from that point forward with new inputs or a different agent.
- **Pre-flight cost estimation.** `--estimate` projects token spend and dollar cost before any LLM call is made.

## Node kinds

A flow is composed of nodes. AKOS ships 14+ node kinds:

| Kind | Icon | Description |
|---|---|---|
| `trigger` | ⚡ | Where the flow starts. Connects to the trigger system. |
| `agent` | 🤖 | Runs a configured agent — the primary compute node. |
| `tool` | 🔧 | Calls a single tool directly, without a reasoning step. |
| `condition` | ◆ | Evaluates an expression and routes to one of two branches. |
| `parallel` | ⇉ | Fans out to multiple branches that run concurrently. |
| `human-gate` | ⏸ | Pauses the run until a human approves or rejects. |
| `rag` | 📚 | Retrieves context from a knowledge source and injects it forward. |
| `output` | ⏹ | Ends the flow and saves the artifact. |

## Anatomy of a flow

A real example: a request-triage flow.

```
⚡ Trigger
    ↓
🤖 Agent: classify request
    ↓
◆ Condition: which path?
   ↙            ↘
🤖 Agent:      🤖 Agent:
  standard       escalate
      ↘         ↙
     ⏸ Human gate: approve
           ↓
       ⏹ Output: artifact saved
```

A trigger fires → an agent classifies → a condition branches → the appropriate agent runs → a human approves → the run completes and an artifact is saved.

## Data flow between nodes

Each node receives a typed input and produces a typed output. Downstream nodes declare which upstream outputs they consume via JSONPath selectors. The schema is validated at build time — wiring a node to an incompatible output fails fast.

## Authoring modes

Because a flow is typed data, three editors are interchangeable views of the same underlying contract:

| Mode | Who uses it |
|---|---|
| **GUI** — visual drag-and-drop canvas | Operators and builders |
| **YAML** — committed to version control | Config-driven and GitOps workflows |
| **Code** — TypeScript objects | Developers extending the system |

Switch freely between modes. They never diverge.

## Live execution

When a flow is running:

- The canvas lights up node-by-node as each step executes.
- Token cost is tracked per node in real time.
- Every node write is checkpointed — the run is pausable and resumable.
- A HITL gate sends a notification to the configured approvers and holds the run until they act.

## Related topics

- **[Workflows in the app](/docs/using-the-app/flows)** — visual editor, snapshots, and import wizard.
- **[Triggers](./triggers)** — the 14 GA event sources that start a flow.
- **[Processes](./pipelines)** — chain multiple flows into ordered, multi-phase work.
- **[Quality checks (Evals)](/docs/using-the-app/evals)** — regression-test flows before promotion.
- **[Run lifecycle](/docs/how-it-works/run-lifecycle)** — the full path from trigger to audit ledger.