From 3074fdd80e8c00d8b409c8f6e35fcce4b3a1969e Mon Sep 17 00:00:00 2001 From: anastasiaguspan Date: Mon, 2 Mar 2026 10:35:29 -0500 Subject: [PATCH 1/3] first draft --- weave/guides/integrations/openai_agents.mdx | 86 ++++++++++++++++++++- 1 file changed, 85 insertions(+), 1 deletion(-) diff --git a/weave/guides/integrations/openai_agents.mdx b/weave/guides/integrations/openai_agents.mdx index d910c6fe72..429e7f318b 100644 --- a/weave/guides/integrations/openai_agents.mdx +++ b/weave/guides/integrations/openai_agents.mdx @@ -2,7 +2,8 @@ title: "OpenAI Agents SDK" description: "Use W&B Weave with the OpenAI Agents SDK to track and monitor your agentic applications" --- - + + The [OpenAI Agents Python SDK](https://github.com/openai/openai-agents-python) is a lightweight and powerful framework for building multi-agent workflows. You can use W&B Weave with the OpenAI Agents SDK to track and monitor your agentic applications. ## Installation @@ -58,3 +59,86 @@ if __name__ == "__main__": ## View traces When the above code sample is run, a link to the Weave dashboard is generated. To see what happened during your agent execution, follow the link to see your agent traces. + + +The [OpenAI Agents Node SDK](https://github.com/openai/openai-node) is a lightweight and powerful framework for building multi-agent workflows. You can use W&B Weave with the OpenAI Agents SDK to trace and monitor your agentic applications in TypeScript. + +## Installation + +Install the required dependencies using `npm`: + +```bash +npm install weave @openai/agents zod +``` + +## Get started + +To use the OpenAI Agents SDK with Weave, you need to: + +- Initialize Weave with your project name. +- Create and run your agents as usual. Weave automatically instruments `@openai/agents` through module loader hooks, so no additional setup is required. + +In the following code sample, an OpenAI Agent is created and integrated with Weave for traceability. First, update `your-team-name/your-project-name` in the Weave project initialization to real values. A `get_weather` tool is defined that 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 with a sample input (`What's the weather in Tokyo?`) and outputs the final response. + +```typescript +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(); + +``` + +### Manual instrumentation + +In most cases, automatic instrumentation handles everything. If you need manual control, for example when using dynamic imports or bundlers that bypass module hooks, you can call `instrumentOpenAIAgents()` explicitly: + +```typescript +import * as weave from "weave"; + +await weave.init("openai-agents"); +await weave.instrumentOpenAIAgents(); +``` + +Alternatively, for full control over the tracing processor, create and register one manually: + +```typescript +import { addTraceProcessor } from "@openai/agents"; +import { createOpenAIAgentsTracingProcessor } from "weave"; + +const processor = createOpenAIAgentsTracingProcessor(); +addTraceProcessor(processor); +``` + +## View traces + +When the above code sample is run, a link to the Weave dashboard is generated. To see what happened during your agent execution, follow the link to see your agent traces. + + \ No newline at end of file From c814eb2e2c5c53e70268572bbdb67b9173e52b1d Mon Sep 17 00:00:00 2001 From: anastasiaguspan Date: Mon, 2 Mar 2026 16:33:48 -0500 Subject: [PATCH 2/3] draft --- weave/guides/integrations/openai_agents.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/weave/guides/integrations/openai_agents.mdx b/weave/guides/integrations/openai_agents.mdx index 429e7f318b..29b3d1d44a 100644 --- a/weave/guides/integrations/openai_agents.mdx +++ b/weave/guides/integrations/openai_agents.mdx @@ -99,6 +99,7 @@ const getWeather = tool({ async function main() { // UPDATE to your project info. await weave.init("your-team-name/your-project-name"); + await weave.instrumentOpenAIAgents(); const agent = new Agent({ name: "Hello world", @@ -116,6 +117,7 @@ main(); ``` + ### Manual instrumentation In most cases, automatic instrumentation handles everything. If you need manual control, for example when using dynamic imports or bundlers that bypass module hooks, you can call `instrumentOpenAIAgents()` explicitly: @@ -127,18 +129,17 @@ await weave.init("openai-agents"); await weave.instrumentOpenAIAgents(); ``` -Alternatively, for full control over the tracing processor, create and register one manually: +For full control over the tracing processor, such as for custom processor configuration or conditional registration, create and register one manually: ```typescript import { addTraceProcessor } from "@openai/agents"; import { createOpenAIAgentsTracingProcessor } from "weave"; +... + const processor = createOpenAIAgentsTracingProcessor(); addTraceProcessor(processor); ``` -## View traces - -When the above code sample is run, a link to the Weave dashboard is generated. To see what happened during your agent execution, follow the link to see your agent traces. - \ No newline at end of file + From 8a9d6177d198009594ee7ed6a504faae0325b915 Mon Sep 17 00:00:00 2001 From: anastasiaguspan Date: Wed, 4 Mar 2026 08:32:37 -0500 Subject: [PATCH 3/3] clarifying ESM vs commonJS --- weave/guides/integrations/js.mdx | 56 ++++++++++++++++++--- weave/guides/integrations/openai_agents.mdx | 21 ++++++-- 2 files changed, 66 insertions(+), 11 deletions(-) diff --git a/weave/guides/integrations/js.mdx b/weave/guides/integrations/js.mdx index 278914639c..dbd981545d 100644 --- a/weave/guides/integrations/js.mdx +++ b/weave/guides/integrations/js.mdx @@ -18,11 +18,13 @@ Weave will generally handle this automatically. However, there may be [edge case ## Usage instructions -You can either use CommonJS and ESM. +TypeScript projects can use either the CommonJS or ESM module system. ### CommonJS -For CommonJS, no special configuration is required. Automatic patching works out of the box. Simply install Weave: +For CommonJS projects, no special configuration is required. Automatic patching works out of the box. + +Install Weave: ```bash npm install weave @@ -30,17 +32,59 @@ npm install weave ### ESM -For ESM, use Node's `--import` flag to enable auto-instrumentation. The `weave/instrument` module is available as long as the `weave` package is installed. +For ESM projects, use the Node.js `--import` CLI flag to enable auto-instrumentation. The `weave/instrument` module is available as long as the `weave` package is installed. 1. Install Weave: + ```bash npm install weave ``` -2. Import the `weave/instrument` module: + +1. Compile your TypeScript file. +For an example file `test.ts`, compile it with: + + ```bash + npx tsc + ``` + This assumes your `tsconfig.json` outputs compiled files to a `dist` directory, for example: + + ```json + { + "compilerOptions": { + "rootDir": ".", + "outDir": "dist" + } + } + ``` + After compiling, your file will be available as `dist/test.js`. + +1. Run the compiled file with the Node.js `--import=weave/instrument` flag: + ```bash - node --import=weave/instrument dist/main.js + node --import=weave/instrument dist/test.js ``` +Weave must be installed locally in the project you're running. + +Because ESM loads modules differently than CommonJS, Weave must be loaded before other modules to enable automatic instrumentation. Using the `import` flag ensures Weave is loaded before other modules so it can [patch](/weave/guides/integrations) them. + +### If you're unsure which type of project you have + +If you are running a TypeScript file directly with a tool like: +``` +npx tsx test.ts +``` +your project may still be using ESM depending on your `package.json` configuration. + +To determine if you are using CommonJS or ESM, open your `package.json` and check the `type` field: +``` +"type": "module" +``` +If `type` is `module` then your project uses ESM. +If `type` is `commonjs` or is missing, then your project uses CommonJS. + + + ## Advanced usage and troubleshooting This section covers edge cases and workarounds for when the TypeScript SDK's automatic patching doesn’t work as expected. For example, ESM-only environments, bundler setups like Next.js, or constrained runtime environments may cause unexpected issues. If you're seeing missing traces or integration issues, start here. @@ -60,7 +104,7 @@ export NODE_OPTIONS="--import=weave/instrument" ### Bundler compatibility -Some frameworks and bundlers, such as Next.js, may bundle third-party libraries in ways that break Node’s ability to patch them at runtime. +Some frameworks and bundlers, such as Next.js, may bundle third-party libraries in ways that prevent Node.js from patching them at runtime. If this describes your setup, try the following steps: diff --git a/weave/guides/integrations/openai_agents.mdx b/weave/guides/integrations/openai_agents.mdx index 29b3d1d44a..7b80ef52b0 100644 --- a/weave/guides/integrations/openai_agents.mdx +++ b/weave/guides/integrations/openai_agents.mdx @@ -60,6 +60,7 @@ if __name__ == "__main__": When the above code sample is run, a link to the Weave dashboard is generated. To see what happened during your agent execution, follow the link to see your agent traces. + The [OpenAI Agents Node SDK](https://github.com/openai/openai-node) is a lightweight and powerful framework for building multi-agent workflows. You can use W&B Weave with the OpenAI Agents SDK to trace and monitor your agentic applications in TypeScript. @@ -73,10 +74,15 @@ npm install weave @openai/agents zod ## Get started -To use the OpenAI Agents SDK with Weave, you need to: +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. -- Initialize Weave with your project name. -- Create and run your agents as usual. Weave automatically instruments `@openai/agents` through module loader hooks, so no additional setup is required. +The following code sample assumes an ESM project. If you need help setting up your project or determining which type you are using, see [TypeScript SDK: Third-Party Integration Guide](/weave/guides/integrations/js). In the following code sample, an OpenAI Agent is created and integrated with Weave for traceability. First, update `your-team-name/your-project-name` in the Weave project initialization to real values. A `get_weather` tool is defined that 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 with a sample input (`What's the weather in Tokyo?`) and outputs the final response. @@ -99,7 +105,6 @@ const getWeather = tool({ async function main() { // UPDATE to your project info. await weave.init("your-team-name/your-project-name"); - await weave.instrumentOpenAIAgents(); const agent = new Agent({ name: "Hello world", @@ -120,7 +125,13 @@ main(); ### Manual instrumentation -In most cases, automatic instrumentation handles everything. If you need manual control, for example when using dynamic imports or bundlers that bypass module hooks, you can call `instrumentOpenAIAgents()` explicitly: +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()`: ```typescript import * as weave from "weave";