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.

Set credentials

Find these in Lemma project settings, or in the project get-started flow.

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

Keep LEMMA_API_KEY server-side. Never commit it. Never put it in browser or client-side code. The SDK sends to https://api.uselemma.ai by default. Pass baseUrl / base_url only for a custom endpoint.

What a ready trace is

Creating an API key, adding an SDK dependency, or seeing an ingest attempt does not prove observability. Observability is proven when a real production-like path produces a ready trace you can open in the dashboard: inspectable, with a root, nested work, and input and output you recognize. A key, an SDK install, or a failed or empty ingest is not a ready trace.

What you are building

You 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)

Instrument the agent

Pick one path. Framework adapters live on the integration pages: Vercel AI SDK, OpenAI Agents, LangChain, and LangGraph.

Coding agent
Direct SDK

Use a coding agent to instrument the production agent.

Open the project get-started flow

In the Lemma dashboard, select or create the organization and project, then open that project’s get-started flow.

Install the tracing skill

npx skills add uselemma/lemma --skill "lemma-tracing"

Ask the coding agent to use that skill to instrument the production agent.

Exercise a real path

Run a production-like request through the instrumented agent.

Install the SDK and record one generation and one tool call inside a trace callback.

Install the SDK

TypeScript
Python

npm install @uselemma/tracing

pip install uselemma-tracing

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 a ready trace

Open Traces in the Lemma dashboard. 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

After the trace looks complete, see Overview for issues, Inspect, and workflow connections.

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 ready trace lands.

Instrument an agent

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

Runnable examples

The same docs chat agent, instrumented once per stack.

Traces in the dashboard

Search and inspect the trace you sent.

Overview

Issues, Inspect, Artifacts, and Analytics after ingest.

Tracing

Integrations

Troubleshooting

Reference

Set credentials

What a ready trace is

What you are building

Instrument the agent

Verify a ready trace

Stamp a release

Next steps

Instrument an agent

Runnable examples

Traces in the dashboard

Overview

​Set credentials

​What a ready trace is

​What you are building

​Instrument the agent

​Verify a ready trace

​Stamp a release

​Next steps

Instrument an agent

Runnable examples

Traces in the dashboard

Overview

Set credentials

What a ready trace is

What you are building

Instrument the agent

Verify a ready trace

Stamp a release

Next steps