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. A complete docs-chat agent using this integration lives in examples/openai-agents (TypeScript) and examples/python/openai-agents (Python). See Runnable examples.

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 and identity options directly:

addTraceProcessor(
  openAIAgents({
    apiKey: process.env.LEMMA_API_KEY,
    projectId: process.env.LEMMA_PROJECT_ID,
    baseUrl: process.env.LEMMA_BASE_URL,
    release: process.env.LEMMA_RELEASE,
    metadata: { service: "support" },
    threadIdKey: "threadId",
    userIdKey: "userId",
  }),
);

Then run your agent normally:

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

const processor = openAIAgents();
addTraceProcessor(processor);

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);
  await processor.forceFlush();
  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 and identity options 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"),
    metadata={"service": "support"},
    thread_id_key="thread_id",
    user_id_key="user_id",
)

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

Root input, output, user, and thread

Both TypeScript and Python processors promote the same root fields on the Lemma trace:

Field	Source
Root input	First generation/response messages: last user message content
Root output	Last successful generation/response output
Root error	Hard errors on terminal span types (`agent`, `task`, `guardrail`, `custom`), not recovered soft tool errors
`threadId` / `thread_id`	OpenAI Agents `group_id`, then configurable metadata key
`userId` / `user_id`	Metadata (`userId`, `user_id`, or `resourceId` by default; override with `userIdKey` / `user_id_key`)

Soft tool failures (isError / is_error / Mastra error: true) mark the tool span as ERROR without failing the root when a later generation succeeds.

Flush and shutdown

Call forceFlush() / force_flush() (or shutdown()) to send any still-open traces exactly once. A later onTraceEnd / on_trace_end for a flushed trace is a no-op, so spans are never duplicated in the append-only ingest store.

const processor = openAIAgents();
addTraceProcessor(processor);
// ...
await processor.forceFlush();

from uselemma_tracing import openai_agents

processor = openai_agents()
# register processor, run agents...
processor.force_flush()

What Lemma records

OpenAI Agents event	Lemma record
Trace start/end	One Lemma trace named from the OpenAI Agents trace, with root I/O and timing from span bounds
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 thread id, so runs in the same conversation stay grouped.

What gets recorded

The integration always records prompts, tool inputs, tool outputs, model output, and error messages. A trace cannot show what a run produced or why it failed without them. Redact secrets and sensitive user data before they reach the agent.

Debug this integration

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.

Tracing

Integrations

Troubleshooting

Reference

OpenAI Agents SDK

TypeScript

Python

Root input, output, user, and thread

Flush and shutdown

What Lemma records

What gets recorded

Debug this integration

​TypeScript

​Python

​Root input, output, user, and thread

​Flush and shutdown

​What Lemma records

​What gets recorded

​Debug this integration

TypeScript

Python

Root input, output, user, and thread

Flush and shutdown

What Lemma records

What gets recorded

Debug this integration