Skip to content

Type References

Core Types

agentlightning.Triplet

Bases: BaseModel

Single interaction turn captured during reinforcement learning.

agentlightning.RolloutRawResult = Union[None, float, List[ReadableSpan], List[Span]] module-attribute

Rollout result type.

Possible return values of rollout.

agentlightning.RolloutMode = Literal['train', 'val', 'test'] module-attribute

Possible rollout modes.

agentlightning.GenericResponse

Bases: BaseModel

Generic server response used by compatibility endpoints.

Deprecated

This response is no longer used by the new LightningStore APIs.

Attributes:

  • status (str) –

    Status string describing the result of the request.

  • message (Optional[str]) –

    Optional human readable explanation.

  • data (Optional[Dict[str, Any]]) –

    Arbitrary payload serialized as JSON.

agentlightning.ParallelWorkerBase

Base class for workloads executed across multiple worker processes.

The lifecycle is orchestrated by the main process:

Subclasses must implement run() and can override other lifecycle hooks.

__init__()

Initialize the base class. This method can be overridden by subclasses.

init(*args, **kwargs)

Initialize before spawning the workers. This method can be overridden by subclasses.

init_worker(worker_id, *args, **kwargs)

Initialize the worker. This method can be overridden by subclasses.

run(*args, **kwargs)

Run the workload. This method can be overridden by subclasses.

teardown(*args, **kwargs)

Teardown after the workers have exited. This method can be overridden by subclasses.

teardown_worker(worker_id, *args, **kwargs)

Teardown the worker. This method can be overridden by subclasses.

agentlightning.Dataset

Bases: Protocol, Generic[T_co]

The general interface for a dataset.

It's currently implemented as a protocol, having a similar interface to torch.utils.data.Dataset. You don't have to inherit from this class; you can use a simple list if you want to.

agentlightning.AttemptStatus = Literal['preparing', 'running', 'failed', 'succeeded', 'unresponsive', 'timeout'] module-attribute

The status of an attempt.

agentlightning.RolloutStatus = Literal['queuing', 'preparing', 'running', 'failed', 'succeeded', 'cancelled', 'requeuing'] module-attribute

The status of a rollout.

agentlightning.RolloutConfig

Bases: BaseModel

Configuration controlling rollout retries and timeouts.

max_attempts = Field(default=1, ge=1) class-attribute instance-attribute

The maximum number of attempts for the rollout, including the first attempt.

retry_condition = Field(default_factory=(cast(Callable[[], List[AttemptStatus]], list))) class-attribute instance-attribute

The list of statuses that should trigger a retry.

timeout_seconds = None class-attribute instance-attribute

The timeout for the rollout, in seconds. None indicates no timeout.

unresponsive_seconds = None class-attribute instance-attribute

The unresponsive timeout for the rollout, in seconds. None indicates no unresponsive timeout.

agentlightning.Rollout

Bases: BaseModel

config = Field(default_factory=RolloutConfig) class-attribute instance-attribute

Retry and timeout configuration associated with the rollout.

end_time = None class-attribute instance-attribute

Timestamp when the rollout ended.

input instance-attribute

Task input used to generate the rollout.

metadata = None class-attribute instance-attribute

Additional metadata attached to the rollout.

mode = None class-attribute instance-attribute

Execution mode such as "train", "val" or "test". See RolloutMode.

resources_id = None class-attribute instance-attribute

Identifier of the resources required to execute the rollout.

rollout_id instance-attribute

Unique identifier for the rollout.

start_time instance-attribute

Timestamp when the rollout started.

status = 'queuing' class-attribute instance-attribute

Latest status emitted by the controller.

agentlightning.Attempt

Bases: BaseModel

Execution attempt for a rollout, including metadata for retries.

attempt_id instance-attribute

The universal id for current attempt.

end_time = None class-attribute instance-attribute

The time when the attempt has ended.

last_heartbeat_time = None class-attribute instance-attribute

The last time when the worker has reported progress (i.e., a span).

metadata = None class-attribute instance-attribute

A bucket for any other relevant information.

rollout_id instance-attribute

The rollout which this attempt belongs to.

sequence_id instance-attribute

The sequence number of the attempt, starting from 1.

start_time instance-attribute

The time when the attempt has started.

status = 'preparing' class-attribute instance-attribute

The status of the attempt.

worker_id = None class-attribute instance-attribute

The rollout worker which is executing this attempt.

agentlightning.AttemptedRollout

Bases: Rollout

Rollout paired with the currently active attempt.

attempt instance-attribute

The attempt that is currently processing the rollout.

agentlightning.Hook

Bases: ParallelWorkerBase

Base class for defining hooks in the agent runner's lifecycle.

on_rollout_end(*, agent, runner, rollout, spans) async

Hook called after a rollout attempt completes.

Parameters:

  • agent (LitAgent[Any]) –

    The LitAgent instance associated with the runner.

  • runner (Runner[Any]) –

    The Runner managing the rollout.

  • rollout (Rollout) –

    The Rollout object that has been processed.

  • spans (Union[List[ReadableSpan], List[Span]]) –

    The spans that have been added to the store.

Subclasses can override this method for cleanup or additional logging. By default, this is a no-op.

on_rollout_start(*, agent, runner, rollout) async

Hook called immediately before a rollout attempt begins.

Parameters:

Subclasses can override this method to implement custom logic such as logging, metric collection, or resource setup. By default, this is a no-op.

on_trace_end(*, agent, runner, tracer, rollout) async

Hook called immediately after the rollout completes but before the tracer exits the trace context.

Parameters:

Subclasses can override this method to implement custom logic such as logging, metric collection, or resource cleanup. By default, this is a no-op.

on_trace_start(*, agent, runner, tracer, rollout) async

Hook called immediately after the tracer enters the trace context but before the rollout begins.

Parameters:

Subclasses can override this method to implement custom logic such as logging, metric collection, or resource setup. By default, this is a no-op.

Resources

agentlightning.Resource

Bases: BaseModel

Base class for tunable resources distributed to executors.

resource_type instance-attribute

Alias of the resource type.

agentlightning.LLM

Bases: Resource

Resource that identifies an LLM endpoint and its configuration.

api_key = None class-attribute instance-attribute

Optional secret used to authenticate requests.

endpoint instance-attribute

The URL of the LLM API endpoint.

model instance-attribute

The identifier for the model to be used (e.g., 'gpt-4o').

sampling_parameters = Field(default_factory=dict) class-attribute instance-attribute

A dictionary of hyperparameters for model inference, such as temperature, top_p, etc.

get_base_url(*args, **kwargs)

Return the base URL consumed by OpenAI-compatible clients.

Users are encouraged to use get_base_url(rollout_id, attempt_id) to get the LLM endpoint instead of accessing .endpoint directly.

agentlightning.ProxyLLM

Bases: LLM

LLM resource that rewrites endpoints through LLMProxy.

The proxy injects rollout- and attempt-specific routing information into the endpoint so that downstream services can attribute requests correctly.

__getattribute__(name)

Emit a warning when endpoint is accessed directly after initialization.

get_base_url(rollout_id, attempt_id)

Return the routed endpoint for a specific rollout/attempt pair.

Parameters:

  • rollout_id (Optional[str]) –

    Identifier of the rollout making the request.

  • attempt_id (Optional[str]) –

    Identifier of the attempt within that rollout.

Returns:

  • str –

    Fully qualified endpoint including rollout metadata.

Raises:

  • ValueError –

    If exactly one of rollout_id or attempt_id is provided.

model_post_init(__context)

Mark initialization as complete after Pydantic finishes setup.

with_attempted_rollout(rollout)

Bake rollout metadata into a concrete LLM instance.

agentlightning.PromptTemplate

Bases: Resource

Resource describing a reusable prompt template.

engine instance-attribute

The templating engine to use for rendering the prompt.

template instance-attribute

The template string. The format depends on the engine.

format(**kwargs)

Format the prompt using keyword arguments.

Warning

Only the f-string engine is supported for now.

agentlightning.ResourceUnion = Annotated[Union[LLM, ProxyLLM, PromptTemplate], Field(discriminator='resource_type')] module-attribute

agentlightning.NamedResources = Dict[str, ResourceUnion] module-attribute

Mapping from resource names to their configured instances.

Examples:

resources: NamedResources = {
    "main_llm": LLM(
        endpoint="http://localhost:8080",
        model="llama3",
        sampling_parameters={"temperature": 0.7, "max_tokens": 100},
    ),
    "system_prompt": PromptTemplate(
        template="You are a helpful assistant.",
        engine="f-string",
    ),
}

agentlightning.ResourcesUpdate

Bases: BaseModel

Update payload broadcast to clients when resources change.

resources instance-attribute

Mapping of resource names to their definitions.

resources_id instance-attribute

Identifier used to version the resources.

Traces

agentlightning.AttributeValue = Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]] module-attribute

Possible values for OpenTelemetry attributes.

agentlightning.Attributes = Dict[str, AttributeValue] module-attribute

Mapping from attribute names to their values. Same as OpenTelemetry Attributes type.

agentlightning.TraceState = Dict[str, str] module-attribute

Mapping from trace state key to its value. Same as OpenTelemetry TraceState type.

agentlightning.SpanContext

Bases: BaseModel

Pydantic representation of opentelemetry.trace.SpanContext values.

is_remote instance-attribute

Whether the span is remote.

span_id instance-attribute

The span ID of the span.

trace_id instance-attribute

The trace ID of the span.

trace_state instance-attribute

Mapping from trace state key to its value.

from_opentelemetry(src) classmethod

Construct a SpanContext from OpenTelemetry data.

agentlightning.TraceStatus

Bases: BaseModel

Serializable variant of opentelemetry.trace.Status.

description = None class-attribute instance-attribute

The description of the span. Same as OpenTelemetry Status.description type.

status_code instance-attribute

The status code of the span. Same as OpenTelemetry Status.status_code type.

from_opentelemetry(src) classmethod

Create a TraceStatus from OpenTelemetry metadata.

agentlightning.Event

Bases: BaseModel

Serializable representation of OpenTelemetry Event values.

attributes instance-attribute

Mapping from attribute names to their values. Same as OpenTelemetry Attributes type.

name instance-attribute

The name of the event.

timestamp = None class-attribute instance-attribute

The timestamp of the event. Same as OpenTelemetry Event.timestamp type.

from_opentelemetry(src) classmethod

Create an Event from an OpenTelemetry event.

Bases: BaseModel

Serializable representation of OpenTelemetry Link values.

attributes = None class-attribute instance-attribute

Optional attributes.

context instance-attribute

The context of the link.

from_opentelemetry(src) classmethod

Create a Link from an OpenTelemetry link.

agentlightning.Resource

Bases: BaseModel

Base class for tunable resources distributed to executors.

resource_type instance-attribute

Alias of the resource type.

agentlightning.Span

Bases: BaseModel

Agent Lightning's canonical span model used for persistence and analytics.

The model captures the most relevant fields from opentelemetry.sdk.trace.ReadableSpan instances while preserving unmodeled attributes in Pydantic BaseModel's extra storage. This keeps the serialized format stable even as upstream OpenTelemetry types evolve.

attempt_id instance-attribute

The attempt which this span belongs to.

attributes instance-attribute

The attributes of the span. See OpenTelemetry docs.

context instance-attribute

The context of the span. See OpenTelemetry docs.

end_time instance-attribute

The end time of the span. See OpenTelemetry docs.

events instance-attribute

The events of the span. See OpenTelemetry docs.

The links of the span. See OpenTelemetry docs.

name instance-attribute

The name of the span. See OpenTelemetry docs.

parent instance-attribute

The parent context of the span. See OpenTelemetry docs.

parent_id instance-attribute

The parent span ID of the span.

resource instance-attribute

The resource of the span. See OpenTelemetry docs.

rollout_id instance-attribute

The rollout which this span belongs to.

sequence_id instance-attribute

The ID to make spans ordered within a single attempt.

span_id instance-attribute

The span ID of the span. This ID comes from the OpenTelemetry span ID generator.

start_time instance-attribute

The start time of the span. See OpenTelemetry docs.

status instance-attribute

The status of the span. See OpenTelemetry docs.

trace_id instance-attribute

The trace ID of the span. One rollout/attempt can have multiple traces. This ID comes from the OpenTelemetry trace ID generator.

from_attributes(*, attributes, rollout_id=None, attempt_id=None, sequence_id=None, name=None, trace_id=None, span_id=None, parent_id=None, start_time=None, end_time=None, resource=None) classmethod

Build a synthetic span from raw attributes. Different from the from_opentelemetry method, all parameters other than attributes are optional and will be generated if not provided.

Parameters:

  • attributes (Attributes) –

    Span attributes to persist.

  • rollout_id (Optional[str], default: None ) –

    Optional rollout identifier associated with the span.

  • attempt_id (Optional[str], default: None ) –

    Optional attempt identifier associated with the span.

  • sequence_id (Optional[int], default: None ) –

    Optional sequence number to preserve ordering.

  • name (Optional[str], default: None ) –

    Optional human-readable span name.

  • trace_id (Optional[str], default: None ) –

    Custom trace identifier. When omitted, a random identifier is generated.

  • span_id (Optional[str], default: None ) –

    Custom span identifier. When omitted, a random identifier is generated.

  • parent_id (Optional[str], default: None ) –

    Optional parent span identifier.

  • start_time (Optional[float], default: None ) –

    Span start timestamp in seconds.

  • end_time (Optional[float], default: None ) –

    Span end timestamp in seconds.

  • resource (Optional[OtelResource], default: None ) –

    Explicit resource information to attach to the span.

Returns:

  • 'Span' –

    Span populated with the provided attributes.

from_opentelemetry(src, rollout_id, attempt_id, sequence_id) classmethod

Convert an OpenTelemetry span into the Agent Lightning data model.

Parameters:

  • src (ReadableSpan) –

    Span captured by OpenTelemetry.

  • rollout_id (str) –

    Identifier for the rollout that produced the span.

  • attempt_id (str) –

    Identifier of the attempt within the rollout.

  • sequence_id (int) –

    Monotonically increasing identifier assigned to the span.

Returns:

  • 'Span' –

    Parsed Span instance suitable for persistence.

agentlightning.SpanNames

Bases: str, Enum

Enumerated span names recognised by Agent-lightning.

EXCEPTION = 'agentlightning.exception' class-attribute instance-attribute

The name of the exception span.

MESSAGE = 'agentlightning.message' class-attribute instance-attribute

The name of the message span.

OBJECT = 'agentlightning.object' class-attribute instance-attribute

The name of the object span.

REWARD = 'agentlightning.reward' class-attribute instance-attribute

The name of the reward span.

VIRTUAL = 'agentlightning.virtual' class-attribute instance-attribute

The name of the virtual span. It represents derived spans without concrete operations.

agentlightning.SpanAttributeNames

Bases: str, Enum

Canonical attribute names written by Agent Lightning emitters.

MESSAGE = 'message' class-attribute instance-attribute

The name of the message attribute.

OBJECT = 'object' class-attribute instance-attribute

The name of the object attribute.

agentlightning.SpanLike = Union[ReadableSpan, Span] module-attribute

Union type of OpenTelemetry ReadableSpan and Agent-lightning Span.