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 d910c6fe72..7b80ef52b0 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,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. + + + +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); +``` + + +