agent-lightning

# 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 1. Identify the user's workflow and route to the nearest sub-skill below. 2. If the user is using a different checkout or package version, read [repo provenance](references/repo-provenance.md) before relying on version-sensitive details. 3. For install or import trouble, run or adapt [scripts/check_agentlightning_install.py](scripts/check_agentlightning_install.py) and read [compatibility](references/compatibility.md) plus [cross-cutting troubleshooting](references/troubleshooting.md). 4. 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](sub-skills/agent-authoring/SKILL.md) | 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](sub-skills/tracing-and-instrumentation/SKILL.md) | `OtelTracer`, `AgentOpsTracer`, emitters, `operation`, adapters, trace troubleshooting | | Operate `LightningStore`, runners, algorithms, `Trainer.fit`, `Trainer.dev`, status/retry behavior | [runner-store-training](sub-skills/runner-store-training/SKILL.md) | 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](sub-skills/cli-and-services/SKILL.md) | 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](sub-skills/examples-and-recipes/SKILL.md) | Example/backend catalog, optional dependency matrix, maintainer example rules | ## Installation orientation General use: ```bash python -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: ```bash python 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 --help` or `python 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.