Agent Lightning

https://microsoft.github.io/agent-lightning/stable/
Admin
Agent Lightning is a trainer designed to optimize AI agents with minimal code changes, supporting...
Tokens:109,448
Snippets:513
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Start and Use LightningStoreServer and LightningStoreClient

Source: https://microsoft.github.io/agent-lightning/stable/deep-dive/store

Demonstrates the setup and basic usage of LightningStoreServer and LightningStoreClient. The server runs a FastAPI app exposing the store API, while the client communicates with this API. This example covers starting the server, creating a client, querying data, and properly closing both resources.

```python
import agentlightning as agl

# Server (owner process)
in_memory_store = agl.InMemoryLightningStore()
server = agl.LightningStoreServer(store=in_memory_store, host="0.0.0.0", port=4747)
await server.start()      # starts uvicorn in a daemon thread and waits for /health
# or keep your own event loop and stop via await server.stop()
# await server.run_forever()

# Client (same or different process)
client = agl.LightningStoreClient("http://localhost:4747")

print(await client.query_rollouts(status=["queuing"]))

await client.close()
await server.stop()
```

--------------------------------

### Install Agent-Lightning Nightly Build from Test PyPI

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Installs the latest experimental features from Agent-Lightning's nightly builds available on Test PyPI. Use with caution as these builds may be unstable.

```bash
pip install --upgrade --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ agentlightning
```

--------------------------------

### Minimal Developer Installation from Source using uv

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Clones the Agent-Lightning repository and installs essential development dependencies using `uv` as the package manager. This provides an isolated development environment.

```bash
git clone https://github.com/microsoft/agent-lightning
cd agent-lightning
uv sync --group dev
```

--------------------------------

### Install Agent-Lightning Stable Release from PyPI

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Installs or upgrades Agent-Lightning to the latest stable version from the Python Package Index (PyPI). This is the recommended method for general use.

```bash
pip install --upgrade agentlightning
```

--------------------------------

### Activate Agent-Lightning Virtual Environment

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Demonstrates two methods for using the virtual environment created by 'uv' in the '.venv/' directory. Option 1 uses 'uv run' to execute scripts, while Option 2 involves activating the environment directly using 'source'.

```bash
# Option 1: Prefix commands with uv run
uv run python your_script.py

# Option 2: Activate the virtual environment
source .venv/bin/activate
python your_script.py
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Installs and runs pre-commit hooks for Agent-Lightning to enforce code style and linting rules. This helps prevent common formatting issues before contributing code. Requires 'uv' to be installed.

```bash
uv run pre-commit install
uv run pre-commit run --all-files --show-diff-on-failure --color=always
```

--------------------------------

### Start Agent-Lightning Runner

Source: https://microsoft.github.io/agent-lightning/stable/how-to/write-first-algorithm

Initiates the runner process, which connects to the LightningStore and awaits tasks. Requires setting the OPENAI_API_KEY environment variable. The output indicates the runner has started and is ready for rollouts.

```bash
export OPENAI_API_KEY=sk-... # Your OpenAI API key
python apo_custom_algorithm.py runner
```

--------------------------------

### Install Agent-Lightning Extras (CPU)

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Installs additional dependencies for CPU-only machines using 'uv sync'. It synchronizes frozen dependencies and includes algorithm-specific extras ('apo', 'verl') and development/PyTorch groups. Assumes 'uv' is installed.

```bash
uv sync --frozen \
    --extra apo \
    --extra verl \
    --group dev \
    --group torch-cpu \
    --group torch-stable \
    --group trl \
    --group agents \
    --no-default-groups
```

--------------------------------

### Run Agent Lightning Components Manually (Shell)

Source: https://microsoft.github.io/agent-lightning/stable/how-to/unsloth-sft

This snippet shows the shell commands to manually start the necessary components for running an Agent Lightning example. It involves starting the store server and then executing the Python scripts for the rollout runners and the algorithm.

```shell
agl store --port 4747
python examples/unsloth/sft_rollout_runners.py
python examples/unsloth/sft_algorithm.py
```

--------------------------------

### Start LightningStore Server

Source: https://microsoft.github.io/agent-lightning/stable/how-to/write-first-algorithm

Starts the LightningStore server, which acts as a central hub for communication between the algorithm and the runner. It listens on port 4747 by default.

```bash
agl store
```

--------------------------------

### Installation

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

Instructions for installing the agent-lightning library with VERL support.

```APIDOC
## Installation

### Description
Instructions for installing the agent-lightning library with VERL support.

### Method
N/A (Command Line)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
pip install agentlightning[verl]
```

### Response
N/A

### Warning
To avoid various compatibility issues, follow the steps in the installation guide to set up VERL and its dependencies. Installing VERL directly with `pip install agentlightning[verl]` can cause issues unless you already have a compatible version of PyTorch installed.
```

--------------------------------

### Build Component Examples - Agent Lightning

Source: https://microsoft.github.io/agent-lightning/stable/reference/trainer

Demonstrates practical usage of the `build_component` function for creating component instances. The examples cover scenarios where the component specification is provided as a direct instance, a string representing an import path, and a dictionary containing the type and constructor arguments. These examples illustrate the flexibility of the function in handling different input formats to instantiate objects of a specified type.

```python
>>> # Direct instance
>>> optimizer = build_component(AdamW(), expected_type=Optimizer, spec_name='optimizer')
>>>
>>> # String import path
>>> optimizer = build_component('torch.optim.AdamW', expected_type=Optimizer, spec_name='optimizer')
>>>
>>> # Dict with type and kwargs
>>> spec = {'type': 'torch.optim.AdamW', 'lr': 0.001}
>>> optimizer = build_component(spec, expected_type=Optimizer, spec_name='optimizer')
>>>
```

--------------------------------

### Manually Install VERL Dependencies for Agent-Lightning

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

A recommended manual setup for VERL integration with Agent-Lightning, ensuring compatibility with specific PyTorch and CUDA versions. Installs PyTorch, flash-attn, vLLM, and VERL.

```bash
pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
pip install flash-attn --no-build-isolation
pip install vllm==0.10.2
pip install verl==0.5.0
```

--------------------------------

### Download and Prepare Spider Dataset

Source: https://microsoft.github.io/agent-lightning/stable/how-to/train-sql-agent

This shell script demonstrates how to download and prepare the Spider dataset required for the SQL agent tutorial. It navigates to the example directory, installs the 'gdown' utility, downloads a dataset bundle, unzips it, and removes the archive. It assumes the user is in the root directory of the repository.

```bash
cd examples/spider
pip install gdown  # included in the 'experiment' optional dependency
gdown --fuzzy https://drive.google.com/file/d/1oi9J1jZP9TyM35L85CL3qeGWl2jqlnL6/view
unzip -q spider-data.zip -d data
rm spider-data.zip

```

--------------------------------

### Install Agent-Lightning Extras (GPU)

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/installation

Installs additional dependencies for GPU-equipped machines (CUDA 12.8 compatible) using 'uv sync'. It synchronizes frozen dependencies and includes algorithm-specific extras ('apo', 'verl') and GPU-specific PyTorch groups. Assumes 'uv' is installed.

```bash
uv sync --frozen \
    --extra apo \
    --extra verl \
    --group dev \
    --group torch-gpu-stable \
    --group trl \
    --group agents \
    --no-default-groups
```

--------------------------------

### Start Local vLLM Server and LLM Proxy - Shell and Python

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/debug

This snippet demonstrates how to start a local vLLM server and then launch an Agent Lightning LLM Proxy to connect to it. The LLM Proxy facilitates debugging local LLM features by routing requests to the local server. It requires vLLM to be installed and a model to be specified.

```shell
vllm serve Qwen/Qwen2.5-0.5B-Instruct --port 8080

```

```python
import agentlightning as agl
import time

llm_proxy = agl.LLMProxy(
    port=8081,
    model_list=[
        {
            "model_name": "Qwen/Qwen2.5-0.5B-Instruct",
            "litellm_params": {
                "model": "hosted_vllm/Qwen/Qwen2.5-0.5B-Instruct",
                "api_base": "http://localhost:8080/v1",
            },
        }
    ],
    store=agl.InMemoryLightningStore(),
)

llm_proxy.start()
time.sleep(1000000)

```

--------------------------------

### Install Agent-Lightning with APO Support

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/apo

This command installs the agent-lightning library, including the necessary dependencies for the APO (Automatic Prompt Optimization) algorithm. Ensure you have pip installed to use this command.

```bash
pip install agentlightning[apo]
```

--------------------------------

### Start the Agent-Lightning Store

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/debug

This command starts the Agent-Lightning store in a separate terminal. It requires specifying a port for the store to listen on. This is the first step in manually managing the store for isolated algorithm debugging.

```bash
agl store --port 4747

```

--------------------------------

### Start Rollout API

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Registers a new rollout and immediately creates its first attempt. This is used when the caller wants to begin execution without visiting the public queue. It generates unique IDs, records start times, copies configuration, and resolves resource IDs.

```APIDOC
## POST /websites/microsoft_github_io_agent-lightning_stable/start_rollout

### Description
Register a rollout and immediately create its first attempt. Note: Use `enqueue_rollout()` when the caller only wants to submit work for later scheduling. The rollout must be persisted with `status="preparing"` and an initial attempt with `sequence_id == 1` so the caller can begin execution without visiting the public queue. Implementations are expected to: 1. Generate a unique `rollout_id` and `attempt_id`. 2. Record `start_time` for both rollout and attempt based on the current clock. 3. Copy `config` and `metadata` so later mutations do not leak shared references. 4. Resolve `resources_id` to the latest resource snapshot when `None` is supplied.

### Method
POST

### Endpoint
/websites/microsoft_github_io_agent-lightning_stable/start_rollout

### Parameters
#### Request Body
- **input** (TaskInput) - Required - Arbitrary task payload supplied by an algorithm.
- **mode** (Literal['train', 'val', 'test'] | None) - Optional - Optional semantic mode for downstream analytics (`"train"`, `"val"`, `"test"`).
- **resources_id** (str | None) - Optional - Concrete resource snapshot to execute against; defaults to the latest stored snapshot.
- **config** (RolloutConfig | None) - Optional - Rollout retry/timeout policy. Should default to a fresh `RolloutConfig`.
- **metadata** (Dict[str, Any] | None) - Optional - Free-form metadata persisted verbatim with the rollout.

### Response
#### Success Response (200)
- **AttemptedRollout** - The fully-populated `AttemptedRollout` including the just-created attempt.

#### Response Example
```json
{
  "rollout_id": "string",
  "attempt_id": "string",
  "sequence_id": 0,
  "start_time": 0.0,
  "end_time": null,
  "status": "preparing",
  "metadata": {}
}
```
```

--------------------------------

### LightningStoreServer Management

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Endpoints for managing the LightningStoreServer, including starting, stopping, and running the server.

```APIDOC
## POST /start

### Description
Starts the FastAPI server in the background. This method must be called in the same process where the server was created.

### Method
POST

### Endpoint
/start

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the server has started.

#### Response Example
```json
{
  "message": "FastAPI server started in the background."
}
```
```

```APIDOC
## POST /stop

### Description
Gracefully stops the running FastAPI server. This method must be called in the same process where the server was created.

### Method
POST

### Endpoint
/stop

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the server has stopped.

#### Response Example
```json
{
  "message": "FastAPI server stopped gracefully."
}
```
```

```APIDOC
## POST /run_forever

### Description
Runs the FastAPI server indefinitely. This method must be called in the same process where the server was created.

### Method
POST

### Endpoint
/run_forever

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the server is running indefinitely.

#### Response Example
```json
{
  "message": "FastAPI server running indefinitely."
}
```
```

--------------------------------

### Build Component Example using Python

Source: https://microsoft.github.io/agent-lightning/stable/reference/trainer

Demonstrates how to use the `build_component` function to instantiate an optimizer. It shows two methods: direct class instantiation and using a factory function (lambda).

```python
optimizer = build_component(AdamW, expected_type=Optimizer, spec_name='optimizer')

optimizer = build_component(lambda: AdamW(lr=0.001), expected_type=Optimizer,
spec_name='optimizer')
```

--------------------------------

### Configure Trainer Adapter Initialization Parameters

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/parallelize

Explains how to provide initialization parameters for default Trainer components, like the adapter, using a dictionary.

```python
trainer = agl.Trainer(
    algorithm=algorithm,
    adapter={"agent_match": "plan_agent", "repair_hierarchy": False},
)
```

--------------------------------

### Launch SQL Agent Training (Qwen)

Source: https://microsoft.github.io/agent-lightning/stable/how-to/train-sql-agent

This shell command launches the training of the SQL agent using the Qwen model. It is executed from the 'examples/spider' directory and uses a helper script 'train_sql_agent.py'. This is the default configuration for Qwen-2.5-Coder-1.5B. Ensure you are in the 'examples/spider' directory before running.

```bash
python train_sql_agent.py qwen   # Default Qwen-2.5-Coder-1.5B run

```

--------------------------------

### Install VERL and Dependencies

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

Provides the pip command to install the agentlightning package with VERL support. It includes a warning about potential compatibility issues if PyTorch is not already installed.

```bash
pip install agentlightning[verl]
```

--------------------------------

### Set Up Data and Server Resources (Synchronous Wrapper)

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

Synchronously sets up data and server resources for the Agent Lightning server. It takes data, server addresses, and a training flag as input.

```python
def set_up_data_and_server(data, server_addresses, is_train=True):
    """Synchronous wrapper for setting up data and server resources."""
    pass
```

--------------------------------

### Start Agent Lightning Server and Proxy

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

Starts the main AgentLightningServer and the associated proxy server. This function is essential for launching the core components of the system.

```python
def start():
    """Starts the main AgentLightningServer and the proxy server."""
    pass
```

--------------------------------

### Algorithm Class

Source: https://microsoft.github.io/agent-lightning/stable/reference/algorithm

Documentation for the base Algorithm class and its methods, including retrieving clients, adapters, stores, and running the algorithm.

```APIDOC
## `agentlightning.Algorithm`

Algorithm is the strategy, or tuner to train the agent.

### Methods

#### `get_adapter()`

*   **Description**: Retrieve the adapter for this algorithm to communicate with the runners.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)

#### `get_client()`

*   **Description**: Get the client to communicate with the algorithm. If the algorithm does not require a server-client communication, it can also create a mock client that never communicates with itself. Deprecated and will be removed in a future version.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Returns**: `AgentLightningClient` – The AgentLightningClient instance associated with this algorithm.

#### `get_initial_resources()`

*   **Description**: Get the initial resources for this algorithm.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)

#### `get_llm_proxy()`

*   **Description**: Retrieve the configured LLM proxy instance, if one has been set.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Returns**: `Optional[LLMProxy]` – The active LLMProxy instance or None when not configured.

#### `get_store()`

*   **Description**: Retrieve the store for this algorithm to communicate with the runners.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)

#### `get_trainer()`

*   **Description**: Get the trainer for this algorithm.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Returns**: `Trainer` – The Trainer instance associated with this agent.

#### `is_async()`

*   **Description**: Return True if the algorithm is asynchronous.
*   **Method**: GET (Conceptual)
*   **Endpoint**: N/A (Instance method)

#### `run(train_dataset=None, val_dataset=None)`

*   **Description**: Subclasses should implement this method to implement the algorithm.
*   **Method**: POST (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `train_dataset` (Optional[Dataset[Any]]) - Optional - The dataset to train on. Not all algorithms require a training dataset.
    *   `val_dataset` (Optional[Dataset[Any]]) - Optional - The dataset to validate on. Not all algorithms require a validation dataset.
*   **Returns**: `Union[None, Awaitable[None]]` – Algorithm should refrain from returning anything. It should just run the algorithm.

#### `set_adapter(adapter)`

*   **Description**: Set the adapter for this algorithm to collect and convert traces.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `adapter` (Adapter) - Required - The adapter to set.

#### `set_initial_resources(resources)`

*   **Description**: Set the initial resources for this algorithm.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `resources` (Any) - Required - The initial resources to set.

#### `set_llm_proxy(llm_proxy)`

*   **Description**: Set the LLM proxy for this algorithm.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `llm_proxy` (LLMProxy) - Required - The LLM proxy to set.

#### `set_store(store)`

*   **Description**: Set the store for this algorithm.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `store` (Any) - Required - The store to set.

#### `set_trainer(trainer)`

*   **Description**: Set the trainer for this algorithm.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: N/A (Instance method)
*   **Parameters**:
    *   `trainer` (Trainer) - Required - The trainer to set.

```

--------------------------------

### Tutorials Using VERL

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

A list of tutorials available for learning how to use the VERL algorithm.

```APIDOC
## Tutorials Using VERL

### Description
A list of tutorials available for learning how to use the VERL algorithm.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Tutorials
- Train SQL Agent with RL - A practical example of training a SQL agent using VERL.
```

--------------------------------

### Configure Trainer with Client-Server Strategy via Dictionary

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/parallelize

Shows how to configure the Trainer to use the ClientServerExecutionStrategy by passing a dictionary, allowing customization of ports and other settings.

```python
trainer = agl.Trainer(
    algorithm=algorithm,
    n_runners=8,
    strategy={"type": "cs", "server_port": 9999},
)
```

--------------------------------

### Start and Manage Tracing Contexts

Source: https://microsoft.github.io/agent-lightning/stable/reference/runner

The `trace_context` method starts a new tracing context and should be used as an asynchronous context manager. It allows for optional naming of the context and associating spans with a store, rollout ID, or attempt ID. It yields a `LightningSpanProcessor` to collect spans.

```python
from agent_lightning.tracing import Tracer, LightningStore

# Assuming 'tracer' is an instance of a Tracer subclass
# tracer: Tracer

# Example using trace_context with optional parameters
async with tracer.trace_context(name="custom_context_name", store=LightningStore(), rollout_id="rollout-123", attempt_id="attempt-abc") as span_processor:
    print("Inside the traced context.")
    # Perform operations that should be traced
    # The span_processor can be used to interact with the collected spans if needed

print("Exited the traced context.")
```

--------------------------------

### Serve Model with vLLM and Start Client

Source: https://microsoft.github.io/agent-lightning/stable/how-to/unsloth-sft

This Python code demonstrates how to launch a vLLM inference server using subprocess and then connect to it using httpx and OpenAI's client. It includes waiting for the server to be ready before establishing a connection.

```python
from openai import OpenAI
import subprocess
import httpx
import time

vllm_process = subprocess.Popen([
    "vllm", "serve", model_path, "--port", str(port),
    "--enable-auto-tool-choice", "--tool-call-parser", "hermes"
])

# Wait for the server to be ready
url = f"http://localhost:{port}/health"
start = time.time()
client = httpx.Client()

while True:
    if client.get(url).status_code == 200:
        break

server_address = f"http://localhost:{port}/v1"

# Try using the vLLM server
openai = OpenAI(base_url=server_address)
...
```

--------------------------------

### VERL Entrypoint

Source: https://microsoft.github.io/agent-lightning/stable/algorithm-zoo/verl

This section describes how to create an instance of the VERL algorithm using the provided shortcut.

```APIDOC
## VERL Entrypoint

### Description
This section describes how to create an instance of the VERL algorithm using the provided shortcut.

### Method
N/A (Usage Example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import agentlightning as agl
agl.VERL(...)
```

### Response
N/A
```

--------------------------------

### Get Rollout By ID

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Fetches a rollout by its identifier without mutating its state.

```APIDOC
## GET /rollouts/{rollout_id}

### Description
Fetch a rollout by identifier without mutating its state.

### Method
GET

### Endpoint
/rollouts/{rollout_id}

### Parameters
#### Path Parameters
- **`rollout_id`** (str) - Required - Identifier to retrieve.

### Response
#### Success Response (200)
- **`rollout`** (Optional[Rollout]) - The rollout when found, otherwise `None`.

#### Response Example
```json
{
  "rollout": {
    "rollout_id": "rollout-xyz",
    "status": "queuing",
    "start_time": "2023-10-27T10:00:00Z",
    "input": { ... },
    "mode": "train",
    "resources_id": "snapshot-123",
    "config": { ... },
    "metadata": { "user_id": "abc" }
  }
}
```

### Raises
- `NotImplementedError` - Subclasses must implement retrieval.
```

--------------------------------

### Run Agent-Lightning Algorithm (Pre-written Script)

Source: https://microsoft.github.io/agent-lightning/stable/how-to/write-first-algorithm

A simplified way to run the algorithm using a pre-written script. This command executes the algorithm with default configurations or parameters defined within the script.

```bash
python apo_custom_algorithm.py algo
```

--------------------------------

### Get Resources By ID

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Retrieves a specific named resource snapshot by its identifier.

```APIDOC
## GET /resources/{resources_id}

### Description
Return a specific named resource snapshot by identifier.

### Method
GET

### Endpoint
/resources/{resources_id}

### Parameters
#### Path Parameters
- **`resources_id`** (str) - Required - Identifier of the snapshot.

### Response
#### Success Response (200)
- **`resources_update`** (Optional[ResourcesUpdate]) - The stored `ResourcesUpdate`, or `None` when missing.

#### Response Example
```json
{
  "resources_update": {
    "resources_id": "snapshot-123",
    "timestamp": "2023-10-26T15:30:00Z",
    "resource_list": [
      { "type": "model", "uri": "s3://bucket/model_v2.pt" },
      { "type": "data", "uri": "s3://bucket/data_v2.csv" }
    ]
  }
}
```

### Raises
- `NotImplementedError` - Subclasses must implement retrieval.
```

--------------------------------

### Initialize Trainer with Custom Adapter

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/parallelize

Shows how to swap in a different adapter for the Trainer, such as the TraceToMessages adapter.

```python
trainer = agl.Trainer(algorithm=algorithm, adapter="agentlightning.adapter.TraceToMessages")
```

--------------------------------

### Execute Agent Rollout with Resources in Runner

Source: https://microsoft.github.io/agent-lightning/stable/tutorials/debug

Shows how to execute a single agent rollout using `runner.step()` within the `run_context`. This includes passing necessary resources, such as a `PromptTemplate`, which the agent might require for its execution.

```python
with runner.run_context(agent=apo_rollout, store=store):
    resource = agl.PromptTemplate(template="You are a helpful assistant. {any_question}", engine="f-string")
    rollout = await runner.step(
        "Explain why the sky appears blue using principles of light scattering in 100 words.",
        resources={"main_prompt": resource},
    )
```

--------------------------------

### Get Latest Attempt

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Fetches the attempt with the highest `sequence_id` for a given `rollout_id`.

```APIDOC
## GET /rollouts/{rollout_id}/attempts/latest

### Description
Fetch the attempt with the highest `sequence_id` for `rollout_id`.

### Method
GET

### Endpoint
/rollouts/{rollout_id}/attempts/latest

### Parameters
#### Path Parameters
- **`rollout_id`** (str) - Required - Identifier to inspect.

### Response
#### Success Response (200)
- **`attempt`** (Optional[Attempt]) - The most recent attempt or `None` when no attempts exist yet.

#### Response Example
```json
{
  "attempt": {
    "attempt_id": "attempt-456",
    "rollout_id": "rollout-xyz",
    "sequence_id": 1,
    "start_time": "2023-10-27T10:05:00Z"
  }
}
```

### Raises
- `NotImplementedError` - Subclasses must implement retrieval.
- `ValueError` - Implementations must raise when the rollout does not exist.
```

--------------------------------

### Get Latest Resources

Source: https://microsoft.github.io/agent-lightning/stable/reference/store

Fetches the latest resource snapshot marked as the global default.

```APIDOC
## GET /resources/latest

### Description
Fetch the latest resource snapshot marked as the global default.

### Method
GET

### Endpoint
/resources/latest

### Response
#### Success Response (200)
- **`resources_update`** (Optional[ResourcesUpdate]) - The current latest `ResourcesUpdate`, or `None` when no resources have been registered yet.

#### Response Example
```json
{
  "resources_update": {
    "resources_id": "default-resources-789",
    "timestamp": "2023-10-27T09:00:00Z",
    "resource_list": [
      { "type": "model", "uri": "s3://bucket/model.pt" },
      { "type": "data", "uri": "s3://bucket/data.csv" }
    ]
  }
}
```

### Raises
- `NotImplementedError` - Subclasses must implement retrieval.
```

--------------------------------

### Configure and Run Trainer for Agent Training

Source: https://microsoft.github.io/agent-lightning/stable/how-to/train-first-agent

Configures and starts the Agent-Lightning training process. The Trainer manages the training loop, connecting the algorithm, prompt templates, and datasets. It utilizes parallel runners for efficiency and an adapter to format span data for the algorithm. Requires `openai >= 1.100.0` for `TraceToMessages`.

```python
# 1. Configure the Trainer with the algorithm and initial prompt
trainer = agl.Trainer(
    algorithm=algo,
    n_runners=8, # Run 8 agents in parallel to try out the prompts
    initial_resources={
        # The initial prompt template to be tuned
        "prompt_template": prompt_template_baseline()
    },
    # This is used to convert the span data into a message format consumable by APO algorithm
    adapter=agl.TraceToMessages(),
)

# 2. Load datasets: They can be list of task objects consumable by `room_selector`.
dataset_train, dataset_val = ...

# 3. Start the training process!
trainer.fit(
    agent=room_selector,
    train_dataset=dataset_train,
    val_dataset=dataset_val
)

```

--------------------------------

### Store Management API

Source: https://microsoft.github.io/agent-lightning/stable/reference/algorithm

APIs for getting and setting the data store used by the proxy.

```APIDOC
## GET /store

### Description
Gets the store used by the proxy.

### Method
GET

### Endpoint
`/store`

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **`Optional[LightningStore]`** - The store used by the proxy.

#### Response Example
```json
{
  "store_id": "unique_store_identifier"
}
```

## PUT /store

### Description
Sets the store for the proxy.

### Method
PUT

### Endpoint
`/store`

### Parameters
None

#### Request Body
- **`store`** (LightningStore) - Required - The store to use for the proxy.

### Request Example
```json
{
  "store_id": "new_store_identifier"
}
```

### Response
#### Success Response (200)
- **`message`** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "Store updated successfully"
}
```
```

--------------------------------

### Task Polling

Source: https://microsoft.github.io/agent-lightning/stable/reference/internal

Methods for polling the server to get the next available task for execution, both synchronously and asynchronously.

```APIDOC
## GET /tasks/next

### Description
Polls the server synchronously until a task becomes available.

### Method
GET

### Endpoint
/tasks/next

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Task** (Optional[Task]) - The next Task available for execution, or None if polling fails.

#### Response Example
```json
{
  "id": "task-123",
  "type": "processing",
  "payload": {
    "data": "example_data"
  }
}
```

## GET /tasks/next/async

### Description
Polls the server asynchronously until a task becomes available.

### Method
GET

### Endpoint
/tasks/next/async

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Task** (Optional[Task]) - The next Task exposed by the server, or None if polling fails.

#### Response Example
```json
{
  "id": "task-456",
  "type": "analysis",
  "payload": {
    "query": "example_query"
  }
}
```
```
Tokens:
Raw