# dankosorkin/agent-workflow-sdk architecture

> Architecture diagram of the GitHub repository dankosorkin/agent-workflow-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dankosorkin/agent-workflow-sdk
- Repository: https://github.com/dankosorkin/agent-workflow-sdk

## Overview

agent-workflow-sdk is an async Python library for composing typed-state agent workflows and running them over interchangeable local-agent or LLM backends. The primary path is: a caller builds a graph, compiles it, invokes or streams it, and receives state/events; the runtime executes concurrent super-steps, checkpoints progress, and can suspend for human input and resume later. Documented extensions include prebuilt workflow patterns, persistent cross-run memory, observability, and a queued worker control plane. Some subsystem links are documented rather than verified from complete source excerpts.

Main entry points: [`agentflow/compiled.py`](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/compiled.py) (Compiled graph API), [`agentflow/runtime.py`](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/runtime.py) (Step runtime), [`agentflow/graph.py`](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/graph.py) (Graph builder), [`agentflow/backends/base.py`](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/base.py) (Backend contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow definition"]
  node_graph["Graph builder<br/>[graph.py]"]
  node_state["Typed state<br/>[state.py]"]
  node_patterns["Prebuilt patterns"]
end

subgraph group_execution["Execution"]
  node_compiled["Compiled graph API<br/>[compiled.py]"]
  node_runtime["Step runtime<br/>[runtime.py]"]
  node_events["Events and requests<br/>[events.py]"]
  node_interrupts["Interrupt handling<br/>[interrupts.py]"]
end

subgraph group_backends["Model backends"]
  node_backend_api["Backend contracts<br/>[base.py]"]
  node_local_backends["Local agent CLIs<br/>[claude_code.py]"]
  node_api_backends["LLM providers<br/>[openai.py]"]
end

subgraph group_durability["Durability and memory"]
  node_checkpointer["Checkpoint contract<br/>[base.py]"]
  node_checkpoint_stores[("Checkpoint stores")]
  node_shared_store[("Cross-run memory<br/>[base.py]")]
end

subgraph group_operations["Operations"]
  node_observability["Hooks and telemetry<br/>[observability.py]"]
  node_control_worker["Run workers<br/>[worker.py]"]
  node_run_queue["Run queue<br/>[queue.py]"]
  node_graph_registry["Graph registry<br/>[registry.py]"]
  node_control_records["Run records<br/>[records.py]"]
end

node_caller(("Workflow caller"))

node_caller -->|"builds"| node_graph
node_graph -->|"declares channels"| node_state
node_caller -->|"compiles and invokes"| node_compiled
node_graph -->|"compiles"| node_compiled
node_compiled -->|"runs steps"| node_runtime
node_runtime -->|"folds updates"| node_state
node_runtime -->|"emits events"| node_events
node_compiled -->|"loads and saves"| node_checkpointer
node_checkpointer -.->|"implemented by"| node_checkpoint_stores
node_caller -->|"selects backend"| node_backend_api
node_backend_api -->|"implemented by"| node_local_backends
node_backend_api -->|"implemented by"| node_api_backends
node_local_backends -->|"streams events"| node_events
node_api_backends -->|"streams events"| node_events
node_runtime -.->|"suspends execution"| node_interrupts
node_caller -.->|"uses patterns"| node_patterns
node_caller -.->|"uses persistent memory"| node_shared_store
node_compiled -->|"reports hooks"| node_observability
node_caller -.->|"runs queued work"| node_control_worker
node_control_worker -->|"claims and completes"| node_run_queue
node_control_worker -->|"resolves graph"| node_graph_registry
node_run_queue -->|"handles run records"| node_control_records
node_graph_registry -->|"registers compiled graphs"| node_compiled

click node_graph "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/graph.py"
click node_state "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/state.py"
click node_patterns "https://github.com/dankosorkin/agent-workflow-sdk/tree/main/agentflow/prebuilt"
click node_compiled "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/compiled.py"
click node_runtime "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/runtime.py"
click node_events "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/events.py"
click node_interrupts "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/interrupts.py"
click node_backend_api "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/base.py"
click node_local_backends "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/claude_code.py"
click node_api_backends "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/openai.py"
click node_checkpointer "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/checkpoint/base.py"
click node_checkpoint_stores "https://github.com/dankosorkin/agent-workflow-sdk/tree/main/agentflow/checkpoint"
click node_shared_store "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/store/base.py"
click node_observability "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/observability.py"
click node_control_worker "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/worker.py"
click node_run_queue "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/queue.py"
click node_graph_registry "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/registry.py"
click node_control_records "https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/records.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_graph,node_state,node_patterns toneBlue
class node_compiled,node_runtime,node_events,node_interrupts toneAmber
class node_backend_api,node_local_backends,node_api_backends toneMint
class node_checkpointer,node_checkpoint_stores,node_shared_store toneRose
class node_observability,node_control_worker,node_run_queue,node_graph_registry,node_control_records,node_caller toneIndigo
```

## Components

### Workflow definition

- [Graph builder](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/graph.py): `agentflow/graph.py`
- [Typed state](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/state.py): `agentflow/state.py`
- [Prebuilt patterns](https://github.com/dankosorkin/agent-workflow-sdk/tree/main/agentflow/prebuilt): `agentflow/prebuilt`

### Execution

- [Compiled graph API](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/compiled.py): `agentflow/compiled.py`
- [Step runtime](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/runtime.py): `agentflow/runtime.py`
- [Events and requests](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/events.py): `agentflow/events.py`
- [Interrupt handling](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/interrupts.py): `agentflow/interrupts.py`

### Model backends

- [Backend contracts](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/base.py): `agentflow/backends/base.py`
- [Local agent CLIs](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/claude_code.py): `agentflow/backends/claude_code.py`
- [LLM providers](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/backends/openai.py): `agentflow/backends/openai.py`

### Durability and memory

- [Checkpoint contract](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/checkpoint/base.py): `agentflow/checkpoint/base.py`
- [Checkpoint stores](https://github.com/dankosorkin/agent-workflow-sdk/tree/main/agentflow/checkpoint): `agentflow/checkpoint`
- [Cross-run memory](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/store/base.py): `agentflow/store/base.py`

### Operations

- [Hooks and telemetry](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/observability.py): `agentflow/observability.py`
- [Run workers](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/worker.py): `agentflow/controlplane/worker.py`
- [Run queue](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/queue.py): `agentflow/controlplane/queue.py`
- [Graph registry](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/registry.py): `agentflow/controlplane/registry.py`
- [Run records](https://github.com/dankosorkin/agent-workflow-sdk/blob/main/agentflow/controlplane/records.py): `agentflow/controlplane/records.py`

### Other components

- **Workflow caller**

## Connections

- Workflow caller → Graph builder: builds
- Graph builder → Typed state: declares channels (evidence: `agentflow/graph.py`)
- Workflow caller → Compiled graph API: compiles and invokes
- Graph builder → Compiled graph API: compiles (evidence: `agentflow/graph.py`)
- Compiled graph API → Step runtime: runs steps (evidence: `agentflow/compiled.py`)
- Step runtime → Typed state: folds updates (evidence: `agentflow/runtime.py`)
- Step runtime → Events and requests: emits events (evidence: `agentflow/runtime.py`)
- Compiled graph API → Checkpoint contract: loads and saves (evidence: `agentflow/compiled.py`)
- Checkpoint contract → Checkpoint stores: implemented by (evidence: `agentflow/checkpoint/base.py`)
- Workflow caller → Backend contracts: selects backend
- Backend contracts → Local agent CLIs: implemented by (evidence: `agentflow/backends/claude_code.py`)
- Backend contracts → LLM providers: implemented by (evidence: `agentflow/backends/openai.py`)
- Local agent CLIs → Events and requests: streams events (evidence: `agentflow/backends/claude_code.py`)
- LLM providers → Events and requests: streams events (evidence: `agentflow/backends/openai.py`)
- Step runtime → Interrupt handling: suspends execution
- Workflow caller → Prebuilt patterns: uses patterns
- Workflow caller → Cross-run memory: uses persistent memory (evidence: `agentflow/store/base.py`)
- Compiled graph API → Hooks and telemetry: reports hooks (evidence: `agentflow/compiled.py`)
- Workflow caller → Run workers: runs queued work
- Run workers → Run queue: claims and completes (evidence: `agentflow/controlplane/worker.py`)
- Run workers → Graph registry: resolves graph (evidence: `agentflow/controlplane/worker.py`)
- Run queue → Run records: handles run records (evidence: `agentflow/controlplane/queue.py`)
- Graph registry → Compiled graph API: registers compiled graphs (evidence: `agentflow/controlplane/registry.py`)
