Skip to main content

Agent Lightning v1.0

3,500-Line Lightweight Agentic RL Framework for Training Agents with Real Harnesses!

Documentation  ·  Technical Report  ·  WeChat Group (微信群)  ·  MIT License

Agent Lightning was completely refactored in v1.0. For legacy releases earlier than v1.0, see this branch.

⚡ News

⚡ 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 architecture

Agent Lightning v1.0 keeps the training architecture simple with three lightweight components:

  • Trainer: Runs verl and 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.

Agent Lightning v1.0 benchmark comparison

⚡ 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

⚡ Community Projects

⚡ Citation

If you use Agent Lightning v1.0 in your research or projects, please cite the technical report:

@misc{he2026agentlightningv10harnessed,
  title={Agent Lightning v1.0: Towards Harnessed Agentic RL},
  author={Zhiyuan He and Siwei Zhang and Zhiwen Zhou and Yuqing Yang and Yu Kang and Yuge Zhang and Luna K. Qiu and Tin Yan Tsui and Jiahang Xu and Chong Luo},
  year={2026},
  eprint={2608.17528},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2608.17528},
}

For the original Agent Lightning paper, please use:

@misc{luo2025agentlightningtrainai,
      title={Agent Lightning: Train ANY AI Agents with Reinforcement Learning},
      author={Xufang Luo and Yuge Zhang and Zhiyuan He and Zilong Wang and Siyun Zhao and Dongsheng Li and Luna K. Qiu and Yuqing Yang},
      year={2025},
      eprint={2508.03680},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2508.03680},
}

⚡ Contributing

This project welcomes contributions and suggestions. Start by reading the Contributing Guide for recommended contribution points, environment setup, branching conventions, and pull request expectations. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

⚡ Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

⚡ Responsible AI

This project has been evaluated and certified to comply with the Microsoft Responsible AI Standard. The team will continue to monitor and maintain the repository, addressing any severe issues, including potential harms, if they arise.

⚡ License

Agent Lightning v1.0 is released under the MIT License.

Metadata

Release files for agentlightning 1.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentlightning 1.0.3
File Size Uploaded Provenance Actions
agentlightning-1.0.3.tar.gz 1.5 MB With provenance Details for agentlightning-1.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentlightning 1.0.3
File Interpreter ABI Platform Actions
agentlightning-1.0.3-py3-none-any.whl Python 3 none any Details for agentlightning-1.0.3-py3-none-any.whl

Total release size: 1.6 MB

Release files / agentlightning-1.0.3.tar.gz

Download URL agentlightning-1.0.3.tar.gz
Size 1.5 MB
Tags Source
SHA-256 checksum
How to use checksums
96a5fd5f1ad8cf022e8928764789a7f8c65616cccea4c4652ee80a92d4721e69
BLAKE2b-256 checksum
How to use checksums
2c2f11a684ad584acc9bad6e50bf12629b93fda86d4f341a4abc80f54864166a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / agentlightning-1.0.3-py3-none-any.whl

Download URL agentlightning-1.0.3-py3-none-any.whl
Size 80.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
26af7553bf1a5ca1a0b555cc62fca00031e03fdf1fc3053488e4ef588f05c39a
BLAKE2b-256 checksum
How to use checksums
de6ccb720d25b93bfb1ba6d9bea19fc446cf80ab1bf84b8c86336464f80cb8ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for agentlightning 1.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentlightning-1.0.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page