OpenAI agent ts docs 1934

docs.json

@@ -810,6 +810,7 @@
                     "pages": [
                       "weave/guides/integrations",
                       "weave/guides/integrations/autopatching",
+                      "weave/guides/integrations/js",
                       {
                         "group": "LLM Providers",
                         "pages": [
@@ -829,7 +830,6 @@
                           "weave/guides/integrations/together_ai"
                         ]
                       },
-                      "weave/guides/integrations/local_models",
                       {
                         "group": "Frameworks",
                         "pages": [
@@ -846,16 +846,16 @@
                           "weave/guides/integrations/koog",
                           "weave/guides/integrations/autogen",
                           "weave/guides/integrations/verdict",
-                          "weave/guides/integrations/verifiers",
-                          "weave/guides/integrations/js"
+                          "weave/guides/integrations/verifiers"
                         ]
                       },
                       {
                         "group": "Protocols",
                         "pages": [
                           "weave/guides/integrations/mcp"
                         ]
-                      }
+                      },
+                      "weave/guides/integrations/local_models"
                     ]
                   },
                   {

weave/guides/integrations/js.mdx

@@ -16,30 +16,166 @@ weave.wrapOpenAI(new OpenAI());
 Weave will generally handle this automatically. However, there may be [edge cases](#advanced-usage).
 </Warning>
 
-## Usage instructions
+## Use Weave integrations with your TypeScript project
 
-You can either use CommonJS and ESM.
+TypeScript projects can use either the CommonJS or ESM module system.
 
-### CommonJS 
+### If you're unsure which type of project you have
 
-For CommonJS, no special configuration is required. Automatic patching works out of the box. Simply install Weave:
+If you run a TypeScript file directly with a tool such as:
 
 ```bash
-npm install weave
+npx tsx test.ts
 ```
 
-### ESM 
+the module system may be determined implicitly by your environment. For consistent behavior, we recommend explicitly defining `package.json` and `tsconfig.json` files.
 
-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.
+To determine whether a project uses CommonJS or ESM, check the `type` field in `package.json`:
+
+```json
+"type": "module"
+```
+
+- If `type` is `"module"`, the project uses **ESM**.
+- If the `type` field is missing or set to `"commonjs"`, the project defaults to using **CommonJS**.
+
+### Set up a CommonJS project
+
+For CommonJS projects, automatic instrumentation works without additional configuration.
+
+To configure your project for CommonJS:
+
+1. Create or update your `package.json`:
+
+   ```json
+   {
+     "type": "commonjs"
+   }
+   ```
+
+2. Create a `tsconfig.json` with CommonJS-compatible settings:
+
+   ```json
+   {
+     "compilerOptions": {
+       "module": "CommonJS",
+       "target": "es2022",
+       "rootDir": ".",
+       "outDir": "dist"
+     }
+   }
+   ```
+
+   These settings configure TypeScript to compile for CommonJS:
+
+   - **`module: "CommonJS"`** — Compiles modules to CommonJS format (`require`/`module.exports`).
+     For details on this compiler option, see [TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module).
+
+   - **`target: "es2022"`** *(Recommended)* — Emits modern JavaScript compatible with recent Node.js versions.
+     For details on this compiler option, see [TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target).
+
+   - **`rootDir: "."`** — Treats the directory that contains `tsconfig.json` as the root of your input files. TypeScript uses this with `outDir` to mirror your source folder layout in the output.
+     For details on this compiler option, see [TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir).
+
+   - **`outDir: "dist"`** — Writes emitted JavaScript (and other compiler outputs) into the `dist` folder.
+     For details on this compiler option, see [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).
+
+
+3. Install Weave and any other required libraries:
+
+   ```bash
+   npm install weave
+   ```
+
+4. Compile your TypeScript file.
+
+   For an example file `test.ts`:
+
+   ```bash
+   npx tsc
+   ```
+
+   This compiles the file to `dist/test.js`.
+
+5. Run the compiled file with Node.js:
+
+   ```bash
+   node dist/test.js
+   ```
+
+Because CommonJS uses Node.js's `require` module loader, Weave can automatically instrument supported libraries without requiring the `--import` flag used in ESM projects.
+
+### Set up an ESM project
+
+To use Weave with an ESM TypeScript project, configure your project for Node.js ESM, compile your code, and start Node.js with the `--import` flag so Weave can register its instrumentation before other modules load.
+
+To configure your project for ESM:
+
+1. Create or update your `package.json`:
+
+   ```json
+   {
+     "type": "module"
+   }
+   ```
+
+2. Create a `tsconfig.json` with Node-compatible ESM settings:
+
+   ```json
+   {
+     "compilerOptions": {
+       "module": "nodenext",
+       "moduleResolution": "nodenext",
+       "target": "es2022",
+       "rootDir": ".",
+       "outDir": "dist"
+     }
+   }
+   ```
+
+   These settings configure TypeScript to compile for modern Node.js ESM:
+
+   - **`module: "nodenext"`** — Compiles modules using Node.js ESM semantics.  
+     For details on this compiler option, see [TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module).
+
+   - **`moduleResolution: "nodenext"`** — Ensures module resolution follows Node.js ESM rules.  
+     For details on this compiler option, see [TypeScript - Module Resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution).
+
+   - **`target: "es2022"`** *(Recommended)* — Emits modern JavaScript compatible with recent Node.js versions.  
+     For details on this compiler option, see [TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target).
+
+   - **`rootDir: "."`** — Treats the directory that contains `tsconfig.json` as the root of your input files. TypeScript uses this with `outDir` to mirror your source folder layout in the output.  
+     For details on this compiler option, see [TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir).
+
+   - **`outDir: "dist"`** — Writes emitted JavaScript (and other compiler outputs) into the `dist` folder.  
+     For details on this compiler option, see [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).
+
+3. Install Weave and any other required libraries:
+
+   ```bash
+   npm install weave
+   ```
+
+4. Compile your TypeScript file.
+
+   For an example file `test.ts`:
+
+   ```bash
+   npx tsc
+   ```
+
+   This compiles the file to `dist/test.js`.
+
+5. Run the compiled file with Node.js and preload the Weave instrumentation:
+
+   ```bash
+   node --import=weave/instrument dist/test.js
+   ```
+
+  The `--import` flag ensures the `weave/instrument` module loads before other modules so Weave can automatically instrument supported libraries and integrations.
+
+   Weave must be installed locally in the project you run.
 
-1. Install Weave:
-    ```bash
-    npm install weave
-    ```
-2. Import the `weave/instrument` module:
-    ```bash
-    node --import=weave/instrument dist/main.js
-    ```
 
 ## Advanced usage and troubleshooting
 
@@ -60,7 +196,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:
 

weave/guides/integrations/openai_agents.mdx

@@ -2,9 +2,12 @@
 title: "OpenAI Agents SDK"
 description: "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.
 
-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.
+<Tabs>
+  <Tab title="Python">
 
+The [OpenAI Agents Python SDK](https://github.com/openai/openai-agents-python) is a lightweight and powerful framework for building multi-agent workflows. 
 ## Installation
 
 Install the required dependencies using `pip`: 
@@ -15,13 +18,13 @@ pip install weave openai-agents
 
 ## Get started
 
-To use the OpenAI Agents SDK with Weave, you'll need to:
+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
+- Initialize Weave with your project name.
+- Add the Weave tracing processor to your agents.
+- Create and run your agents as usual.
 
-In the following codes sample, an OpenAI Agent is created and integrated with Weave for traceability. First, a Weave project is initialized and the `WeaveTracingProcessor` is set up to capture execution traces. A `Weather` data model is created to represent 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 asynchronously runs the agent with a sample input (`What's the weather in Tokyo?`) and outputs the final response.
+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.
 
 ```python lines
 from pydantic import BaseModel
@@ -57,4 +60,100 @@ 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. 
+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.
+</Tab>
+
+<Tab title="TypeScript">
+The [OpenAI Agents Node SDK](https://github.com/openai/openai-node) is a lightweight and powerful framework for building multi-agent workflows. 
+
+## Installation
+
+Install the required dependencies using `npm`:
+
+```bash
+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](/weave/guides/integrations/js).
+
+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.
+
+```typescript lines
+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()`:
+
+```typescript lines
+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:
+
+```typescript lines
+import { addTraceProcessor } from "@openai/agents";
+import { createOpenAIAgentsTracingProcessor } from "weave";
+
+...
+
+const processor = createOpenAIAgentsTracingProcessor();
+addTraceProcessor(processor);
+```
+
+</Tab>
+</Tabs>