Run usage

TypeScript
Python

A run is a single end-to-end execution of your agent. In Lemma custom instrumentation, runs are created with wrapAgent.

A run is a single end-to-end execution of your agent. In Lemma custom instrumentation, runs are created with wrap_agent.

Required

Create a run wrapper

TypeScript
Python

import { wrapAgent } from "@uselemma/tracing";

const wrapped = wrapAgent("support-agent", async ({ onComplete }, input) => {
  const finalAnswer = await solveUserRequest(input.userMessage);
  onComplete(finalAnswer);
  return finalAnswer;
});

from uselemma_tracing import TraceContext, wrap_agent

async def run_agent(ctx: TraceContext, input_data: dict):
    final_answer = await solve_user_request(input_data["user_message"])
    ctx.on_complete(final_answer)
    return final_answer

wrapped = wrap_agent("support-agent", run_agent)

Execute the run

TypeScript
Python

const { result, runId } = await wrapped(
  { userMessage: "Reset my password" },
  { threadId: "support-thread-42", isExperiment: false } // optional second argument
);

runId is the stable identifier you can store, return to clients, and correlate with downstream events.

result, run_id, span = await wrapped(
    {"user_message": "Reset my password"},
    {"thread_id": "support-thread-42", "is_experiment": False},  # optional second argument
)

run_id is the stable identifier you can return, store, and correlate with downstream signals.

Per-invocation options

Pass a second argument to the wrapped function for lemma.thread_id and to override the default experiment flag for that call only. Full reference: Per-invocation options.

Optional run data

TypeScript
Python

Run-level data is usually attached as span attributes from inside the wrapped function:

const wrapped = wrapAgent("support-agent", async ({ span, onComplete }, input) => {
  span.setAttribute("lemma.user_id", input.userId);
  span.setAttribute("lemma.session_id", input.sessionId);
  span.setAttribute("lemma.route", "chat.support");

  const finalAnswer = await solveUserRequest(input.userMessage);
  onComplete(finalAnswer);
  return finalAnswer;
});

Recommended run-level keys:

lemma.user_id
lemma.session_id
lemma.environment
lemma.feature

Using consistent keys makes filtering in the dashboard predictable across services.

Attach run-level attributes on the root span:

async def run_agent(ctx: TraceContext, input_data: dict):
    ctx.span.set_attribute("lemma.user_id", input_data["user_id"])
    ctx.span.set_attribute("lemma.session_id", input_data["session_id"])
    ctx.span.set_attribute("lemma.route", "chat.support")

    final_answer = await solve_user_request(input_data["user_message"])
    ctx.on_complete(final_answer)
    return final_answer

Recommended run-level keys:

lemma.user_id
lemma.session_id
lemma.environment
lemma.feature

Mark a run as failed

TypeScript
Python

Use recordError and rethrow so the run is visibly errored and your app still handles failures normally.

const wrapped = wrapAgent("support-agent", async ({ recordError }, input) => {
  try {
    return await solveUserRequest(input.userMessage);
  } catch (error) {
    recordError(error);
    throw error;
  }
});

Use record_error and re-raise the exception:

async def run_agent(ctx: TraceContext, input_data: dict):
    try:
        return await solve_user_request(input_data["user_message"])
    except Exception as err:
        ctx.record_error(err)
        raise

Dashboard outcome

A run appears as the top-level ai.agent.run span with:

total duration
final output from onComplete / on_complete
error state (if recordError / record_error is called or an uncaught error occurs)
custom attributes for filtering

Getting Started

Tracing

Experiments

Integrations

Required

Create a run wrapper

Execute the run

Per-invocation options

Optional run data

Mark a run as failed

Dashboard outcome

Next Steps

Getting Started

Tracing

Experiments

Integrations

​Required

​Create a run wrapper

​Execute the run

​Per-invocation options

​Optional run data

​Mark a run as failed

​Dashboard outcome

​Next Steps

Required

Create a run wrapper

Execute the run

Per-invocation options

Optional run data

Mark a run as failed

Dashboard outcome

Next Steps