Skip to main content
AKOS

Flows

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. See run modes.
  • 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:

KindIconDescription
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:

ModeWho uses it
GUI — visual drag-and-drop canvasOperators and builders
YAML — committed to version controlConfig-driven and GitOps workflows
Code — TypeScript objectsDevelopers 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.

On this page

Flows · AKOS