# microsoft/agent-lightning architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/agent-lightning
- Repository: https://github.com/microsoft/agent-lightning

## Overview

1. **Repository shape**
This is a monorepo centered on the Python package `agentlightning`, with two major satellites: a TypeScript/React `dashboard` for inspecting training state, and a large `examples`/`contrib` area that demonstrates integrations with specific agent stacks and workloads.

2. **Core architectural idea**
Agent Lightning is built around a closed loop: an agent runs normally, emits structured interaction data, that data is normalized into traces/spans, stored centrally, then consumed by a training algorithm that produces updated resources such as prompts, policies, or weights. The `trainer` is the coordinator that keeps this loop moving.

3. **Agent/runtime boundary**
The agent-facing side lives in `runner`, `client`, `litagent`, `adapter`, and `emitter`. These modules let a host agent framework continue to execute while Lightning captures prompts, tool calls, messages, rewards, and exceptions with minimal coupling to the agent implementation.

4. **Trace and event model**
The event model is defined by `emitter`, `types`, `adapter/messages.py`, and `adapter/triplet.py`. These components turn heterogeneous agent activity into structured artifacts that the rest of the system can reason about uniformly, which is what makes cross-framework support possible.

5. **LightningStore as the central hub**
The `store` package is the main shared boundary in the system. It has in-memory, SQLite, and MongoDB backends, plus client/server modes and collection abstractions. The store is where tasks, traces, resources, and rollout-related state converge.

6. **Training and optimization layer**
`algorithm` contains the optimization logic. There is a generic algorithm base/decorator layer, an APO implementation, a Fast path, and a `verl` interface for RL-style training pipelines. Algorithms read from the store and publish new resources back into the same system.

7. **Trainer orchestration**
`trainer` is the system coordinator. It owns initialization, registry, and legacy compatibility logic, and is responsible for connecting datasets, runners, the store, and the algorithm. In architecture terms, it is the control plane that sequences ingestion, training, and deployment of updated artifacts.

8. **Execution and process boundaries**
`execution` models how work crosses process boundaries. It includes client/server, inter-process, and shared-memory variants, which indicates the repo supports both local and distributed execution patterns for agent rollouts and data movement.

9. **Observability and instrumentation**
`tracer`, `instrumentation`, `logging`, `utils/otel.py`, and `utils/otlp.py` wire the system into OpenTelemetry-style observability and third-party tooling such as AgentOps, Weave, LiteLLM, and vLLM. This is not just logging; it is part of how agent activity becomes inspectable training data.

10. **CLI and service utilities**
`cli` provides operational entry points for the store, Prometheus, and vLLM-related workflows. `server.py`, `llm_proxy.py`, and `utils/server_launcher.py` support serving and proxying services that sit around the core training loop.

11. **Dashboard and ops UI**
The `dashboard` package is a separate frontend application that visualizes resources, traces, rollouts, and workers. It is backed by its own store/features slices and is paired with Docker/Grafana/Prometheus assets under `docker`, showing that observability and operational inspection are first-class parts of the architecture.

12. **Examples and integration surface**
`examples` and `contrib/recipes` are not just demos; they are reference integration boundaries. They show how the same core library plugs into different agent domains such as RAG, SQL, web shop, Claude Code, Azure, Spider, Tinker, and Unsloth, plus specialized training flows for each.

13. **Deployment and persistence options**
The repo supports multiple storage and monitoring deployment modes through Docker Compose files for MongoDB, Prometheus, Grafana, and combined store setups. This reinforces that persistence and observability are swappable infrastructure concerns around a stable core.

14. **Diagram takeaway**
An accurate architecture diagram should place the agent runtime on one side, the LightningStore in the center, the trainer/algorithm loop on the other side, and the dashboard/telemetry/infrastructure as surrounding planes. The important boundary is not “web app vs backend,” but “agent execution vs centralized training/observation pipeline.”

Main entry points: [`agentlightning/store`](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/store) (Store), [`agentlightning/trainer`](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/trainer) (Trainer), [`agentlightning/runner`](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/runner) (Runner), [`agentlightning/algorithm`](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/algorithm) (Algorithms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core library"]
  node_n_runner["Runner<br/>agent runtime"]
  node_n_litagent["LitAgent<br/>agent wrapper"]
  node_n_adapter["Adapters<br/>trace mapping"]
  node_n_emitter["Emitter<br/>event model"]
  node_n_types["Types<br/>schema model"]
  node_n_store[("Store<br/>central state")]
  node_n_execution["Execution<br/>process boundary"]
  node_n_algorithm["Algorithms<br/>optimization"]
  node_n_trainer["Trainer<br/>control plane"]
  node_n_verl["VERL<br/>rl pipeline"]
end

subgraph group_group_ops["Operations"]
  node_n_tracer["Tracer<br/>observability"]
  node_n_instrumentation["Instrumentation<br/>integrations"]
  node_n_cli["CLI<br/>operations"]
  node_n_server["Server tools<br/>serving<br/>[server.py]"]
  node_n_docker["Docker<br/>infra"]
end

subgraph group_group_ui["Dashboard"]
  node_n_dashboard["Dashboard<br/>frontend app"]
end

subgraph group_group_examples["Examples"]
  node_n_examples["Examples<br/>integration surface"]
  node_n_contrib["Contrib<br/>extensions"]
end

node_n_litagent -->|"captures"| node_n_adapter
node_n_runner -->|"emits"| node_n_emitter
node_n_adapter -->|"uses"| node_n_types
node_n_emitter -->|"writes"| node_n_store
node_n_execution -->|"moves data"| node_n_store
node_n_store -->|"reads"| node_n_algorithm
node_n_algorithm -->|"publishes"| node_n_store
node_n_trainer -->|"orchestrates"| node_n_runner
node_n_trainer -->|"binds"| node_n_store
node_n_trainer -->|"drives"| node_n_algorithm
node_n_trainer -->|"integrates"| node_n_verl
node_n_tracer -->|"observes"| node_n_emitter
node_n_instrumentation -->|"feeds"| node_n_tracer
node_n_cli -->|"operates"| node_n_store
node_n_server -->|"serves"| node_n_store
node_n_dashboard -->|"reads"| node_n_store
node_n_docker -->|"deploys"| node_n_store
node_n_examples -->|"demonstrates"| node_n_runner
node_n_examples -->|"demonstrates"| node_n_trainer
node_n_contrib -->|"extends"| node_n_adapter
node_n_contrib -->|"extends"| node_n_algorithm
node_n_contrib -->|"extends"| node_n_runner

click node_n_runner "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/runner"
click node_n_litagent "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/litagent"
click node_n_adapter "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/adapter"
click node_n_emitter "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/emitter"
click node_n_types "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/types"
click node_n_store "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/store"
click node_n_execution "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/execution"
click node_n_algorithm "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/algorithm"
click node_n_trainer "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/trainer"
click node_n_verl "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/verl"
click node_n_tracer "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/tracer"
click node_n_instrumentation "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/instrumentation"
click node_n_cli "https://github.com/microsoft/agent-lightning/tree/main/agentlightning/cli"
click node_n_server "https://github.com/microsoft/agent-lightning/blob/main/agentlightning/server.py"
click node_n_dashboard "https://github.com/microsoft/agent-lightning/tree/main/dashboard"
click node_n_examples "https://github.com/microsoft/agent-lightning/tree/main/examples"
click node_n_contrib "https://github.com/microsoft/agent-lightning/tree/main/contrib"
click node_n_docker "https://github.com/microsoft/agent-lightning/tree/main/docker"

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_n_runner,node_n_litagent,node_n_adapter,node_n_emitter,node_n_types,node_n_store,node_n_execution,node_n_algorithm,node_n_trainer,node_n_verl toneBlue
class node_n_tracer,node_n_instrumentation,node_n_cli,node_n_server,node_n_docker toneAmber
class node_n_dashboard toneMint
class node_n_examples,node_n_contrib toneRose
```

## Components

### Core library

Python package that defines the agent-lightning runtime, data model, training, and store boundaries.

- [Runner](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/runner): agent runtime · Executes host agents while preserving framework behavior. · `agentlightning/runner`
- [LitAgent](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/litagent): agent wrapper · Decorator and runtime shim for instrumented agent execution. · `agentlightning/litagent`
- [Adapters](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/adapter): trace mapping · Normalizes framework-specific messages and triplets into shared structures. · `agentlightning/adapter`
- [Emitter](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/emitter): event model · Defines rewards, annotations, exceptions, messages, and emitted objects. · `agentlightning/emitter`
- [Types](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/types): schema model · Core, resource, and tracer type definitions shared across the system. · `agentlightning/types`
- [Store](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/store): central state · Central hub for tasks, traces, resources, and rollout state. · `agentlightning/store`
- [Execution](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/execution): process boundary · Client/server, inter-process, and shared-memory execution variants. · `agentlightning/execution`
- [Algorithms](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/algorithm): optimization · Training logic that reads the store and publishes updated artifacts. · `agentlightning/algorithm`
- [Trainer](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/trainer): control plane · Coordinates initialization, registry, datasets, runners, store, and algorithms. · `agentlightning/trainer`
- [VERL](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/verl): rl pipeline · RL-style training and async service entrypoints. · `agentlightning/verl`

### Operations

Serving, observability, and operational tooling around the core loop.

- [Tracer](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/tracer): observability · Tracer interfaces and integrations for OpenTelemetry and third-party tools. · `agentlightning/tracer`
- [Instrumentation](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/instrumentation): integrations · Adapters for AgentOps, LiteLLM, Weave, and vLLM instrumentation. · `agentlightning/instrumentation`
- [CLI](https://github.com/microsoft/agent-lightning/tree/main/agentlightning/cli): operations · Operational entrypoints for store, Prometheus, and vLLM workflows. · `agentlightning/cli`
- [Server tools](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/server.py): serving · Store and LLM proxy/server utilities around the core loop. · `agentlightning/server.py`
- [Docker](https://github.com/microsoft/agent-lightning/tree/main/docker): infra · Compose files and container assets for store, metrics, and dashboards. · `docker`

### Dashboard

Separate frontend for inspecting traces, resources, rollouts, and workers.

- [Dashboard](https://github.com/microsoft/agent-lightning/tree/main/dashboard): frontend app · React app for resources, traces, rollouts, workers, and settings. · `dashboard`

### Examples

Reference integrations and workload-specific training flows.

- [Examples](https://github.com/microsoft/agent-lightning/tree/main/examples): integration surface · Reference agents, trainers, and recipes for different workloads. · `examples`
- [Contrib](https://github.com/microsoft/agent-lightning/tree/main/contrib): extensions · Extra adapters, agents, rewards, and environment-specific training flows. · `contrib`

## Connections

- LitAgent → Adapters: captures · Wraps agent execution and converts interactions through adapter boundaries.
- Runner → Emitter: emits · Runner produces structured events from agent activity.
- Adapters → Types: uses · Adapter output is shaped by shared core/resource types.
- Emitter → Store: writes · Structured events and rewards flow into the central store.
- Execution → Store: moves data · Execution boundaries transport rollout and trace data to shared storage.
- Store → Algorithms: reads · Algorithms consume stored traces, tasks, and resources.
- Algorithms → Store: publishes · Training updates are written back as new resources or policies.
- Trainer → Runner: orchestrates · Trainer launches and coordinates agent runs.
- Trainer → Store: binds · Trainer connects datasets, rollouts, and persistence.
- Trainer → Algorithms: drives · Trainer sequences optimization and artifact updates.
- Trainer → VERL: integrates · Trainer can delegate to VERL-style RL pipelines.
- Tracer → Emitter: observes · Tracing layers mirror or enrich emitted activity.
- Instrumentation → Tracer: feeds · Third-party integrations feed the tracing layer.
- CLI → Store: operates · CLI entrypoints manage store and service workflows.
- Server tools → Store: serves · Server utilities expose store and proxy capabilities.
- Dashboard → Store: reads · Frontend visualizes central state from the store.
- Docker → Store: deploys · Compose assets provide persistence and monitoring backends.
- Examples → Runner: demonstrates · Examples show agent-side integration patterns.
- Examples → Trainer: demonstrates · Examples include workload-specific training flows.
- Contrib → Adapters: extends · Contrib packages add specialized adapters and integrations.
- Contrib → Algorithms: extends · Contrib packages add environment-specific training algorithms.
- Contrib → Runner: extends · Contrib packages add specialized runners and agents.
