Registry / llm-agents / agentlightning

agentlightning

JSON →
library0.3.0pypypi✓ verified 85d ago

Agent Lightning is an open-source Microsoft framework designed to train and optimize AI agents using techniques like Reinforcement Learning, Automatic Prompt Optimization, and Supervised Fine-tuning. It works with various agent frameworks (e.g., LangChain, AutoGen) with minimal code changes. The current stable version is 0.3.0, and it maintains an active development cycle with regular updates and nightly builds.

pip install agentlightning
INSTALL
IMPORT
SIG · AGENTLIGHTNING
A
agentlightning
llm-agentspythonv0.3.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
4/8 runs
py 3.11
✕ build_error
4/8 runs
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
✕ build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rollout
from agentlightning import rollout
LitAgent
from agentlightning import LitAgent
Trainer
from agentlightning import Trainer

This quickstart demonstrates how to define an agent using the `@agentlightning.rollout` decorator. It simulates an agent's logic for selecting a meeting room based on task requirements and calculates a reward. For actual training, you would integrate a `Trainer` with an algorithm and a dataset.

import os from typing import TypedDict from agentlightning import rollout, Trainer, PromptTemplate, NamedResources, Rollout # Ensure OPENAI_API_KEY is set in your environment or replace 'YOUR_OPENAI_KEY' os.environ.setdefault("OPENAI_API_KEY", os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_KEY')) class RoomSelectionTask(TypedDict): attendee_count: int time: str has_whiteboard: bool expected_choice: str def room_selection_grader(final_choice: str, expected_choice: str) -> float: """Grades the agent's room selection.""" return 1.0 if final_choice == expected_choice else 0.0 @rollout def room_selector_agent(task: RoomSelectionTask, prompt_template: PromptTemplate) -> float: # Simulate agent logic using the prompt_template and task # In a real scenario, this would involve LLM calls and tool usage. prompt_text = prompt_template.format(task=task) # Placeholder for LLM interaction and tool calls # For demonstration, we'll simulate a choice. if task['attendee_count'] > 5 and task['has_whiteboard']: final_choice = 'Large Conference Room with Whiteboard' else: final_choice = 'Small Meeting Room' reward = room_selection_grader(final_choice, task['expected_choice']) return reward # Define a simple prompt template (this would be optimized by Agent Lightning) initial_prompt = PromptTemplate( template="""You are a room selection agent. Given the following task: Attendees: {task[attendee_count]}, Time: {task[time]}, Whiteboard needed: {task[has_whiteboard]}. Select the best room.""" ) # Example usage with a dummy trainer (full training requires more setup) # For a complete training loop, you would typically define a dataset and an algorithm. # This snippet focuses on demonstrating the @rollout decorator. # Create a dummy task for a single rollout demonstration dummy_task = RoomSelectionTask( attendee_count=7, time="10 AM", has_whiteboard=True, expected_choice="Large Conference Room with Whiteboard" ) # Manually run the agent with the initial prompt for demonstration # In a real setup, Trainer would orchestrate this. print(f"Running agent with task: {dummy_task}") resources = NamedResources(prompt_template=initial_prompt) reward = room_selector_agent(dummy_task, resources) print(f"Agent received reward: {reward}") # To initialize a trainer (requires more setup including an algorithm and dataset): # trainer = Trainer(n_runners=1, algorithm=your_algorithm_instance) # trainer.fit(agent=room_selector_agent, tasks=[dummy_task], resources={'prompt_template': initial_prompt})
agentlightning --version
Debug
Known issues
gotchaAgent Lightning is officially supported on Linux distributions (Ubuntu 22.04+ recommended). macOS and Windows (outside of WSL2) are currently not supported.
fix
Use a Linux environment or WSL2 for development and deployment.
affects: >=0.1.0
breakingNightly builds of Agent Lightning contain experimental features and may include unstable or untested changes, potentially leading to breaking changes.
fix
For production or stable environments, use the `pip install agentlightning` command to install the latest stable release. Use nightly builds with caution and for testing new features.
affects: nightly builds
gotchaWhen using `uv` for dependency management, you might encounter `Permission denied` errors under `~/.cache`. This is a known issue with `uv`'s caching mechanism.
fix
Override the cache locations inline by setting `UV_CACHE="$(pwd)/.cache_uv" XDG_CACHE_HOME="$(pwd)/.cache_xdg"` before running `uv` commands.
affects: >=0.2.0 (with uv)
breakingChanges in dependent libraries like `verl` or `weave` can cause incompatibilities or errors due to interface changes or breaking API updates.
fix
Check the project's GitHub issues and pull requests for pinned dependency versions (e.g., `verl<0.7.0`) and adapt your environment accordingly. Regularly update `agentlightning` and its dependencies while monitoring for official compatibility notes.
affects: All versions, depending on specific dependency updates
Errors
Common errors & fixes
uv run errors with Permission denied under ~/.cache
Default `uv` cache locations might cause permission issues in certain environments, often related to user permissions or containerized setups.
fix
Prepend `UV_CACHE="$(pwd)/.cache_uv" XDG_CACHE_HOME="$(pwd)/.cache_xdg"` to your `uv run` command, for example: `UV_CACHE="$(pwd)/.cache_uv" XDG_CACHE_HOME="$(pwd)/.cache_xdg" uv run --no-sync pytest`.
ModuleNotFoundError: No module named 'agentlightning.algorithm.verl'
The `verl` dependency is optional and needs to be explicitly installed if you plan to use VERL-based RL training.
fix
Install the necessary optional dependencies: `pip install agentlightning[verl]` or `pip install verl` separately if you encounter this.
RuntimeError: There is already an event loop running
When integrating `agentlightning` with other asynchronous frameworks or in certain interactive environments (like Jupyter notebooks), a new event loop might be created implicitly, conflicting with `agentlightning`'s async operations.
fix
Use `nest_asyncio.apply()` at the beginning of your script or notebook to allow nested asyncio event loops. Example: `import nest_asyncio; nest_asyncio.apply()`.
Upgrade
Version history
0.3.0latest on PyPI · released Dec 24, 2025
Audit
Dependencies
openairequiredCommonly used LLM provider for agent interactions.
litellmrequiredUsed under the hood for routing LLM requests and collecting traces.
uvoptionalRecommended for fast and safe dependency management (version 0.2+).
verloptionalRequired for Reinforcement Learning (RL) based training.
agentopsoptionalFor trace collection and auto-instrumentation.
Agent activity
62 hits · last 30 days
node
52
Perplexity
1
Resources