From-Scratch Agent

This guide shows how to instrument an agent built from scratch, without relying on a framework integration. You will add:

a top-level run span using agent()
generation spans for LLM calls using llm()
tool-call spans using tool()
run-level metadata for filtering
error handling for failed runs and child spans

Prerequisites

You have a Lemma API key and project ID.
You can run a plain Node.js or Python app.
Your agent loop is code you control directly (no framework wrapper).

Instrument the Agent

Install and configure tracing

TypeScript
Python

npm install @uselemma/tracing openai

// tracer.ts
import { registerOTel } from "@uselemma/tracing";

registerOTel({
  apiKey: process.env.LEMMA_API_KEY,
  projectId: process.env.LEMMA_PROJECT_ID,
});

pip install uselemma-tracing openai

# tracer.py
import os
from uselemma_tracing import register_otel

register_otel(
    api_key=os.getenv("LEMMA_API_KEY"),
    project_id=os.getenv("LEMMA_PROJECT_ID"),
)

Wrap your agent as a run

Use agent() to create the top-level run span.

TypeScript
Python

import "./tracer";
import { agent } from "@uselemma/tracing";

const runAgent = agent("scratch-agent", async (input, ctx) => {
  ctx.span.setAttribute("lemma.user_id", input.userId);
  ctx.span.setAttribute("lemma.session_id", input.sessionId);
  ctx.span.setAttribute("lemma.feature", "support_chat");

  return await executeAgentLoop(input.message);
});

import tracer  # Ensure tracing is registered before agent code runs.
from uselemma_tracing import agent, TraceContext

async def agent_logic(input_data: dict, ctx: TraceContext):
    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.feature", "support_chat")

    return await execute_agent_loop(input_data["message"])

run_agent = agent("scratch-agent", agent_logic)

Wrap LLM calls with llm()

The llm() helper creates a generation span under the active run. Pass the model name as the span label.

TypeScript
Python

import { llm } from "@uselemma/tracing";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const generate = llm("gpt-4o", async (userMessage: string) => {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: userMessage }],
  });
  return response.choices[0]?.message?.content ?? "";
});

from uselemma_tracing import llm
from openai import AsyncOpenAI

client = AsyncOpenAI()

@llm("gpt-4o")
async def generate(user_message: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_message}],
    )
    return response.choices[0].message.content or ""

Wrap tools with tool()

The tool() helper creates a tool-call span nested under the active run.

TypeScript
Python

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

const getWeatherTool = tool("get-weather", async (city: string) => {
  return await getWeather(city);
});

from uselemma_tracing import tool

@tool("get-weather")
async def get_weather_tool(city: str) -> dict:
    return await get_weather(city)

Wire everything into one agent loop

TypeScript
Python

import "./tracer";
import { agent, llm, tool } from "@uselemma/tracing";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const generate = llm("gpt-4o", async (prompt: string) => {
  const res = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: prompt }],
  });
  return res.choices[0]?.message?.content ?? "";
});

const getWeatherTool = tool("get-weather", async (city: string) => {
  return await getWeather(city);
});

const runAgent = agent("scratch-agent", async (input, ctx) => {
  ctx.span.setAttribute("lemma.user_id", input.userId);

  const weatherContext = await getWeatherTool(input.city); // span: tool.get-weather
  const answer = await generate(input.message);             // span: llm.gpt-4o

  return answer;
});

import tracer
from uselemma_tracing import agent, llm, tool, TraceContext
from openai import AsyncOpenAI

client = AsyncOpenAI()

@llm("gpt-4o")
async def generate(prompt: str) -> str:
    res = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    return res.choices[0].message.content or ""

@tool("get-weather")
async def get_weather_tool(city: str) -> dict:
    return await get_weather(city)

async def agent_logic(input_data: dict, ctx: TraceContext) -> str:
    ctx.span.set_attribute("lemma.user_id", input_data["user_id"])

    weather = await get_weather_tool(input_data["city"])  # span: tool.get-weather
    answer = await generate(input_data["message"])         # span: llm.gpt-4o

    return answer

run_agent = agent("scratch-agent", agent_logic)

The helpers handle error recording and span lifecycle automatically — no try/finally or manual span.end() needed.

Run and verify in Lemma

Execute one agent request.
In Lemma, verify:
- top-level ai.agent.run span exists
- llm.gpt-4o generation span is nested under the run
- tool.get-weather span appears with the tool result
- custom metadata (lemma.user_id, lemma.session_id) is filterable

Troubleshooting checklist

No runs visible: ensure registerOTel / register_otel runs before your app logic.
Run appears but no child spans: make sure llm() / tool() wrapped functions are called inside the agent() wrapper.
Run never closes: in streaming mode, ensure ctx.complete() is called inside the finish callback.
Missing metadata filters: verify attributes are set on the run span, not on unrelated spans.

Recipes

​Prerequisites

​Instrument the Agent

​Troubleshooting checklist

Prerequisites

Instrument the Agent

Troubleshooting checklist