Quickstart

Send one complete agent trace to Lemma. The software development kit (SDK) sends JSON to the Lemma API. One agent execution is one trace. Record model calls, tool calls, retrieval, and app logic inside that trace.

What you are building

You will send one support-agent trace with a nested generation and tool call.

support-agent              <- trace root (input, output)
├── draft-reply            <- generation (model, content)
└── search_docs            <- tool call (args, result)

Steps

Install the SDK

TypeScript
Python

npm install @uselemma/tracing

pip install uselemma-tracing

Set environment variables

Find these in Lemma project settings.

export LEMMA_API_KEY="lma_..."
export LEMMA_PROJECT_ID="proj_..."
export LEMMA_RELEASE="1.8.3" # optional

The SDK sends to https://api.uselemma.ai by default. Pass baseUrl / base_url only for a custom endpoint.

Trace one agent execution

Create a client, open a trace, then record one generation and one tool call inside the trace callback.

TypeScript
Python

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

const lemma = new Lemma();

const answer = await lemma.trace(
  {
    name: "support-agent",
    input: userMessage,
    threadId: conversationId,
    userId: user.id,
  },
  async (trace) => {
    const docs = await searchDocs(userMessage);
    trace.recordTool({
      name: "search_docs",
      input: { query: userMessage },
      output: docs,
    });

    const response = await callModel(userMessage, docs);
    trace.recordGeneration({
      name: "draft-reply",
      input: response.messages,
      output: response.text,
      model: "gpt-4o",
    });

    return response.text;
  },
);

from uselemma_tracing import Lemma

lemma = Lemma()

def run(trace):
    docs = search_docs(user_message)
    trace.record_tool(
        name="search_docs",
        input={"query": user_message},
        output=docs,
    )

    response = call_model(user_message, docs)
    trace.record_generation(
        name="draft-reply",
        input=response.messages,
        output=response.text,
        model="gpt-4o",
    )

    return response.text

answer = lemma.trace(
    "support-agent",
    run,
    input=user_message,
    thread_id=conversation_id,
    user_id=user.id,
)

Verify in Lemma

Open the Lemma dashboard and go to Traces. You should see:

One trace for the whole execution
The root trace with input and output
A nested generation with model metadata
A nested tool call with arguments and result

Stamp a release

Tag every ingest payload with the stable identifier your deployment process assigns to the running app, such as an app version, commit SHA, or container tag. Change it with each deployment. Pass release on the client, or set LEMMA_RELEASE. Most continuous integration systems expose the current commit SHA as an environment variable. Set LEMMA_RELEASE to that value during deployment. An explicit constructor value wins over the environment variable. Lemma omits empty, whitespace-only, longer-than-200-character, or newline, tab, or carriage-return values. It does not guess a git SHA. Adapters (vercelAI, openAIAgents, langChain, langGraph, mastra) accept the same release field and forward it to the client they construct.

TypeScript
Python

const lemma = new Lemma({
  release: "1.8.3",
});

lemma = Lemma(release="1.8.3")

Next steps

Use these pages after the first trace lands.

Instrument an agent

Add spans, tools, generations, and errors to a real agent.

Concepts

Traces, spans, generations, and threads.

Trace contract

The exact shape Lemma reads.

Threads and context

Group conversations and attach users.

Getting Started

Platform

Instrumentation

Integrations

Connections

What you are building

Steps

Stamp a release

Next steps

Instrument an agent

Concepts

Trace contract

Threads and context

​What you are building

​Steps

​Stamp a release

​Next steps

Instrument an agent

Concepts

Trace contract

Threads and context

What you are building

Steps

Stamp a release

Next steps