OpenAI Agents SDK

Use Lemma’s OpenAI Agents integration when your app uses the OpenAI Agents SDK trace processor system. The integration creates one Lemma trace for each OpenAI Agents trace, maps model calls to generations, maps function calls to tools, and preserves parent IDs so child spans stay nested correctly. You do not need to wrap agent runs in lemma.trace(). Register the processor once, then run OpenAI Agents normally.

TypeScript

Install both packages:

npm install @uselemma/tracing @openai/agents

Register the Lemma processor before running agents. By default, credentials are read from LEMMA_API_KEY and LEMMA_PROJECT_ID:

import { addTraceProcessor } from "@openai/agents";
import { openAIAgents } from "@uselemma/tracing";

addTraceProcessor(openAIAgents());

You can also pass credentials directly:

addTraceProcessor(
  openAIAgents({
    apiKey: process.env.LEMMA_API_KEY,
    projectId: process.env.LEMMA_PROJECT_ID,
    baseUrl: process.env.LEMMA_BASE_URL,
  }),
);

Then run your agent normally:

import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "support-agent",
  instructions: "Answer customer questions clearly and concisely.",
});

export async function callAgent(userMessage: string) {
  const result = await run(agent, userMessage);
  return result.finalOutput;
}

Python

Install the Python extra:

pip install "uselemma-tracing[openai-agents]" openai-agents

Register the Lemma processor before running agents. By default, credentials are read from LEMMA_API_KEY and LEMMA_PROJECT_ID:

from uselemma_tracing import instrument_openai_agents

instrument_openai_agents()

You can also pass credentials directly:

import os

from uselemma_tracing import instrument_openai_agents

instrument_openai_agents(
    api_key=os.environ["LEMMA_API_KEY"],
    project_id=os.environ["LEMMA_PROJECT_ID"],
    base_url=os.getenv("LEMMA_BASE_URL", "https://api.uselemma.ai"),
)

Then run your agent normally:

from agents import Agent, Runner

agent = Agent(
    name="support-agent",
    instructions="Answer customer questions clearly and concisely.",
)

async def call_agent(user_message: str):
    result = await Runner.run(agent, user_message)
    return result.final_output

What Lemma records

OpenAI Agents event	Lemma record
Trace start/end	One Lemma trace named from the OpenAI Agents trace
Generation or response span	Generation with model, input, output, timing, and OpenAI span attributes
Function span	Tool call with tool name, input, output or error, timing, and parent ID
Other span types	Regular span with OpenAI trace/span fields preserved in attributes

OpenAI Agents trace group_id is recorded as the Lemma threadId, so runs in the same conversation stay grouped.

Privacy

The integration records prompts, tool inputs, tool outputs, and model output by default. Disable input/output recording when you need structure and timings without payload contents:

addTraceProcessor(openAIAgents({ recordInputs: false, recordOutputs: false }));

from uselemma_tracing import instrument_openai_agents

instrument_openai_agents(record_inputs=False, record_outputs=False)

Debugging

Use debug mode to confirm spans are arriving live and nested under the expected parent:

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

enableDebugMode();

from uselemma_tracing import enable_debug_mode

enable_debug_mode()

Look for span started and span ended logs. Tool/function spans should include the generation or agent span ID as parentId in TypeScript or parent_id in Python.

​TypeScript

​Python

​What Lemma records

​Privacy

​Debugging

TypeScript

Python

What Lemma records

Privacy

Debugging