Trace the OpenAI Agents SDK with Langfuse

This notebook demonstrates how to integrate Langfuse into your OpenAI Agents workflow to monitor, debug and evaluate your AI agents.

What is the OpenAI Agents SDK?: The OpenAI Agents SDK is a lightweight, open-source framework that lets developers build AI agents and orchestrate multi-agent workflows. It provides building blocks—such as tools, handoffs, and guardrails to configure large language models with custom instructions and integrated tools. Its Python-first design supports dynamic instructions and function tools for rapid prototyping and integration with external systems.

What is Langfuse?: Langfuse is an open-source observability platform for AI agents. It helps you visualize and monitor LLM calls, tool usage, cost, latency, and more.

1. Install Dependencies

Below we install the openai-agents library (the OpenAI Agents SDK), and the OpenInference OpenAI Agents instrumentation library.

2. Configure Environment & Langfuse Credentials

Next, set up your Langfuse API keys. You can get these keys by signing up for a free Langfuse Cloud account or by self-hosting Langfuse. These environment variables are essential for the Langfuse client to authenticate and send data to your Langfuse project.

3. Instrumenting the Agent

Now, we initialize the OpenInference OpenAI Agents instrumentation. This third-party instrumentation automatically captures OpenAI Agents operations and exports OpenTelemetry (OTel) spans to Langfuse.

Now initialize the Langfuse client. get_client() initializes the Langfuse client using the credentials provided in the environment variables.

4. Hello World Example

Below we create an OpenAI Agent that always replies in haiku form. We run it with Runner.run and print the final output.

Example: Langfuse Trace

Clicking the link above (or your own project link) lets you view all sub-spans, token usage, latencies, etc., for debugging or optimization.

5. Multi-agent Handoff Example

Here we create:

• A Spanish agent that responds only in Spanish.
• An English agent that responds only in English.
• A Triage agent that routes the request to the correct agent based on the input language.

Any calls or handoffs are captured as part of the trace. That way, you can see which sub-agent or tool was used, as well as the final result.

Example: Langfuse Trace

6. Functions Example

The OpenAI Agents SDK allows the agent to call Python functions. With Langfuse instrumentation, you can see which functions are called, their arguments, and the return values. Here we define a simple function get_weather(city: str) and add it as a tool.

Example: Langfuse Trace

When viewing the trace, you’ll see a span capturing the function call get_weather and the arguments passed.

7. Grouping Agent Runs

In some workflows, you want to group multiple calls into a single trace—for instance, when building a small chain of prompts that all relate to the same user request. You can use a trace(...) context manager to nest multiple calls under one top-level trace.

Example: Langfuse Trace

Each child call is represented as a sub-span under the top-level Joke workflow span, making it easy to see the entire conversation or sequence of calls.

Link Langfuse Prompt

If you manage your prompt with Langfuse Prompt Management, you can link the used prompt to the trace by setting up an OTel Span processor.

Limitation: This method links the Langfuse Prompt to all generation spans in the trace that start with the defined string (see next cell).

Resources

• Example notebook on evaluating agents with Langfuse.