# limenagent/prodagent architecture

> Architecture diagram of the GitHub repository limenagent/prodagent, 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/limenagent/prodagent
- Repository: https://github.com/limenagent/prodagent

## Overview

prodagent is a small, dependency-free agent runtime: applications compose agent and workflow strategies from a shared execution kernel. A typical run enters through the Agent or Workflow facade, executes graph nodes in scheduler waves, and can invoke a model or governed tools; runs may suspend for approval and resume. The kernel records events as its source of truth, enabling state reconstruction, replay, artifacts, and traces. The playground exposes scenarios and run data in a browser. Some runtime modules are indexed but unsampled, so their internal links are omitted unless documented.

Main entry points: [`src/kernel/scheduler.py`](https://github.com/limenagent/prodagent/blob/main/src/kernel/scheduler.py) (Wave scheduler), [`src/playground/server.py`](https://github.com/limenagent/prodagent/blob/main/src/playground/server.py) (Playground server), [`src/runtime/agent.py`](https://github.com/limenagent/prodagent/blob/main/src/runtime/agent.py) (Agent runner), [`src/runtime/workflow.py`](https://github.com/limenagent/prodagent/blob/main/src/runtime/workflow.py) (Workflow graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Agent API"]
  node_facade["Public facade<br/>[__init__.py]"]
end

subgraph group_runtime["Runtime strategies"]
  node_agent["Agent runner<br/>[agent.py]"]
  node_workflow["Workflow graph<br/>[workflow.py]"]
  node_react["ReAct loop<br/>[react.py]"]
  node_context["Agent context<br/>[context.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_skills["Agent skills<br/>[skills.py]"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
  node_mcp["MCP adapter<br/>[mcp.py]"]
  node_llm["Model selection<br/>[llm.py]"]
  node_openai["OpenAI-compatible client<br/>[openai_lite.py]"]
end

subgraph group_kernel["Execution kernel"]
  node_plan["Plan and nodes<br/>[graph.py]"]
  node_body["Executable bodies<br/>[body.py]"]
  node_scheduler["Wave scheduler<br/>[scheduler.py]"]
  node_run["Run state machine<br/>[run.py]"]
  node_channels["State reducers<br/>[channels.py]"]
  node_commands["Routing commands<br/>[command.py]"]
  node_bus["Observe and approve<br/>[bus.py]"]
end

subgraph group_state["Run records"]
  node_eventlog[("Event log<br/>[eventlog.py]")]
  node_replay["Replay runs<br/>[replay.py]"]
  node_blobs["Artifact storage<br/>[blob.py]"]
  node_blob_backend[("File blob backend<br/>[blob_store.py]")]
  node_trace["Run traces<br/>[trace.py]"]
end

subgraph group_playground["Browser playground"]
  node_playground["Playground server<br/>[server.py]"]
  node_scenarios["Scenario catalog<br/>[scenarios.py]"]
  node_web["Browser interface<br/>[web.py]"]
end

node_user(("Application caller"))
node_playground_user(("Playground user"))

node_user -->|"calls"| node_facade
node_facade -->|"exports"| node_agent
node_facade -->|"exports"| node_workflow
node_agent -->|"uses"| node_react
node_agent -->|"uses"| node_tool_registry
node_workflow -->|"uses"| node_react
node_workflow -->|"uses"| node_tool_registry
node_agent -->|"hosts runs"| node_scheduler
node_workflow -->|"hosts runs"| node_scheduler
node_react -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"adapts tools"| node_mcp
node_react -.->|"requests completions"| node_llm
node_llm -->|"selects client"| node_openai
node_scheduler -->|"checks readiness"| node_plan
node_scheduler -->|"advances"| node_run
node_scheduler -->|"executes nodes"| node_body
node_scheduler -->|"commits events"| node_eventlog
node_scheduler -->|"publishes events"| node_bus
node_scheduler -->|"stores artifacts"| node_blobs
node_run -->|"folds state"| node_channels
node_run -->|"applies routing"| node_commands
node_eventlog -->|"folds deltas"| node_channels
node_replay -->|"reads events"| node_eventlog
node_replay -->|"rebuilds run"| node_run
node_trace -->|"projects events"| node_eventlog
node_blob_backend -->|"implements storage"| node_blobs
node_playground_user -->|"uses"| node_web
node_web -->|"sends requests"| node_playground
node_playground -->|"loads scenarios"| node_scenarios
node_playground -->|"runs scenarios"| node_agent
node_playground -->|"builds run traces"| node_trace
node_playground -->|"loads artifact bytes"| node_blobs

click node_facade "https://github.com/limenagent/prodagent/blob/main/src/__init__.py"
click node_agent "https://github.com/limenagent/prodagent/blob/main/src/runtime/agent.py"
click node_workflow "https://github.com/limenagent/prodagent/blob/main/src/runtime/workflow.py"
click node_react "https://github.com/limenagent/prodagent/blob/main/src/runtime/react.py"
click node_context "https://github.com/limenagent/prodagent/blob/main/src/runtime/context.py"
click node_memory "https://github.com/limenagent/prodagent/blob/main/src/runtime/memory.py"
click node_skills "https://github.com/limenagent/prodagent/blob/main/src/runtime/skills.py"
click node_tool_registry "https://github.com/limenagent/prodagent/blob/main/src/runtime/tools.py"
click node_mcp "https://github.com/limenagent/prodagent/blob/main/src/runtime/mcp.py"
click node_llm "https://github.com/limenagent/prodagent/blob/main/src/runtime/llm.py"
click node_openai "https://github.com/limenagent/prodagent/blob/main/src/runtime/openai_lite.py"
click node_plan "https://github.com/limenagent/prodagent/blob/main/src/kernel/graph.py"
click node_body "https://github.com/limenagent/prodagent/blob/main/src/kernel/body.py"
click node_scheduler "https://github.com/limenagent/prodagent/blob/main/src/kernel/scheduler.py"
click node_run "https://github.com/limenagent/prodagent/blob/main/src/kernel/run.py"
click node_channels "https://github.com/limenagent/prodagent/blob/main/src/kernel/channels.py"
click node_commands "https://github.com/limenagent/prodagent/blob/main/src/kernel/command.py"
click node_bus "https://github.com/limenagent/prodagent/blob/main/src/kernel/bus.py"
click node_eventlog "https://github.com/limenagent/prodagent/blob/main/src/kernel/eventlog.py"
click node_replay "https://github.com/limenagent/prodagent/blob/main/src/kernel/replay.py"
click node_blobs "https://github.com/limenagent/prodagent/blob/main/src/kernel/blob.py"
click node_blob_backend "https://github.com/limenagent/prodagent/blob/main/src/backends/blob_store.py"
click node_trace "https://github.com/limenagent/prodagent/blob/main/src/kernel/trace.py"
click node_playground "https://github.com/limenagent/prodagent/blob/main/src/playground/server.py"
click node_scenarios "https://github.com/limenagent/prodagent/blob/main/src/playground/scenarios.py"
click node_web "https://github.com/limenagent/prodagent/blob/main/src/playground/web.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_facade,node_playground_user toneBlue
class node_agent,node_workflow,node_react,node_context,node_memory,node_skills,node_tool_registry,node_mcp,node_llm,node_openai toneAmber
class node_plan,node_body,node_scheduler,node_run,node_channels,node_commands,node_bus toneMint
class node_eventlog,node_replay,node_blobs,node_blob_backend,node_trace toneRose
class node_playground,node_scenarios,node_web,node_user toneIndigo
```

## Components

### Agent API

- [Public facade](https://github.com/limenagent/prodagent/blob/main/src/__init__.py): `src/__init__.py`

### Runtime strategies

- [Agent runner](https://github.com/limenagent/prodagent/blob/main/src/runtime/agent.py): `src/runtime/agent.py`
- [Workflow graph](https://github.com/limenagent/prodagent/blob/main/src/runtime/workflow.py): `src/runtime/workflow.py`
- [ReAct loop](https://github.com/limenagent/prodagent/blob/main/src/runtime/react.py): `src/runtime/react.py`
- [Agent context](https://github.com/limenagent/prodagent/blob/main/src/runtime/context.py): `src/runtime/context.py`
- [Agent memory](https://github.com/limenagent/prodagent/blob/main/src/runtime/memory.py): `src/runtime/memory.py`
- [Agent skills](https://github.com/limenagent/prodagent/blob/main/src/runtime/skills.py): `src/runtime/skills.py`
- [Tool registry](https://github.com/limenagent/prodagent/blob/main/src/runtime/tools.py): `src/runtime/tools.py`
- [MCP adapter](https://github.com/limenagent/prodagent/blob/main/src/runtime/mcp.py): `src/runtime/mcp.py`
- [Model selection](https://github.com/limenagent/prodagent/blob/main/src/runtime/llm.py): `src/runtime/llm.py`
- [OpenAI-compatible client](https://github.com/limenagent/prodagent/blob/main/src/runtime/openai_lite.py): `src/runtime/openai_lite.py`

### Execution kernel

- [Plan and nodes](https://github.com/limenagent/prodagent/blob/main/src/kernel/graph.py): `src/kernel/graph.py`
- [Executable bodies](https://github.com/limenagent/prodagent/blob/main/src/kernel/body.py): `src/kernel/body.py`
- [Wave scheduler](https://github.com/limenagent/prodagent/blob/main/src/kernel/scheduler.py): `src/kernel/scheduler.py`
- [Run state machine](https://github.com/limenagent/prodagent/blob/main/src/kernel/run.py): `src/kernel/run.py`
- [State reducers](https://github.com/limenagent/prodagent/blob/main/src/kernel/channels.py): `src/kernel/channels.py`
- [Routing commands](https://github.com/limenagent/prodagent/blob/main/src/kernel/command.py): `src/kernel/command.py`
- [Observe and approve](https://github.com/limenagent/prodagent/blob/main/src/kernel/bus.py): `src/kernel/bus.py`

### Run records

- [Event log](https://github.com/limenagent/prodagent/blob/main/src/kernel/eventlog.py): `src/kernel/eventlog.py`
- [Replay runs](https://github.com/limenagent/prodagent/blob/main/src/kernel/replay.py): `src/kernel/replay.py`
- [Artifact storage](https://github.com/limenagent/prodagent/blob/main/src/kernel/blob.py): `src/kernel/blob.py`
- [File blob backend](https://github.com/limenagent/prodagent/blob/main/src/backends/blob_store.py): `src/backends/blob_store.py`
- [Run traces](https://github.com/limenagent/prodagent/blob/main/src/kernel/trace.py): `src/kernel/trace.py`

### Browser playground

- [Playground server](https://github.com/limenagent/prodagent/blob/main/src/playground/server.py): `src/playground/server.py`
- [Scenario catalog](https://github.com/limenagent/prodagent/blob/main/src/playground/scenarios.py): `src/playground/scenarios.py`
- [Browser interface](https://github.com/limenagent/prodagent/blob/main/src/playground/web.py): `src/playground/web.py`

### Other components

- **Application caller**
- **Playground user**

## Connections

- Application caller → Public facade: calls (evidence: `README.md`)
- Public facade → Agent runner: exports (evidence: `src/__init__.py`)
- Public facade → Workflow graph: exports (evidence: `src/__init__.py`)
- Agent runner → ReAct loop: uses (evidence: `src/runtime/agent.py`)
- Agent runner → Tool registry: uses (evidence: `src/runtime/agent.py`)
- Workflow graph → ReAct loop: uses (evidence: `src/runtime/workflow.py`)
- Workflow graph → Tool registry: uses (evidence: `src/runtime/workflow.py`)
- Agent runner → Wave scheduler: hosts runs (evidence: `src/runtime/agent.py`)
- Workflow graph → Wave scheduler: hosts runs (evidence: `src/runtime/workflow.py`)
- ReAct loop → Tool registry: dispatches tools (evidence: `src/runtime/react.py`)
- Tool registry → MCP adapter: adapts tools (evidence: `src/runtime/mcp.py`)
- ReAct loop → Model selection: requests completions
- Model selection → OpenAI-compatible client: selects client (evidence: `src/runtime/llm.py`)
- Wave scheduler → Plan and nodes: checks readiness (evidence: `src/kernel/scheduler.py`)
- Wave scheduler → Run state machine: advances (evidence: `src/kernel/scheduler.py`)
- Wave scheduler → Executable bodies: executes nodes (evidence: `src/kernel/scheduler.py`)
- Wave scheduler → Event log: commits events (evidence: `src/kernel/scheduler.py`)
- Wave scheduler → Observe and approve: publishes events (evidence: `src/kernel/scheduler.py`)
- Wave scheduler → Artifact storage: stores artifacts (evidence: `src/kernel/scheduler.py`)
- Run state machine → State reducers: folds state (evidence: `src/kernel/run.py`)
- Run state machine → Routing commands: applies routing (evidence: `src/kernel/run.py`)
- Event log → State reducers: folds deltas (evidence: `src/kernel/eventlog.py`)
- Replay runs → Event log: reads events (evidence: `src/kernel/replay.py`)
- Replay runs → Run state machine: rebuilds run (evidence: `src/kernel/replay.py`)
- Run traces → Event log: projects events (evidence: `src/kernel/trace.py`)
- File blob backend → Artifact storage: implements storage (evidence: `src/backends/blob_store.py`)
- Playground user → Browser interface: uses
- Browser interface → Playground server: sends requests (evidence: `src/playground/server.py`)
- Playground server → Scenario catalog: loads scenarios (evidence: `src/playground/server.py`)
- Playground server → Agent runner: runs scenarios (evidence: `src/playground/server.py`)
- Playground server → Run traces: builds run traces (evidence: `src/playground/server.py`)
- Playground server → Artifact storage: loads artifact bytes (evidence: `src/playground/server.py`)
