> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselemma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Record OpenAI Agents SDK traces with Lemma

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:

```bash theme={null}
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`:

```typescript theme={null}
import { addTraceProcessor } from "@openai/agents";
import { openAIAgents } from "@uselemma/tracing";

addTraceProcessor(openAIAgents());
```

You can also pass credentials directly:

```typescript theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
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`:

```python theme={null}
from uselemma_tracing import instrument_openai_agents

instrument_openai_agents()
```

You can also pass credentials directly:

```python theme={null}
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:

```python theme={null}
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:

```typescript theme={null}
addTraceProcessor(openAIAgents({ recordInputs: false, recordOutputs: false }));
```

```python theme={null}
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:

```typescript theme={null}
import { enableDebugMode } from "@uselemma/tracing";

enableDebugMode();
```

```python theme={null}
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.