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
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.fixUse 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.fixFor 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.fixOverride 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.fixCheck 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.
fixPrepend `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.
fixInstall 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.
fixUse `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.