OpenAI Agents SDK

Use W&B Weave with the OpenAI Agents SDK to track and monitor your agentic applications

You can use W&B Weave with the OpenAI Agents SDK to trace and monitor your agentic applications.

Python

The OpenAI Agents Python SDK is a lightweight and powerful framework for building multi-agent workflows.

Installation

Install the required dependencies using pip:

pip install weave openai-agents

Get started

To use the OpenAI Agents SDK with Weave:

• Initialize Weave with your project name.
• Add the Weave tracing processor to your agents.
• Create and run your agents as usual.

The following code sample creates an OpenAI Agent and integrates it with Weave for traceability. A Weave project is initialized and the WeaveTracingProcessor is set up to capture execution traces. A Weather data model represents weather information. The get_weather function is decorated as a tool the agent can use and returns a sample weather report. An agent named Hello world is configured with basic instructions and access to the weather tool. The main function runs the agent asynchronously with a sample input (What's the weather in Tokyo?) and prints the final response.

from pydantic import BaseModel
from agents import Agent, Runner, function_tool
import agents
import weave
import asyncio

weave.init("openai-agents")

class Weather(BaseModel):
    city: str
    temperature_range: str
    conditions: str

@function_tool
def get_weather(city: str) -> Weather:
    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")

agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather]
)

async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")    
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

View traces

When the above code sample is run, a link to the Weave dashboard is generated. Open the link to inspect traces from your agent run.

Realtime API with the Python Agents SDK

For tracing realtime voice agents built with RealtimeAgent and RealtimeRunner from the OpenAI Agents Python SDK, follow OpenAI Realtime API. That guide uses patch_openai_realtime() with Weave.

TypeScript

The OpenAI Agents Node SDK is a lightweight and powerful framework for building multi-agent workflows.

Installation

Install the required dependencies using npm:

npm install weave @openai/agents zod

Get started

In most Node.js environments, manual instrumentation is not required.
Weave automatically instruments @openai/agents when the module is loaded.

Automatic instrumentation works by registering a module loader hook:

• CommonJS projects: No additional configuration is required.
• ESM projects: Node must be started with the --import=weave/instrument flag so the instrumentation loads before other modules.

If you need help setting up your project or determining which type you are using, see TypeScript SDK: Third-Party Integration Guide.

The following code sample creates an OpenAI Agent and integrates it with Weave for traceability. Replace your-team-name/your-project-name in the Weave project initialization with your entity and project. The sample defines a get_weather tool that returns a sample weather report, then configures an agent named Hello world with basic instructions and access to the weather tool. The main function runs the agent with a sample input (What's the weather in Tokyo?) and logs the final response.

import * as weave from "weave";
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Get the current weather for a given city.",
  parameters: z.object({
    city: z.string().describe("The name of the city"),
  }),
  async execute({ city }) {
    return `${city}: 14-20C, Sunny with wind.`;
  },
});

async function main() {
  // UPDATE to your project info.
  await weave.init("your-team-name/your-project-name");

  const agent = new Agent({
    name: "Hello world",
    instructions: "You are a helpful agent.",
    tools: [getWeather],
  });

  const result = await run(agent, [
    { role: "user", content: "What's the weather in Tokyo?" },
  ]);
  console.log(result.finalOutput);
}

main();

In CommonJS, the import * as weave from "weave" statement must appear before import { Agent, run, tool } from "@openai/agents" for automatic instrumentation. If your code cannot follow this ordering, use the manual instrumentation technique that follows.

Manual instrumentation

Manual instrumentation is only needed in cases where the module loader hook cannot run, such as:

• Bundlers that bundle dependencies into a single file.
• Environments where Node CLI flags cannot be passed.
• Dynamic module loading patterns that bypass the loader hook.

In these cases, you can explicitly register the instrumentation by using instrumentOpenAIAgents():

import * as weave from "weave";

await weave.init("openai-agents");
await weave.instrumentOpenAIAgents();

For full control over the tracing processor, such as for custom processor configuration or conditional registration, create and register one manually:

import { addTraceProcessor } from "@openai/agents";
import { createOpenAIAgentsTracingProcessor } from "weave";

...

const processor = createOpenAIAgentsTracingProcessor();
addTraceProcessor(processor);

OpenAI Realtime API with the OpenAI Agents SDK

The examples above use the Agents SDK in a request-response style. You call run() with a list of messages and read finalOutput, which aligns with patterns such as the OpenAI Responses API.

The OpenAI Realtime API targets long-lived streaming sessions over a persistent connection (audio and text). The programming model is different from sending a single inference-style request and receiving one structured result.

Weave can trace Realtime usage from multiple integration paths. The OpenAI Realtime API guide focuses on Python and direct WebSocket clients. This section describes TypeScript with RealtimeAgent and RealtimeSession from @openai/agents/realtime, backed by automatic instrumentation for @openai/agents-realtime (pull request #6315, Graphite stack).

Use the same npm install command as in the Installation section of this tab. Realtime types and classes are exported from @openai/agents/realtime.

Weave patches @openai/agents-realtime through the same module loader hooks as @openai/agents. Import Weave before agent modules, and start Node with --import=weave/instrument when you use ESM. If hooks cannot run (for example in bundled apps or with dynamic imports that bypass the loader), call patchRealtimeSession() once at startup before constructing any RealtimeSession.

The following example initializes Weave, connects a session, sends a text message, and prints the assistant reply. Set OPENAI_API_KEY in your environment.

import * as weave from "weave";
import { RealtimeAgent, RealtimeSession, tool } from "@openai/agents/realtime";
import { z } from "zod";

const getWeatherTool = tool({
  name: "get_weather",
  description: "Get the current weather for a given city.",
  parameters: z.object({
    city: z.string().describe("The name of the city"),
  }),
  async execute({ city }) {
    const weather: Record<string, string> = {
      "San Francisco": "65°F, foggy",
      "New York": "72°F, sunny",
      London: "55°F, cloudy",
    };
    return weather[city] ?? "70°F, clear";
  },
});

const agent = new RealtimeAgent({
  name: "Assistant",
  instructions:
    "You are a helpful assistant. Keep responses concise. This is a realtime session.",
  tools: [getWeatherTool],
});

async function main() {
  await weave.init("your-team-name/your-project-name");

  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) throw new Error("OPENAI_API_KEY is required");

  const session = new RealtimeSession(agent);

  session.on("history_updated", (history) => {
    const last = history[history.length - 1];
    if (last?.type === "message" && last.role === "assistant") {
      const text = (last.content ?? [])
        .filter((c) => c.type === "output_text")
        .map((c) => ("text" in c ? String(c.text) : ""))
        .join("");
      if (text) console.log(`\nAssistant: ${text}`);
    }
  });

  session.on("error", (event) => {
    console.error("[error]", event.error);
  });

  await session.connect({ apiKey });
  session.sendMessage("What is the weather like in San Francisco?");

  await new Promise((resolve) => setTimeout(resolve, 10_000));
  session.close();
}

main().catch(console.error);

A full runnable script, including notes on running it from the Weave repo, is in openaiAgentsRealtime.ts (pull request #6322).