chore(weave): initial set up of the openai agents realtime API support.

[chance-wnb]

Summary

Adds manual Weave tracing support for @openai/agents-realtime RealtimeSession usage in the TypeScript SDK.

Call instrumentRealtimeSession(session) before session.connect() and Weave will automatically capture a structured call tree for the entire session:

Realtime Session
├── Realtime Session Update     ← session.updated (point-in-time)
├── Generation                  ← turn_started … turn_done  (+ token usage)
│   └── Audio Out               ← first audio chunk … audio_done
└── Generation
    └── Audio Out

No changes to user application code are required beyond the single instrumentRealtimeSession call. The adapter attaches/detaches cleanly and handles abrupt disconnects.

The future PRs will implement the auto injection.

How it works

• Session lifecycle (session.created, session.updated) is sourced from session.on('transport_event'), which proxies all raw server-sent WebSocket events.
• Generation lifecycle uses the transport's semantic turn_started / turn_done events. turn_started carries providerData.response.id; turn_done carries the full response object including token usage.
• Audio lifecycle opens on the first audio chunk (keyed by responseId) and closes on audio_done or when the parent turn_done fires, whichever comes first.
• Disconnect is detected via connection_change: 'disconnected', which cleanly closes all open calls.
• No hard dependency on @openai/agents-realtime — duck-typed interfaces (RealtimeSessionLike, RealtimeTransportLike) in a separate types file mean the integration works without adding the package as a required dependency.
• Token usage is normalised from camelCase or snake_case source keys (inputTokens / input_tokens, etc.) and stored under the session model name, matching the Record<string, LLMUsageSchema> shape the Weave backend expects.

Files changed

File	Change
src/integrations/openai.realtime.agent.ts	New — WeaveRealtimeTracingAdapter class + instrumentRealtimeSession() factory
src/integrations/openai.realtime.agent.types.ts	New — duck-typed RealtimeSessionLike / RealtimeTransportLike interfaces
src/integrations/index.ts	Export instrumentRealtimeSession
src/index.ts	Re-export instrumentRealtimeSession from top-level package

Usage

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 city',
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `The weather in ${city} is 72°F and sunny.`,
});

const agent = new RealtimeAgent({
  name: 'Assistant',
  instructions: 'You are a friendly voice assistant. Keep responses concise.',
  voice: 'verse',
  tools: [getWeatherTool],
});

async function main() {
  await weave.init('my-project');

  const session = new RealtimeSession(agent, { transport: 'websocket' });

  // Attach Weave tracing — must be called before session.connect()
  weave.instrumentRealtimeSession(session);

  session.on('agent_handoff', (_ctx, from, to) => {
    console.log(`handoff: ${from.name} → ${to.name}`);
  });
  session.on('error', (event) => console.error('[error]', event.error));

  await session.connect({ apiKey: process.env.OPENAI_API_KEY! });

  session.sendMessage('What is the weather in San Francisco?');

  // Keep alive long enough to receive a response, then disconnect
  await new Promise(resolve => setTimeout(resolve, 15_000));
  session.close();
}

main().catch(console.error);

Testing

• Tested locally.
• Unit tests TBD in the other PRs upper in the stack

[chance-wnb]

• chore(weave): Realtime API, support collecting audio data #6249
• chore(weave): Enable capturing of tool calls. #6248
• chore(weave): initial set up of the openai agents realtime API support. #6247 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[wandbot-3000]

Preview this PR with FeatureBee: https://beta.wandb.ai/?betaVersion=3a8fc39ecaf25ab809e37f01339d79e4d0d474b7

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!