Agent Lightning Repo Skill
Use this skill when a user asks for help with Agent Lightning (agentlightning): writing trainable agents, collecting spans and rewards, coordinating runners/stores/trainers/algorithms, using agl services, selecting example recipes, or diagnosing package/backend issues.
Agent Lightning's core loop is: a runner executes a LitAgent, a tracer emits spans into a LightningStore, algorithms read those traces and update resources, and Trainer wires those components together.
First steps for any task
- Identify the user's workflow and route to the nearest sub-skill below.
- If the user is using a different checkout or package version, read repo provenance before relying on version-sensitive details.
- For install or import trouble, run or adapt scripts/check_agentlightning_install.py and read compatibility plus cross-cutting troubleshooting.
- Treat GPU, MongoDB, cloud API, W&B/Tinker, Docker/SWE-bench, and dashboard workflows as optional unless the user explicitly provides those resources.
Route map
| User intent | Use this sub-skill | What it contains |
|---|---|---|
Write or wrap an agent, fix @rollout signatures, use PromptTemplate or LLM, debug one rollout | agent-authoring | Agent function/class patterns, resource injection, return contracts, runner single-step smoke |
| Emit rewards/messages/objects, inspect spans, adapt traces to messages/triplets, debug missing token IDs | tracing-and-instrumentation | OtelTracer, AgentOpsTracer, emitters, operation, adapters, trace troubleshooting |
Operate LightningStore, runners, algorithms, Trainer.fit, Trainer.dev, status/retry behavior | runner-store-training | Store API, rollout/attempt lifecycle, resources, custom algorithms, training loop recipes |
Use agl CLI, store/prometheus services, LLM proxy, vLLM bridge, endpoint checks, metrics | cli-and-services | Help-confirmed CLI flags, service launch patterns, safe LiteLLM/OpenAI-compatible checks |
| Choose or adapt examples such as APO, SQL, RAG, ChartQA, Unsloth, Azure, Claude Code, Tinker | examples-and-recipes | Example/backend catalog, optional dependency matrix, maintainer example rules |
Installation orientation
General use:
bashpython -m pip install --upgrade agentlightning python - <<'PY' import agentlightning as agl print(agl.__version__) print(type(agl.InMemoryLightningStore()).__name__) PY
For source development, use the repository's uv workflow and choose only the optional groups needed for the task. CPU-only work can inspect and run base package APIs without CUDA. APO requires the apo extra (poml) plus an OpenAI-compatible endpoint for full examples. VERL/vLLM/Unsloth/vision/RAG examples require larger dependency groups and usually CUDA-compatible hardware.
Core public objects to recognize
- Agent authoring:
rollout,llm_rollout,prompt_rollout,LitAgent,PromptTemplate,LLM,ProxyLLM,NamedResources. - Execution:
LitAgentRunner,Runner,Hook,Trainer,Algorithm,FastAlgorithm,Baseline,algo. - Store/control plane:
LightningStore,InMemoryLightningStore,LightningStoreClient,LightningStoreServer,LightningStoreThreaded,RolloutConfig. - Tracing:
OtelTracer,AgentOpsTracer,DummyTracer,emit_reward,emit_message,emit_object,emit_exception,operation,find_final_reward,TracerTraceToTriplet,LlmProxyTraceToTriplet,TraceToMessages. - Services:
agl,LLMProxy,ProxyLLM, metrics backends, OpenAI-compatible endpoint patterns.
Fast validation
Use this when a user asks whether the installed package is basically usable:
bashpython scripts/check_agentlightning_install.py
For deeper workflow checks, run the nearest sub-skill smoke script:
- Agent authoring:
python sub-skills/agent-authoring/scripts/agent_rollout_smoke.py - Tracing:
python sub-skills/tracing-and-instrumentation/scripts/local_trace_smoke.py - Store/training control plane:
python sub-skills/runner-store-training/scripts/store_status_smoke.py - Services:
python sub-skills/cli-and-services/scripts/check_litellm_proxy.py --helporpython sub-skills/cli-and-services/scripts/check_prometheus_metrics.py --duration 1 --host 127.0.0.1
Run scripts from the generated skill directory or pass explicit paths/URLs where the script supports them. The scripts are safe by default: they do not train models, download data, mutate Docker/Mongo/Ray, or print secrets.
Known limits
This skill was verified for CPU-compatible package import, CLI help, and in-memory store/runner/tracing smokes. It preserves guidance for optional GPU/cloud/service workflows but does not claim those backends were available or verified. When a user requests optional workflows, first confirm or detect the required hardware, credentials, endpoints, datasets, and dependency groups before running expensive commands.
