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

​
Required

​
Create a run wrapper

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

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

​
Execute the run

const { result, runId } = await wrapped({ userMessage: "Reset my password" });
runId is the stable identifier you can store, return to clients, and correlate with downstream events.

​
Optional run data

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.

​
Mark a run as failed

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;
  }
});

​
Dashboard outcome

A run appears as the top-level ai.agent.run span with:
  • total duration
  • final output from onComplete
  • error state (if recordError is called or an uncaught error occurs)
  • custom attributes for filtering

​
Next Steps