How microsoft/agent-lightning works
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: store Store · trainer Trainer · runner Runner · algorithm Algorithms
Components 18
Core library
Python package that defines the agent-lightning runtime, data model, training, and store boundaries.
- Runner · Executes host agents while preserving framework behavior.
agentlightning/runner - LitAgent · Decorator and runtime shim for instrumented agent execution.
agentlightning/litagent - Adapters · Normalizes framework-specific messages and triplets into shared structures.
agentlightning/adapter - Emitter · Defines rewards, annotations, exceptions, messages, and emitted objects.
agentlightning/emitter - Types · Core, resource, and tracer type definitions shared across the system.
agentlightning/types - Store · Central hub for tasks, traces, resources, and rollout state.
agentlightning/store - Execution · Client/server, inter-process, and shared-memory execution variants.
agentlightning/execution - Algorithms · Training logic that reads the store and publishes updated artifacts.
agentlightning/algorithm - Trainer · Coordinates initialization, registry, datasets, runners, store, and algorithms.
agentlightning/trainer - VERL · RL-style training and async service entrypoints.
agentlightning/verl
Operations
Serving, observability, and operational tooling around the core loop.
- Tracer · Tracer interfaces and integrations for OpenTelemetry and third-party tools.
agentlightning/tracer - Instrumentation · Adapters for AgentOps, LiteLLM, Weave, and vLLM instrumentation.
agentlightning/instrumentation - CLI · Operational entrypoints for store, Prometheus, and vLLM workflows.
agentlightning/cli - Server tools · Store and LLM proxy/server utilities around the core loop.
agentlightning/server.py - Docker · Compose files and container assets for store, metrics, and dashboards.
docker
Dashboard
Separate frontend for inspecting traces, resources, rollouts, and workers.
- Dashboard · React app for resources, traces, rollouts, workers, and settings.
dashboard
Connections 22
- 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.