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.Worker

Bases: BaseModel

Worker information. This is actually the same as Runner info.

current_attempt_id = None class-attribute instance-attribute

The ID of the current attempt that the worker is processing.

current_rollout_id = None class-attribute instance-attribute

The ID of the current rollout that the worker is processing.

heartbeat_stats = None class-attribute instance-attribute

Statistics about the worker's heartbeat.

last_busy_time = None class-attribute instance-attribute

The last time when the worker has started an attempt and became busy.

last_dequeue_time = None class-attribute instance-attribute

The last time when the worker has tried to dequeue a rollout.

last_heartbeat_time = None class-attribute instance-attribute

The last time when the worker has reported the stats.

last_idle_time = None class-attribute instance-attribute

The last time when the worker has triggered the end of an attempt and became idle.

status = 'unknown' class-attribute instance-attribute

The status of the worker.

worker_id instance-attribute

The ID of the worker.

agentlightning.WorkerStatus = Literal['idle', 'busy', 'unknown'] module-attribute

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.

agentlightning.PaginatedResult

Bases: BaseModel, Sequence[T_item]

Result of a paginated query.

Behaves like a sequence, but also carries pagination metadata (limit, offset, total).

items instance-attribute

Items in the result.

limit instance-attribute

Limit of the result.

offset instance-attribute

Offset of the result.

total instance-attribute

Total number of items in the collection.

agentlightning.FilterOptions = Mapping[Union[str, Literal['_aggregate', '_must']], Union[FilterField, Literal['and', 'or'], Mapping[str, FilterField]]] module-attribute

A mapping of field name -> operator dict.

Each operator dict can contain:

  • "exact": value for exact equality.
  • "within": iterable of allowed values.
  • "contains": substring to search for in string fields.

The filter can also have a special field called "_aggregate" that can be used to specify the logic to combine the results of the filters:

  • "and": all conditions must match. This is the default value if not specified.
  • "or": at least one condition must match.

All conditions within a field and between different fields are stored in a unified pool and combined using _aggregate.

The filter can also have a special group called "_must", which is a mapping of filters that must all match, no matter whether the aggregate logic is "and" or "or".

Example:

{
    "_aggregate": "or",
    "_must": {
        "city": {"exact": "New York"},
        "timezone": {"within": ["America/New_York", "America/Los_Angeles"]},
    },
    "status": {"exact": "active"},
    "id": {"within": [1, 2, 3]},
    "name": {"contains": "foo"},
}

agentlightning.SortOptions

Bases: TypedDict

Options for sorting the collection.

name instance-attribute

The name of the field to sort by.

order instance-attribute

The order to sort by.

agentlightning.FilterField

Bases: TypedDict

An operator dict for a single field.

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.

create_time instance-attribute

Timestamp of the creation time of the resources.

resources instance-attribute

Mapping of resource names to their definitions.

resources_id instance-attribute

Identifier used to version the resources.

update_time instance-attribute

Timestamp of the last update time of the resources.

version instance-attribute

Version of 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.SpanAttributeNames

Bases: str, Enum

Canonical attribute names written by Agent Lightning emitters. Deprecated in favor of semconv.

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.

Semantic Conventions

agentlightning.semconv

Semantic conventions for Agent-lightning spans.

Conventions in this file are added on demand. We generally DO NOT add new semantic conventions unless it's absolutely needed for certain algorithms or scenarios.

AGL_ANNOTATION = 'agentlightning.annotation' module-attribute

Agent-lightning's standard span name for annotations.

Annotations are minimal span units for rewards, tags, and metadatas. They are used to "annotate" a specific event or a part of rollout.

AGL_EXCEPTION = 'agentlightning.exception' module-attribute

Agent-lightning's standard span name for exceptions.

Used by the exception emitter to record exception details.

AGL_MESSAGE = 'agentlightning.message' module-attribute

Agent-lightning's standard span name for messages and logs.

AGL_OBJECT = 'agentlightning.object' module-attribute

Agent-lightning's standard span name for customized objects.

AGL_VIRTUAL = 'agentlightning.virtual' module-attribute

Agent-lightning's standard span name for virtual operations.

Mostly used in adapter when needing to represent the root or intermediate operations.

LightningResourceAttributes

Bases: Enum

Resource attribute names used in Agent-lightning spans.

ATTEMPT_ID = 'agentlightning.attempt_id' class-attribute instance-attribute

Resource name for attempt ID in Agent-lightning spans.

ROLLOUT_ID = 'agentlightning.rollout_id' class-attribute instance-attribute

Resource name for rollout ID in Agent-lightning spans.

SPAN_SEQUENCE_ID = 'agentlightning.span_sequence_id' class-attribute instance-attribute

Resource name for span sequence ID in Agent-lightning spans.

LightningSpanAttributes

Bases: Enum

Attribute names that commonly appear in Agent-lightning spans.

Exception types can't be found here because they are defined in OpenTelemetry's official semantic conventions.

Attribute name for linking the current span to another span or other objects like requests/responses.

MESSAGE_BODY = 'agentlightning.message.body' class-attribute instance-attribute

Attribute name for message text in message spans.

OBJECT_JSON = 'agentlightning.object.json' class-attribute instance-attribute

Attribute name for object serialized value (JSON) in object spans.

OBJECT_LITERAL = 'agentlightning.object.literal' class-attribute instance-attribute

Attribute name for object literal value in object spans (for str, int, bool, ...).

OBJECT_TYPE = 'agentlightning.object.type' class-attribute instance-attribute

Attribute name for object type (full qualified name) in object spans.

I think builtin types like str, int, bool, list, dict are self-explanatory and should also be qualified to use here.

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

Attribute prefix for rewards-related data in reward spans.

It should be used as a prefix. For example, "agentlightning.reward.0.value" can be used to track a specific metric. See RewardAttributes.

TAG = 'agentlightning.tag' class-attribute instance-attribute

Attribute name for tagging spans with customized strings.

LinkAttributes

Bases: Enum

Standard link types used in Agent-lightning spans.

The link is more powerful than OpenTelemetry link in that it supports linking to a queryset of spans. It can even link to span object that hasn't been emitted yet.

KEY_MATCH = 'key_match' class-attribute instance-attribute

Linking to spans with matching attribute keys.

trace_id and span_id are reserved and will be used to link to specific spans directly.

For example, it can be gen_ai.response.id if intended to be link to a chat completion response span. Or it can be span_id to link to a specific span by its ID.

VALUE_MATCH = 'value_match' class-attribute instance-attribute

Linking to spans with corresponding attribute values on those keys.

LinkPydanticModel

Bases: BaseModel

A stricter implementation of LinkAttributes used in otel helpers.

key_match instance-attribute

The attribute key to match on the target spans.

value_match instance-attribute

The attribute value to match on the target spans.

RewardAttributes

Bases: Enum

Multi-dimensional reward attributes will look like:

{"agentlightning.reward.0.name": "efficiency", "agentlightning.reward.0.value": 0.75}

The first reward in the reward list will automatically be the primary reward. If the reward list has greater than 1, it shall be a multi-dimensional case.

REWARD_NAME = 'name' class-attribute instance-attribute

Key for each dimension in multi-dimensional reward spans.

REWARD_VALUE = 'value' class-attribute instance-attribute

Value for each dimension in multi-dimensional reward spans.

RewardPydanticModel

Bases: BaseModel

A stricter implementation of RewardAttributes used in otel helpers.

name instance-attribute

Name of the reward dimension.

value instance-attribute

Value of the reward dimension.

Environment Variables

agentlightning.LightningEnvVar

Bases: Enum

Environment variables for Agent Lightning.

AGL_CURRENT_ROLE = 'AGL_CURRENT_ROLE' class-attribute instance-attribute

Which side(s) to run in this process. Used in ClientServerExecutionStrategy.

AGL_EMITTER_DEBUG = 'AGL_EMITTER_DEBUG' class-attribute instance-attribute

Enable debug logging for the emitter.

AGL_MANAGED_STORE = 'AGL_MANAGED_STORE' class-attribute instance-attribute

If yes, the ExecutionStrategy constructs LightningStore wrappers automatically. When False the provided store is passed directly to the bundles, allowing callers to manage store wrappers manually.

AGL_SERVER_HOST = 'AGL_SERVER_HOST' class-attribute instance-attribute

Interface the LightningStoreServer binds to when running the algorithm bundle locally.

AGL_SERVER_PORT = 'AGL_SERVER_PORT' class-attribute instance-attribute

Port the LightningStoreServer listens to.

agentlightning.resolve_bool_env_var(env_var, override=None, fallback=None) 

resolve_bool_env_var(
    env_var: LightningEnvVar, override: bool, fallback: bool
) -> bool

resolve_bool_env_var(
    env_var: LightningEnvVar, *, fallback: bool
) -> bool

resolve_bool_env_var(
    env_var: LightningEnvVar,
    override: bool | None = None,
    fallback: bool | None = None,
) -> bool | None

Resolve a boolean environment variable.

Parameters:

  • env_var (LightningEnvVar) –

    The environment variable to resolve.

  • override (bool | None, default: None ) –

    Optional override supplied by the caller.

  • fallback (bool | None, default: None ) –

    Default value if the environment variable is not set.

agentlightning.resolve_int_env_var(env_var, override=None, fallback=None) 

resolve_int_env_var(
    env_var: LightningEnvVar, override: int, fallback: int
) -> int

resolve_int_env_var(
    env_var: LightningEnvVar, *, fallback: int
) -> int

resolve_int_env_var(
    env_var: LightningEnvVar,
    override: int | None = None,
    fallback: int | None = None,
) -> int | None

Resolve an integer environment variable.

Parameters:

  • env_var (LightningEnvVar) –

    The environment variable to resolve.

  • override (int | None, default: None ) –

    Optional override supplied by the caller.

  • fallback (int | None, default: None ) –

    Default value if the environment variable is not set.

agentlightning.resolve_str_env_var(env_var, override=None, fallback=None) 

resolve_str_env_var(
    env_var: LightningEnvVar, override: str, fallback: str
) -> str

resolve_str_env_var(
    env_var: LightningEnvVar, *, fallback: str
) -> str

resolve_str_env_var(
    env_var: LightningEnvVar,
    override: str | None = None,
    fallback: str | None = None,
) -> str | None

Resolve a string environment variable.

Parameters:

  • env_var (LightningEnvVar) –

    The environment variable to resolve.

  • override (str | None, default: None ) –

    Optional override supplied by the caller.

  • fallback (str | None, default: None ) –

    Default value if the environment variable is not set.