{"id":7904,"library":"agentlightning","title":"Agent Lightning","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/agent-lightning","tags":["AI agents","reinforcement learning","prompt optimization","LLM","agent framework"],"install":[{"cmd":"pip install agentlightning","lang":"bash","label":"Stable Release"},{"cmd":"pip install --upgrade --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --pre agentlightning","lang":"bash","label":"Nightly Build (Latest Features)"}],"dependencies":[{"reason":"Commonly used LLM provider for agent interactions.","package":"openai","optional":false},{"reason":"Used under the hood for routing LLM requests and collecting traces.","package":"litellm","optional":false},{"reason":"Recommended for fast and safe dependency management (version 0.2+).","package":"uv","optional":true},{"reason":"Required for Reinforcement Learning (RL) based training.","package":"verl","optional":true},{"reason":"For trace collection and auto-instrumentation.","package":"agentops","optional":true}],"imports":[{"symbol":"rollout","correct":"from agentlightning import rollout"},{"symbol":"LitAgent","correct":"from agentlightning import LitAgent"},{"symbol":"Trainer","correct":"from agentlightning import Trainer"}],"quickstart":{"code":"import os\nfrom typing import TypedDict\nfrom agentlightning import rollout, Trainer, PromptTemplate, NamedResources, Rollout\n\n# Ensure OPENAI_API_KEY is set in your environment or replace 'YOUR_OPENAI_KEY'\nos.environ.setdefault(\"OPENAI_API_KEY\", os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_KEY'))\n\nclass RoomSelectionTask(TypedDict):\n    attendee_count: int\n    time: str\n    has_whiteboard: bool\n    expected_choice: str\n\ndef room_selection_grader(final_choice: str, expected_choice: str) -> float:\n    \"\"\"Grades the agent's room selection.\"\"\"\n    return 1.0 if final_choice == expected_choice else 0.0\n\n@rollout\ndef room_selector_agent(task: RoomSelectionTask, prompt_template: PromptTemplate) -> float:\n    # Simulate agent logic using the prompt_template and task\n    # In a real scenario, this would involve LLM calls and tool usage.\n    prompt_text = prompt_template.format(task=task)\n    # Placeholder for LLM interaction and tool calls\n    # For demonstration, we'll simulate a choice.\n    if task['attendee_count'] > 5 and task['has_whiteboard']:\n        final_choice = 'Large Conference Room with Whiteboard'\n    else:\n        final_choice = 'Small Meeting Room'\n\n    reward = room_selection_grader(final_choice, task['expected_choice'])\n    return reward\n\n# Define a simple prompt template (this would be optimized by Agent Lightning)\ninitial_prompt = PromptTemplate(\n    template=\"\"\"You are a room selection agent. Given the following task: \n    Attendees: {task[attendee_count]}, Time: {task[time]}, Whiteboard needed: {task[has_whiteboard]}.\n    Select the best room.\"\"\"\n)\n\n# Example usage with a dummy trainer (full training requires more setup)\n# For a complete training loop, you would typically define a dataset and an algorithm.\n# This snippet focuses on demonstrating the @rollout decorator.\n\n# Create a dummy task for a single rollout demonstration\ndummy_task = RoomSelectionTask(\n    attendee_count=7, \n    time=\"10 AM\", \n    has_whiteboard=True, \n    expected_choice=\"Large Conference Room with Whiteboard\"\n)\n\n# Manually run the agent with the initial prompt for demonstration\n# In a real setup, Trainer would orchestrate this.\nprint(f\"Running agent with task: {dummy_task}\")\nresources = NamedResources(prompt_template=initial_prompt)\nreward = room_selector_agent(dummy_task, resources)\nprint(f\"Agent received reward: {reward}\")\n\n# To initialize a trainer (requires more setup including an algorithm and dataset):\n# trainer = Trainer(n_runners=1, algorithm=your_algorithm_instance)\n# trainer.fit(agent=room_selector_agent, tasks=[dummy_task], resources={'prompt_template': initial_prompt})\n","lang":"python","description":"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."},"warnings":[{"fix":"Use a Linux environment or WSL2 for development and deployment.","message":"Agent Lightning is officially supported on Linux distributions (Ubuntu 22.04+ recommended). macOS and Windows (outside of WSL2) are currently not supported.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Nightly builds of Agent Lightning contain experimental features and may include unstable or untested changes, potentially leading to breaking changes.","severity":"breaking","affected_versions":"nightly builds"},{"fix":"Override the cache locations inline by setting `UV_CACHE=\"$(pwd)/.cache_uv\" XDG_CACHE_HOME=\"$(pwd)/.cache_xdg\"` before running `uv` commands.","message":"When using `uv` for dependency management, you might encounter `Permission denied` errors under `~/.cache`. This is a known issue with `uv`'s caching mechanism.","severity":"gotcha","affected_versions":">=0.2.0 (with uv)"},{"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.","message":"Changes in dependent libraries like `verl` or `weave` can cause incompatibilities or errors due to interface changes or breaking API updates.","severity":"breaking","affected_versions":"All versions, depending on specific dependency updates"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"Default `uv` cache locations might cause permission issues in certain environments, often related to user permissions or containerized setups.","error":"uv run errors with Permission denied under ~/.cache"},{"fix":"Install the necessary optional dependencies: `pip install agentlightning[verl]` or `pip install verl` separately if you encounter this.","cause":"The `verl` dependency is optional and needs to be explicitly installed if you plan to use VERL-based RL training.","error":"ModuleNotFoundError: No module named 'agentlightning.algorithm.verl'"},{"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()`.","cause":"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.","error":"RuntimeError: There is already an event loop running"}]}