Skip to content

Agent Developer APIs

Agent Decorators

Tip

These are convenient helpers for creating agents from functions. First-time users are recommended to use these decorators to create agents.

agentlightning.rollout(func)

Create a FunctionalLitAgent from an arbitrary rollout function.

This function inspects the provided callable and creates the appropriate agent type based on its signature. It supports both LLM-based and prompt-template-based agents. The returned agent instance is callable, preserving the original function's behavior and type hints.

See llm_rollout and prompt_rollout for more details.

Parameters:

  • func (Union[LlmRolloutFunc[T], PromptRolloutFunc[T], Callable[..., Any]]) –

    Callable that implements the rollout. Supported signatures:

    • [async ](task, llm[, rollout]) for LLM-based agents
    • [async ](task, prompt_template[, rollout]) for prompt-template-based agents

    The supported output types of func is same as the return type of rollout.

Returns:

Examples:

# LLM-based agent
@rollout
def my_llm_agent(task, llm):
    client = OpenAI(base_url=llm.endpoint)
    response = client.chat.completions.create(
        model=llm.model,
        messages=[{"role": "user", "content": task.input}],
    )
    return response

# Prompt-template-based agent
@rollout
def my_prompt_agent(task, prompt_template):
    messages = prompt_template.format(task=task.input)
    # ... perform rollout with the formatted prompt
    return response

# Function is still callable with original behavior
result = my_llm_agent(task, llm)

# Agent methods are also available
result = my_llm_agent.rollout(task, resources, rollout)

Raises:

  • NotImplementedError –

    If the function signature doesn't match any known patterns.

Warning

The following two decorators are implementations of agentlightning.rollout. They are not recommended for new users.

agentlightning.llm_rollout(func=None, *, strip_proxy=True) 

llm_rollout(
    func: LlmRolloutFunc[T],
) -> FunctionalLitAgent[T]

llm_rollout(
    *, strip_proxy: bool = True
) -> Callable[[LlmRolloutFunc[T]], FunctionalLitAgent[T]]

Create a FunctionalLitAgent for LLM-based rollouts.

Parameters:

  • func (LlmRolloutFunc[T] | None, default: None ) –

    Callable defining the agent's behaviour. Supported signatures include:

    • (task, llm) -> result
    • (task, llm, rollout) -> result
    • async (task, llm) -> result
    • async (task, llm, rollout) -> result
  • strip_proxy (bool, default: True ) –

    When True, convert proxy resources into concrete LLM instances before calling the function. Defaults to True.

Returns:

Examples:

@llm_rollout
def my_agent(task, llm):
    return llm.endpoint

@llm_rollout(strip_proxy=False)
def my_agent_no_strip(task, llm):
    return llm.model

result = my_agent(task, llm)
result = my_agent.rollout(task, resources, rollout)

agentlightning.prompt_rollout(func=None) 

prompt_rollout(
    func: PromptRolloutFunc[T],
) -> FunctionalLitAgent[T]

prompt_rollout() -> (
    Callable[[PromptRolloutFunc[T]], FunctionalLitAgent[T]]
)

Create a FunctionalLitAgent for prompt-based rollouts.

This decorator is designed for agents that work with tunable prompt templates. It enables a workflow where algorithms manage and optimize the prompt template, while agents consume the template to perform rollouts. This is particularly useful for prompt optimization scenarios.

Parameters:

  • func (PromptRolloutFunc[T] | None, default: None ) –

    Callable defining the agent's behavior. Supported signatures include:

    • (task, prompt_template) -> result
    • (task, prompt_template, rollout) -> result
    • async (task, prompt_template) -> result
    • async (task, prompt_template, rollout) -> result

Returns:

Examples:

@prompt_rollout
def my_agent(task, prompt_template):
    messages = prompt_template.format(task=task.input)
    return messages

result = my_agent(task, prompt_template)
result = my_agent.rollout(task, resources, rollout)

Class-based Agents

agentlightning.LitAgent

Bases: Generic[T]

Base class for implementing agent rollouts.

Subclasses override the rollout methods to process tasks while the trainer and runner infrastructure manages orchestration, tracing, and persistence.

runner property

Return the runner responsible for executing rollouts.

tracer property

Return the tracer configured for this agent.

trainer property

Return the trainer associated with this agent.

__init__(*, trained_agents=None)

Initialize the agent instance.

Parameters:

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

    Optional identifier used by legacy tooling to mark trained agents.

Deprecated

The trained_agents flag is deprecated. Configure agent_match in the adapter layer instead. See TracerTraceToTriplet for more details.

get_runner()

Return the runner responsible for executing rollouts.

get_tracer()

Return the tracer configured for this agent.

get_trainer()

Return the trainer associated with this agent.

is_async()

Return True when the agent overrides any asynchronous rollout methods.

Override this method for customized async detection logic.

on_rollout_end(task, rollout, runner, tracer)

Hook invoked after a rollout completes.

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

Parameters:

Deprecated

Override Hook.on_rollout_end instead of this method when extending agents.

on_rollout_start(task, runner, tracer)

Hook invoked immediately before a rollout begins.

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

Parameters:

Deprecated

Override Hook.on_rollout_start instead of this method when extending agents.

rollout(task, resources, rollout)

Execute a rollout synchronously.

If you don't wish to implement both training rollout and validation rollout separately, you can just implement rollout which will work for both.

Parameters:

  • task (T) –

    Task payload provided by the scheduler.

  • resources (NamedResources) –

    Mapping of named resources (for example LLMs or prompt templates).

  • rollout (Rollout) –

    Rollout metadata. Avoid mutating this object directly unless a subclass needs to override defaults.

Returns:

rollout_async(task, resources, rollout) async

Execute a rollout asynchronously.

Parameters:

  • task (T) –

    Task payload provided by the scheduler.

  • resources (NamedResources) –

    Mapping of named resources (for example LLMs or prompt templates).

  • rollout (Rollout) –

    Rollout metadata. Avoid mutating this object directly unless a subclass needs to override defaults.

Returns:

set_runner(runner)

Attach the runner responsible for executing rollouts.

Parameters:

set_trainer(trainer)

Attach the trainer responsible for orchestration.

Parameters:

training_rollout(task, resources, rollout)

Process a single training task synchronously.

By default, this method delegates to rollout.

training_rollout_async(task, resources, rollout) async

Process a single training task asynchronously.

By default, this method delegates to rollout_async.

validation_rollout(task, resources, rollout)

Process a single validation task synchronously.

Override this method when validation should differ from training. The default implementation delegates to training_rollout.

validation_rollout_async(task, resources, rollout) async

Process a single validation task asynchronously.

Override this method when validation should differ from training. The default implementation delegates to training_rollout_async.

Emitter

agentlightning.emit_reward(reward)

Emit a reward value as an OpenTelemetry span.

Parameters:

  • reward (float) –

    Numeric reward to record. Integers and booleans are converted to floating point numbers for consistency.

Returns:

  • ReadableSpan –

    Readable span capturing the recorded reward.

Raises:

  • ValueError –

    If the provided reward cannot be interpreted as a float or the resulting span is not a ReadableSpan instance.

agentlightning.emit_message(message)

Emit a textual message as an OpenTelemetry span.

Parameters:

  • message (str) –

    Human readable message to attach as a span attribute.

Note

OpenTelemetry distinguishes between logs and spans. Emitting the message as a span keeps all Agent Lightning telemetry in a single data store for analysis.

agentlightning.emit_object(object)

Emit an object's serialized representation as an OpenTelemetry span.

Parameters:

  • object (Any) –

    Data structure to encode as JSON and attach to the span payload.

Note

The payload must be JSON serializable. Non-serializable objects are ignored and an error is logged to aid debugging.

agentlightning.emit_exception(exception)

Record an exception with OpenTelemetry metadata.

Parameters:

  • exception (BaseException) –

    Raised exception instance to serialize into telemetry attributes.

Note

The helper validates its input. Non-exception values are ignored to prevent noisy telemetry and indicate programming mistakes via the logger.

Reward Helpers

agentlightning.find_final_reward(spans)

Return the last reward value present in the provided spans.

Parameters:

  • spans (Sequence[SpanLike]) –

    Sequence containing ReadableSpan objects or mocked span-like values.

Returns:

  • Optional[float] –

    Reward value from the latest reward span, or None when none are found.

agentlightning.find_reward_spans(spans)

Return all reward spans in the provided sequence.

Parameters:

  • spans (Sequence[SpanLike]) –

    Sequence containing ReadableSpan objects or mocked span-like values.

Returns:

  • List[SpanLike] –

    List of spans that could be parsed as rewards.

agentlightning.get_reward_value(span)

Extract the reward value from a span, if available.

Parameters:

  • span (SpanLike) –

    Span object produced by AgentOps or Agent Lightning emitters.

Returns:

  • Optional[float] –

    The reward encoded in the span or None when the span does not represent a reward.

agentlightning.is_reward_span(span)

Return True when the provided span encodes a reward value.

Legacy Emitter Decorators

agentlightning.reward.reward(fn)

Decorate a reward function so its outputs are tracked as spans.

The decorator integrates with AgentOps when it is available and falls back to the built-in telemetry otherwise. Both synchronous and asynchronous functions are supported transparently.

Deprecated

This decorator is deprecated. Use emit_reward instead.

Parameters:

  • fn (FnType) –

    Callable that produces a numeric reward.

Returns:

  • FnType –

    Wrapped callable that preserves the original signature.