OpenAI agent ts docs 1934 by anastasiaguspan · Pull Request #2210 · wandb/docs

anastasiaguspan · 2026-03-02T21:41:06Z

Description

Documentation for TypeScript SDK: OpenAI agents Integration

I have tested this 'getting started' code example but it does require 'await weave.instrumentOpenAIAgents();' to work.

if that's accurate, Proposing we remove these lines under Section "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:

import * as weave from "weave";

await weave.init("openai-agents");
await weave.instrumentOpenAIAgents();

Testing

[ x] Local build succeeds without errors (mint dev)
[ ]x Local link check succeeds without errors (mint broken-links)
PR tests succeed

Related issues

Fixes DOCS-1934

github-actions · 2026-03-02T21:44:43Z

📚 Mintlify Preview Links

🔗 View Full Preview

📝 Changed (3 total)

📄 Pages (2)

File	Preview
`weave/guides/integrations/js.mdx`	Js
`weave/guides/integrations/openai_agents.mdx`	Openai Agents

⚙️ Other (1)

File
`docs.json`

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: 3cffb64 at 2026-03-19 17:42:12 UTC

github-actions · 2026-03-02T21:45:01Z

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Checked against: https://wb-21fd5541-openai-agent-ts-docs-1934.mintlify.app

chance-wnb

Thank you so much Anastasia. Overall this looks great! 👍 I thought about some minor details. Can you help me verify a few things please?

weave/guides/integrations/js.mdx

chance-wnb · 2026-03-06T18:26:21Z

weave/guides/integrations/openai_agents.mdx

+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";


in the CommonJS way, since we are not relying on pre-loader, if we move import * as weave from "weave"; after import { Agent, run, tool } from "@openai/agents"; (which means the import of @openai/agents runs first), does it still work I wonder?

If it doesn't, and for some reason users are unable to put import * as weave from "weave"; first. We can suggest them to manually patch in such a situtation.

If it still works, then we are good!

in cjs, we don't use import, so assuming for cjs you meant
const weave = require("weave");
const { Agent, run, tool } = require("@openai/agents");

changed to
const { Agent, run, tool } = require("@openai/agents");
const weave = require("weave");

no, it didn't work.
So i will call this ordering out specifically, good catch. Tho calling this out might be a little confusing since the import code is different from the example, i'll see what I can do
(just to be sure i did test this for the esm version and it was fine)

I see. what I said earlier is confusing, let me clarify: regardless of whether it is CJS or ESM, people always write it as:

import * as weave from "weave"; import { Agent, run, tool } from "@openai/agents";

as TypeScript. This looks identical like ESM, but it is TypeScript :) It just happens that TypeScript uses the modern ESM syntax.

Eventually, under CJS config, it will be configured to:

const weave = require("weave"); const { Agent, run, tool } = require("@openai/agents");

…tup, clarified import ordering for CommonJS agent integration

chance-wnb · 2026-03-12T21:52:25Z

weave/guides/integrations/openai_agents.mdx

+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";


I see. what I said earlier is confusing, let me clarify: regardless of whether it is CJS or ESM, people always write it as:

import * as weave from "weave"; import { Agent, run, tool } from "@openai/agents";

as TypeScript. This looks identical like ESM, but it is TypeScript :) It just happens that TypeScript uses the modern ESM syntax.

Eventually, under CJS config, it will be configured to:

const weave = require("weave"); const { Agent, run, tool } = require("@openai/agents");

chance-wnb · 2026-03-12T21:54:43Z

weave/guides/integrations/openai_agents.mdx

+
+The example code on this page uses ESM syntax. In CommonJS projects, the equivalent import statement is:
+```typescript lines
+const weave = require("weave");


so here maybe you also want to mention the typescript syntax as well:

import * as weave from "weave"; import { Agent, run, tool } from "@openai/agents";

and with CommonJS configuration, the order of that two import statements(which will be translated to require() in compiled code) matters.

chance-wnb

Thank you so much for the due diligence and attention to every detail! It is much appreciated. Great job!

chance-wnb · 2026-03-13T16:28:33Z

weave/guides/integrations/js.mdx

+   - **`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).
+
+   - **`verbatimModuleSyntax: false`** — Allows ESM-style `import`/`export` syntax in source files while emitting CommonJS output.


nit: in my opinion, this doesn't seem to be a commonly-seen option. with its default value being false, we probably don't need to mention it. So the simpler the user's config is, the better.

Since tsconfig is such a huge topic, our doc is not the go-to place for every details, as long as we bring something basic that works, we already fulfill our limited liability :)

Just my two cents, and it is a nit-picky comment. I will leave it to your decision.

…ter as a FAQ instead.

dbrian57

Hey, I'm approving because I know this is blocking other things, but I do think this needs a little rework. Please feel free to hit me up for another review if you have time or want to discuss some of the feedback.

I'm mostly concerned about the step summarization stuff and the suggested ESM vs Common section.

weave/guides/integrations/js.mdx

dbrian57 · 2026-03-19T14:22:42Z

weave/guides/integrations/js.mdx

-For CommonJS, no special configuration is required. Automatic patching works out of the box. Simply install Weave:
+For CommonJS projects, automatic instrumentation works out of the box.
+
+1. Configure your project for CommonJS.


I feel like we need some introduction to what we're doing, either here or in the intro sentence. This kinda just jumps into the procedure without telling the user what they're about to do.

My suggestion would be:

Suggested change

1. Configure your project for CommonJS.

To configure your Weave project for CommonJS:

1. Create or update your `package.json` file and set its `type` field to `commonjs`:

And then nix the next line

weave/guides/integrations/js.mdx

dbrian57 · 2026-03-19T14:42:06Z

weave/guides/integrations/js.mdx

+     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).


I would err on the side of caution and define the other two fields, as well.

dbrian57 · 2026-03-19T14:47:20Z

weave/guides/integrations/js.mdx

+   For an example file `test.ts`:
+
+   ```bash
+   npx tsc


Is this command correct? It doesn't target a file.

weave/guides/integrations/js.mdx

dbrian57 · 2026-03-19T16:01:58Z

weave/guides/integrations/openai_agents.mdx

+</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.


I think we should put this description outside of the tabs, as there is little difference between the TS and Python versions. Also, the Python version incorrectly uses "track" instead of "trace"

weave/guides/integrations/openai_agents.mdx

dbrian57 · 2026-03-19T16:14:00Z

weave/guides/integrations/openai_agents.mdx

+
+Manual instrumentation is only needed in cases where the module loader hook cannot run, such as:
+
+- bundlers that bundle dependencies into a single file


I think all of these should start with capitalization? https://developers.google.com/style/lists#introductory-sentences-for-lists

dbrian57 · 2026-03-19T16:17:36Z

weave/guides/integrations/js.mdx


-You can either use CommonJS and ESM.
+TypeScript projects can use either the CommonJS or ESM module system.



Should we include information here about when you should be using one over the other?

Co-authored-by: Dan Brian <daniel.brian@gmail.com>

anastasiaguspan added 2 commits March 2, 2026 10:35

first draft

3074fdd

draft

c814eb2

anastasiaguspan requested a review from a team as a code owner March 2, 2026 21:41

anastasiaguspan requested a review from chance-wnb March 2, 2026 21:43

mintlify bot deployed to staging March 2, 2026 21:43 View deployment

clarifying ESM vs commonJS

8a9d617

mintlify bot deployed to staging March 4, 2026 13:33 View deployment

chance-wnb reviewed Mar 6, 2026

View reviewed changes

updates based on eng review. strengthened instructions for project se…

6e7e95e

…tup, clarified import ordering for CommonJS agent integration

mintlify bot deployed to staging March 12, 2026 20:50 View deployment

Merge branch 'main' into openai-agent-ts-docs-1934

55405d5

mintlify bot deployed to staging March 12, 2026 20:55 View deployment

chance-wnb reviewed Mar 12, 2026

View reviewed changes

fixing commonJS build to be consistent with ESM

1ea8ac5

mintlify bot deployed to staging March 13, 2026 14:27 View deployment

chance-wnb approved these changes Mar 13, 2026

View reviewed changes

removing the verbatim setting since it defaults to false, will add la…

17d5798

…ter as a FAQ instead.

mintlify bot deployed to staging March 13, 2026 17:52 View deployment

dbrian57 approved these changes Mar 19, 2026

View reviewed changes

Update weave/guides/integrations/js.mdx

db5f15d

Co-authored-by: Dan Brian <daniel.brian@gmail.com>

mintlify bot deployed to staging March 19, 2026 17:39 View deployment

anastasiaguspan and others added 2 commits March 19, 2026 13:40

Update weave/guides/integrations/js.mdx

4e3325a

Co-authored-by: Dan Brian <daniel.brian@gmail.com>

Update weave/guides/integrations/js.mdx

3cffb64

Co-authored-by: Dan Brian <daniel.brian@gmail.com>

mintlify bot deployed to staging March 19, 2026 17:41 View deployment

Update weave/guides/integrations/openai_agents.mdx

76de132

Co-authored-by: Dan Brian <daniel.brian@gmail.com>

-. Configure your project for CommonJS.
+To configure your Weave project for CommonJS:
+. Create or update your `package.json` file and set its `type` field to `commonjs`:


		Manual instrumentation is only needed in cases where the module loader hook cannot run, such as:

		- bundlers that bundle dependencies into a single file


		You can either use CommonJS and ESM.
		TypeScript projects can use either the CommonJS or ESM module system.

Conversation

anastasiaguspan commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

Related issues

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Mintlify Preview Links

📝 Changed (3 total)

📄 Pages (2)

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Link Checker Results

Uh oh!

chance-wnb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chance-wnb Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chance-wnb Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chance-wnb Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chance-wnb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dbrian57 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anastasiaguspan commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

chance-wnb Mar 6, 2026 •

edited

Loading

chance-wnb Mar 12, 2026 •

edited

Loading

chance-wnb Mar 12, 2026 •

edited

Loading