Skip to content

fix(openai-agents-ts): support @openai/agents up to 0.21 and add real-SDK compatibility test - #285

Merged
nik13 merged 3 commits into
devfrom
fix/ts-openai-agents-peer-range
Oct 26, 2026
Merged

nik13 merged 3 commits into
devfrom
fix/ts-openai-agents-peer-range

Conversation

@nik13

@nik13 nik13 commented Oct 25, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Makes @traceai/openai-agents installable and correct on current @openai/agents releases, makes its hide flags and setTracerProvider() work, and adds a compatibility test that runs the real SDK.

  • Peer range ^0.4.0 -> >=0.4.0 <0.22.0. npm install @traceai/openai-agents @openai/agents@0.21.0 (the current release) fails today with ERESOLVE. The require hook uses the same range, and the range is exported as SUPPORTED_AGENTS_VERSIONS.
  • Span data. The processor read camelCase fields (toAgent, modelConfig, usage.inputTokens, input/response) that the SDK never emits. Every release from 0.4 to 0.21 uses snake_case (to_agent/from_agent, model_config, usage.input_tokens, response spans' _input/_response). Because of that, these were all missing: handoff names, graph.node.parent_id, invocation parameters, token counts, and response/root input and output. Response spans now carry the model and token counts. Generation spans carry the output text and fall back to the Chat Completions usage block.
  • exclusiveProcessor option. The default true keeps today's setTraceProcessors behaviour, which replaces the SDK's OpenAI exporter. false uses addTraceProcessor and keeps it. This matches exclusive_processor in the Python package.
  • ESM entry point. exports["."].import / module pointed at dist/esm/index.js, but the build wrote dist/esm/src/index.js with extensionless imports, so import "@traceai/openai-agents" failed. The ESM and ESNext tsconfigs now use rootDir: "src" and the shared ESM base config, like the other packages.
  • manuallyInstrument() no longer throws on an ES module namespace (import * as agents from "@openai/agents").
  • Hide flags and setTracerProvider(). traceConfig and FI_HIDE_INPUTS / FI_HIDE_OUTPUTS had no effect. InstrumentationBase calls enable() from its constructor, before the subclass stores traceConfig, so the FITracer was built with undefined, and fi-core then returns its defaults without reading the environment. That FITracer also kept the tracer it was created with, so a provider passed to setTracerProvider() afterwards (the README order) was ignored and spans went to the global provider. The tracer is now rebuilt once the config is stored and again when the module is patched. The tracer always gets an options object, so the environment variables are read.
  • Version 0.2.0, a new package CHANGELOG.md and README.md (supported versions, quick start, exporter behaviour, captured spans, hide flags).

Why?

The package could not be installed next to any @openai/agents release after 0.4.x. Even on 0.4.x it dropped handoffs, model settings, token usage and response input/output, because it read the wrong field names. A working package with reproducible compatibility evidence is also what the openai-agents-js tracing-processors list asks for before it links an integration.

How was it tested?

  • Unit tests added / updated (jest; this package uses jest, not vitest)

  • Integration tests pass (or N/A — no gateway behavior changed)

  • ruff check / mypy / npm run typecheck / npm run lint all pass. Type checking passes through pnpm run build and ts-jest. npm run lint cannot run on main (see Notes).

  • Public types, env vars, or SDK behavior changes are documented in the relevant README

  • New src/__tests__/realSdk.test.ts runs a two-agent workflow (tool call, then a handoff, then the answer) through the real Runner and OpenAI models against an in-process fake OpenAI server on 127.0.0.1, so it needs no API key and no network. It covers both the Responses API (response spans) and Chat Completions (generation spans). It asserts span names, parent links, the tool and handoff spans, model, invocation parameters and token counts, and that spans flush on shutdown.

    • Three more tests build the instrumentation in the README order (construct, setTracerProvider(), manuallyInstrument()). They check that spans reach that provider, and that traceConfig and FI_HIDE_* replace input.value / output.value with __REDACTED__. All three fail without the third commit.
    • All 6 tests pass against @openai/agents 0.4.15, 0.11.8, 0.16.1 and 0.21.0.
    • The processor from main fails 2 of the first 3 tests.
  • pnpm test in the package: 2 suites, 24 tests passed.

  • The packed tarball was also run end to end with the README quick start, against a local fake OpenAI server and a local OTLP receiver. The receiver got 5 spans on /tracer/v1/traces with project_name, and with FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true input.value and output.value arrived as __REDACTED__.

  • pnpm run build (CJS, ESM and ESNext) passes.

  • pnpm pack, then a fresh npm install <tgz> @openai/agents@0.21.0 in an empty directory: no ERESOLVE. Both require("@traceai/openai-agents") and import ... from "@traceai/openai-agents" load.

  • pnpm install --frozen-lockfile passes with pnpm 10.30.1 (the pinned packageManager).

Checklist

  • Branch is off dev
  • Commit messages follow Conventional Commits (feat:, fix:, docs:, chore: …)
  • No TODOs or commented-out code left in
  • No real API keys or secrets in the diff
  • If prose was added or changed: checked against docs/VOCABULARY.md (the file does not exist in the repo)

Notes for reviewers

  • Lockfile. @openai/agents 0.21.0 is now a devDependency, so pnpm-lock.yaml moves from @openai/agents 0.4.15 to 0.21.0 (with openai 7.x). pnpm also dedupes the ws peer from 8.21.0 to 8.22.0 across the workspace, which accounts for most of the 450-line lockfile diff. It was regenerated once from main's lockfile; the commits apply cleanly onto dev and pnpm install --frozen-lockfile passes there.
  • No direct zod dependency. The test tool uses a plain JSON schema with strict: true, so the package does not add zod as a devDependency.
  • Upper bound. The range stops at <0.22.0, the last version the test ran on. The SDK ships a minor release every 1-3 weeks, so bump the bound together with the test whenever it does.
  • Hide flags and raw bodies. Even after this PR, @traceai/fi-core 1.0.0 still exports raw.input / raw.output (the request and response bodies) when hiding is on. This predates the PR. The fix is in feat(typescript): hide error details with the content hide flags #271 (fi-core 1.1.0), and the README says so. Merge and release feat(typescript): hide error details with the content hide flags #271 before advertising the hide flags for this package.
  • Jest warning. Jest sometimes prints "A worker process has failed to exit gracefully" when both suites run in parallel workers on a loaded machine (2 of about 8 runs). --detectOpenHandles finds nothing. The cause is the SDK's own BatchTraceProcessor timers (a 500 ms flush wait that is not unref'd, and a shutdown that keeps the loop alive). The tests still pass.
  • Lint. npm run lint (eslint . --ext .ts) cannot run on main: the repo has no ESLint config, and ESLint 9+ needs eslint.config.*. TypeScript type checking ran through the build and ts-jest.
  • After merge, publish @traceai/openai-agents@0.2.0 to npm (npm has only 0.1.0).

Verified on dev (2026-10-25): pnpm --filter "@traceai/openai-agents..." run build passed (49 s) and pnpm --filter @traceai/openai-agents test passed: 2 suites, 24 tests, including realSdk.test.ts against the real @openai/agents 0.21 SDK (55 s).

🤖 Generated with Claude Code

nik13 and others added 3 commits October 25, 2026 13:26
…oints

exports["."].import and "module" point at dist/esm/index.js, but the ESM
and ESNext builds inherited rootDir "." and wrote dist/esm/src/index.js
with extensionless relative imports, so `import "@traceai/openai-agents"`
failed with ERR_MODULE_NOT_FOUND (published 0.1.0 has the same layout).
Use rootDir "src" and the shared ESM/ESNext base configs, as
traceai_openai and the other packages do; tsc-alias then adds the .js
extensions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… SDK's real span data

- Peer range ^0.4.0 -> >=0.4.0 <0.22.0 (npm install with @openai/agents
  0.21.0 failed with ERESOLVE); the require hook uses the same range.
- The processor read camelCase fields (toAgent, modelConfig,
  usage.inputTokens, input/response) that the SDK never emits. Every
  release from 0.4 to 0.21 uses snake_case (to_agent/from_agent,
  model_config, usage.input_tokens, response spans' _input/_response),
  so handoff names and graph.node.parent_id, invocation parameters,
  token counts and response/root input and output were all missing.
- Response spans now carry model and token counts; generation spans
  carry output text and fall back to the Chat Completions usage block.
- exclusiveProcessor option (default true keeps today's
  setTraceProcessors behaviour; false uses addTraceProcessor and keeps
  the SDK's OpenAI exporter), like exclusive_processor in Python.
- manuallyInstrument() no longer throws on an ES module namespace.
- realSdk.test.ts: real Runner + OpenAI models against an in-process
  fake OpenAI server (Responses and Chat Completions), asserting the
  span tree and flush on shutdown. Passes on 0.4.15, 0.11.8, 0.16.1 and
  0.21.0; the old processor fails it.
- Version 0.2.0, new package CHANGELOG.md and README.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…TracerProvider()

InstrumentationBase calls enable() from its constructor, before the
subclass stores traceConfig, so the FITracer was always built with
traceConfig undefined. fi-core returns its defaults for undefined
without reading FI_HIDE_INPUTS / FI_HIDE_OUTPUTS, so neither the option
nor the environment variables redacted anything.

The FITracer also kept the tracer it got at that point. A provider set
with setTracerProvider() afterwards (the order the README shows) was
ignored unless enable() ran again, and spans went to the global
provider instead.

Build the FITracer again once the config is stored and when the module
is patched, and always pass an options object so fi-core reads the
environment. Three new real-SDK tests cover the README order,
traceConfig redaction and FI_HIDE_* redaction; all three fail without
this change. raw.input / raw.output are still exported by fi-core 1.0.0
(fixed in #271); the README says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nik13
nik13 merged commit ffec227 into dev Oct 26, 2026
4 checks passed
@nik13
nik13 deleted the fix/ts-openai-agents-peer-range branch October 26, 2026 00:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant