OpenAI agent ts docs 1934

weave/guides/integrations/js.mdx

@@ -18,29 +18,73 @@ 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
 ```
 
 ### 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:
 

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"
 ---
-
+<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. You can use W&B Weave with the OpenAI Agents SDK to track and monitor your agentic applications.
 
 ## Installation
@@ -58,3 +59,98 @@ 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. 
+</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. 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
+
+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.
+
+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.
+
+```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
+
+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";
+
+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
+import { addTraceProcessor } from "@openai/agents";
+import { createOpenAIAgentsTracingProcessor } from "weave";
+
+...
+
+const processor = createOpenAIAgentsTracingProcessor();
+addTraceProcessor(processor);
+```
+
+</Tab>
+</Tabs>