release
Prepare and publish stable Agent Lightning releases through the repository's version bump, pull-request checks, merge, tag, PyPI trusted-publishing, and versioned-documentation workflows. Use when asked to plan, cut, verify, or explain a release; treat nightly TestPyPI builds as a separate path.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Agent Lightning was completely refactored in v1.0. For legacy releases earlier than v1.0, see this branch.
⚡ News
- [2026/11] We release a Score Centering example for math reasoning, with GRPO and score centering presets, INT8 inference, and an INT4 Attention KV cache.
- [2026/10] Read our AGL-SKILL: Coding Harnesses as Agentic Optimizers technical report on using coding harnesses to optimize other agents across five benchmarks.
- [2026/09] We release a new coding agent example based on an MoE model. Pure RL improves Qwen3.5-35B-A3B on SWE-bench Verified from 47.8% to 61.6% after training it on only 1.8K training examples!
- [2026/08] Agent Lightning Skill is released. It helps a coding agent improve another AI agent against a benchmark.
- [2026/08] Agent Lightning v1.0 technical report is released!
- [2026/08] We open source Agent Lightning v1.0!
⚡ Key Features
- 🪶 ~3,500 lines of code: We treat simplicity as the first principle.
- 🧩 Train with real agent harnesses: Agents interact with the model through the Agent Lightning v1.0 proxy with ZERO changes, while keeping tools, context, control flow, and environments in the loop.
- ☸️ Native Kubernetes support: Run agents directly as Kubernetes Jobs without relying on external sandbox services.
- 💻 Full coding agent training example: Using only 6K training samples, an end-to-end Qwen3.5-9B workflow improves SWE-bench Verified from 41.8% to 56.4%, a gain of 14.6 percentage points. We release the full pipeline, including data cleaning, reward-hacking prevention, and training scripts. Update: We release a new coding agent training example based on Qwen3.5-35B-A3B. Pure RL improves Qwen3.5-35B-A3B on SWE-bench Verified from 47.8% to 61.6% after only 1.8K training examples, a gain of 13.8 percentage points.
⚡ Installation
The following is an example installation on a CUDA 13.0 machine:
cd <this-repo>
uv sync
bash scripts/setup_verl.sh 0.8.0 cu130
See the Installation Guide for details.
⚡ Architecture
Agent Lightning v1.0 keeps the training architecture simple with three lightweight components:
- Trainer: Runs
verland vLLM, builds training samples, and updates the policy. - API Gateway: Proxies model requests and captures training data.
- Rollout Controller: Runs agents locally or as Kubernetes Jobs.
The Trainer creates rollouts, the Controller launches agents, and the Gateway turns interactions into training data, while agents continue to run with their real harnesses.
⚡ Results
We evaluate Agent Lightning v1.0 across several practical training domains, including Search R1, LLM-in-Sandbox, and Coding Agent. Pure RL delivers substantial improvements across all three domains, as shown below.
⚡ Documentation
| Section | Content |
|---|---|
| Installation | Base environment and verl GPU stack |
| Quick Start | Local first run and end-to-end flow |
| Basics | Components, rollouts, events, and trajectories |
| Trainer Configuration | verl integration and trace aggregation |
| API Gateway Configuration | Gateway and model proxy settings |
| Controller Configuration | Local and Kubernetes runners |
| Asynchronous Training | Collocated async collection and pause/drain |
⚡ Examples
| Example | Description |
|---|---|
| Calc-X | POC math reasoning example with AutoGen and MCP calculator tools, requiring only one GPU. |
| GSM8K | POC grade-school math reasoning example. |
| ScienceWorld | Interactive science tasks in a text-based environment. |
| Search-R1 | Multi-turn retrieval and reasoning agent. |
| LLM-in-Sandbox | General agent with computer and code execution tools. |
| Coding Agent | Coding agent trained with repository tests. |
| Coding Agent: MoE | Train Qwen3.5-35B-A3B with Megatron and R3. |
⚡ Articles
- 8/19/2026 Agent Lightning v1.0: Towards Harnessed Agentic RL technical report.
- 12/17/2025 Adopting the Trajectory Level Aggregation for Faster Training Agent-lightning blog.
- 11/4/2025 Tuning ANY AI agent with Tinker ✕ Agent-lightning Medium. See also Part 2.
- 10/22/2025 No More Retokenization Drift: Returning Token IDs via the OpenAI Compatible API Matters in Agent RL vLLM blog. See also Zhihu writeup.
- 8/11/2025 Training AI Agents to Write and Self-correct SQL with Reinforcement Learning Medium.
- 8/5/2025 Agent Lightning: Train ANY AI Agents with Reinforcement Learning arXiv paper.
- 7/26/2025 We discovered an approach to train any AI agent with RL, with (almost) zero code changes. Reddit.
- 6/6/2025 Agent Lightning - Microsoft Research Project page.
⚡ Community Projects
- DeepWerewolf — A case study of agent RL training for the Chinese Werewolf game built with AgentScope and Agent Lightning.
- [AgentFlow](https:/
// HOW IT'S BUILT
// FILES
3 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.agents/skills/release/SKILL.md11 KB9bb8a0d4a2b1upstream ↗
--- name: release description: Prepare and publish stable Agent Lightning releases through the repository's version bump, pull-request checks, merge, tag, PyPI trusted-publishing, and versioned-documentation workflows. Use when asked to plan, cut, verify, or explain a release; treat nightly TestPyPI builds as a separate path. --- # Release Agent Lightning Merging a pull request does not publish a stable release. Stable publication is triggered only by pushing a `v*` tag to the canonical repository; the tagged commit is what gets tested, built, and uploaded. That same tag push also deploys versioned documentation and moves the public `stable` alias, so a release has two public side effects, not one. ## Establish the release state 1. Confirm the repository root, clean working tree, current branch, and remotes. 2. Resolve the canonical `OWNER/REPO`, its default branch, and its permitted merge methods with `gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef,mergeCommitAllowed,rebaseMergeAllowed,squashMergeAllowed`. Identify the local remotes for that repository and the contributor fork by their URLs; do not assume particular remote names or merge settings. 3. Inspect the release contract in: - `.github/workflows/pypi-release.yml` - `.github/workflows/docs.yml` - `.github/workflows/tests.yml` - `scripts/bump_version.sh` - `pyproject.toml` - `agentlightning/__init__.py` 4. Confirm the canonical default branch is already green before branching from it. Resolve its current commit with `gh api repos/OWNER/REPO/commits/<default-branch>` and inspect that commit's check runs; a general recent-run listing can omit or mix commits. A release branch inherits every failure that main is carrying. 5. Query the canonical repository's tags and compare them with the versions published at `https://pypi.org/pypi/agentlightning/json`. Confirm the target version exists in neither place, and stop for an explicit release decision when either of these holds: - A tag exists with no matching PyPI version. A published version is immutable, and its tag must never be reused or moved. A tag that never published is a different situation and still needs a human decision, informed by why it did not publish. See "Recovering a tag that never published" below. - The proposed bump would skip a version that was tagged but never published. 6. Treat verified PyPI trusted-publisher configuration for the canonical repository and `pypi-release.yml` as a prerequisite. If it cannot be inspected directly, require confirmation from an authorized PyPI project owner before pushing the release tag. ## Prepare and merge the version pull request Start a release branch from a freshly fetched canonical default branch, not from another feature branch. The branch name is only a recommendation: ```bash git fetch <canonical-remote> <default-branch> git switch -c chore/release-vX.Y.Z <canonical-remote>/<default-branch> scripts/bump_version.sh patch # or minor / major ``` The script updates the project version with uv and then edits `agentlightning/__init__.py` separately. If it fails or is interrupted between those writes, only some of the three version files may be updated. Inspect `git diff` after any failure and restore or reconcile all three files before retrying; blindly rerunning a partial patch bump can advance the version twice. The bump rewrites exactly three files. Confirm that with `git diff --stat`: - `pyproject.toml` - the `agentlightning` entry in `uv.lock` - `agentlightning.__version__` in `agentlightning/__init__.py` Other version strings in the tree, such as the FastAPI `version` in `agentlightning/server/app.py`, are deliberately outside the bump. Leave them alone; changing them is a separate pull request, not release work. Review the version diff, but do not run the release tests or package build locally as a matter of course. `tests.yml` runs a broader test suite and the same package build on the pull request, covering the narrower tests and build that `pypi-release.yml` will run on the tag. The pull request's GitHub checks are therefore the verification gate. Reproduce a single failure locally only when the workflow logs are not enough to fix it. Commit the version change, push it to the fork, and open the pull request with the GitHub CLI when those external actions are authorized: ```bash git commit -am "Bump version to X.Y.Z" git push -u <fork-remote> <release-branch> gh pr create --repo OWNER/REPO \ --base <default-branch> \ --head <fork-owner>:<release-branch> \ --title "Bump version to X.Y.Z" \ --body "Prepare the vX.Y.Z release." ``` `gh pr create` refuses to run without `--title` and `--body` outside an interactive terminal, and every `gh` call needs `--repo OWNER/REPO` so it acts on the canonical repository rather than the fork. Follow the pull request through its required checks with `gh pr checks <pr> --repo OWNER/REPO --watch`. If a check fails, take the run id from that output, inspect it with `gh run view <run-id> --repo OWNER/REPO --log-failed`, correct the source on the same branch, and resume watching. Once every required check has succeeded, extract the reviewed head and pass both a permitted merge-method flag from step 2 and `--match-head-commit` to `gh pr merge`: ```bash HEAD_SHA="$(gh pr view <pr> --repo OWNER/REPO --json headRefOid --jq .headRefOid)" gh pr merge <pr> --repo OWNER/REPO <merge-method-flag> \ --match-head-commit "$HEAD_SHA" ``` Replace `<merge-method-flag>` with one permitted flag discovered in step 2: `--merge`, `--rebase`, or `--squash`. Committing, pushing, opening the pull request, and merging are each distinct external actions and each requires authorization. ## Tag and publish the merged release After the pull request merges, update the local default branch from the canonical repository, then confirm that the commit you are about to tag is the one this pull request produced and not a later commit that landed behind it: ```bash git switch <default-branch> git pull --ff-only <canonical-remote> <default-branch> gh pr view <pr> --repo OWNER/REPO --json mergeCommit git rev-parse HEAD ``` If HEAD has moved past the merge commit, tag the merge commit explicitly instead of HEAD. `pypi-release.yml` fails the release when the packaged version does not equal the tag without its leading `v`, or when it does not equal the runtime `__version__`. Check both before tagging: ```bash uv version --short grep '^__version__' agentlightning/__init__.py ``` The workflow itself reads the runtime value as `python -c 'from agentlightning import __version__; print(__version__)'` from the repository root before its dependency-sync step, so Python resolves the checkout through the current working directory. Read the file directly for the local pre-tag check; `agentlightning/__init__.py` assigns `__version__` as a single literal, making that check independent of the active Python environment. GitHub reads workflow files as they exist **at the tagged commit**, not at the tip of the default branch. Confirm that the commit being tagged actually contains `.github/workflows/pypi-release.yml` with its `v*` trigger; a commit that predates the workflow will never publish, however the tag is pushed. Immediately query the canonical repository and PyPI again to ensure that `vX.Y.Z` is still absent. Then create an annotated tag on the release commit and push it to the canonical repository: ```bash git tag -a vX.Y.Z -m "vX.Y.Z" <release-commit> git push <canonical-remote> vX.Y.Z ``` The tag push starts the production PyPI publication, so obtain explicit authorization immediately before it. ## Follow both tag-triggered workflows One tag push starts two workflows, and both belong to the release: - `PyPI Release` (`pypi-release.yml`) re-checks the version against the tag, runs the tests, builds the wheel and source distribution, and uploads them to PyPI through trusted publishing. - `Deploy Documentation` (`docs.yml`) runs `mike deploy --push --update-aliases X.Y.Z stable`, which publishes the versioned documentation and repoints the public `stable` alias at this release. Look up each run by workflow and tag rather than selecting from an unfiltered recent-run list: ```bash gh run list --repo OWNER/REPO --workflow pypi-release.yml \ --branch vX.Y.Z --event push --limit 1 gh run list --repo OWNER/REPO --workflow docs.yml \ --branch vX.Y.Z --event push --limit 1 ``` Confirm both runs have the expected tag commit, then follow them to a terminal result with `gh run watch <run-id> --repo OWNER/REPO --exit-status`. After `PyPI Release` succeeds, verify that PyPI exposes the exact version with both the expected wheel and source distribution. After `Deploy Documentation` succeeds, verify that the published site serves `X.Y.Z` and that `stable` serves that same release. Do not require an HTTP redirect: `mike` aliases can serve directly from the alias path with a `200` response. Fetch the versioned and `stable` entry pages and compare their content; byte-for-byte equality is the clearest proof for a static deployment. If path-dependent markup prevents an exact match, verify a release-specific marker such as the version selector or canonical metadata instead. A successful response from `stable` alone is not proof that the alias moved. A green PyPI job with a failed documentation job is a half-finished release: report both workflow URLs and both outcomes. For a transient workflow failure, rerun only with authorization. For a source or workflow defect, do not move the public tag; prepare a corrective release version. A GitHub Release and release notes are optional, separate publication actions and must not be created unless requested. ## Recovering a tag that never published Separate the mechanics from the policy before proposing a recovery. The mechanics: pushing a tag that already exists and points at the same commit changes no ref, so it starts no workflow run. Creating a tag, moving one to a different commit, or deleting and recreating one does change the ref and does start a run. What that run executes is the workflow file at the tagged commit, so a tag on a commit from before `pypi-release.yml` existed starts no PyPI publication no matter how it is pushed. Run `git ls-tree --name-only <tag> .github/workflows/` before assuming a re-push would help. The policy: never move or reuse a tag whose version is on PyPI. That version is immutable, so a re-run could only fail at upload, and consumers who already resolved the tag would silently get different code. Between those, a tag that never published is a decision for a release owner, not a default action. Releasing the next version from a commit that carries the current workflow is usually simpler and always safer than resurrecting the old tag. Note that a non-publishing tag may still have had effects: `docs.yml` has carried the `v*` trigger for longer than `pypi-release.yml`, so an older tag can have deployed documentation and moved `stable` without ever reaching PyPI. ## Nightly distinction `.github/workflows/pypi-nightly.yml` publishes timestamped `.dev` builds to TestPyPI on its schedule or by manual dispatch. It does not create a stable release and should not be substituted for the tag-driven process above..agents/skills/release/agents/openai.yaml192 B1c8dd09410a2upstream ↗
interface: display_name: "Release" short_description: "Prepare and publish Agent Lightning releases" default_prompt: "Use $release to prepare and publish a new Agent Lightning release."README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/microsoft-agent-lightning-agents-skills-release.md