TypeScript SDK Proxy Helpers

This page explains the TypeScript proxy helper flow in the exact order users usually get stuck on: which API key belongs where, when to initialize the agent, and what whyops.openai() or whyops.anthropic() actually changes.

Quickstart

Start there first if you have not created and initialized the WhyOps client yet.

Runtime Events

Add runtime tracing after the proxy flow is already working.

Advanced Patterns

Move there for hybrid tracing, self-hosting, prompt caching, and event IDs.

Which API key goes where

Credential	Where it lives	What it is used for
`WHYOPS_API_KEY`	Your app environment	Authenticates agent init, manual events, and the patched provider client talking to WhyOps
`WHYOPS_API_KEY` in the provider client constructor	Your app environment	The simplest constructor value when you are routing through WhyOps and storing the real provider credential in WhyOps
Provider credential in the WhyOps dashboard	WhyOps provider settings	Lets WhyOps authenticate upstream when it forwards the proxied request

After you call whyops.openai(client) or whyops.anthropic(client), the SDK mutates the client in place so outgoing traffic authenticates to WhyOps with WHYOPS_API_KEY and X-Agent-Name.

The recommended order

1. Store the provider credential in WhyOps

Add your OpenAI or Anthropic provider key in the WhyOps dashboard so WhyOps can forward proxied requests upstream.

2. Create and initialize the WhyOps client

Build the WhyOps instance and call await whyops.initAgent() during startup.

3. Create the provider SDK client normally

Construct the OpenAI or Anthropic SDK client using the provider library you already use.

4. Patch the provider client with WhyOps

Call whyops.openai(...) or whyops.anthropic(...) immediately after creating the client.

5. Send requests as usual

Your app code stays the same after patching. The client now routes through WhyOps.

OpenAI helper

import OpenAI from 'openai';
import { whyops } from './whyops';

await whyops.initAgent();
const traceId = 'session-123';

const openai = whyops.openai(
  new OpenAI({ apiKey: process.env.WHYOPS_API_KEY }),
);

openai.defaultHeaders = {
  ...(openai as any).defaultHeaders,
  'X-Trace-ID': traceId,
  'X-Thread-ID': traceId,
};

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Where is order 123?' }],
});

Linking requests to users

To associate proxied requests with your application user IDs, add the X-External-User-Id header:

openai.defaultHeaders = {
  ...(openai as any).defaultHeaders,
  'X-Trace-ID': traceId,
  'X-Thread-ID': traceId,
  'X-External-User-Id': currentUser.id,
};

Anthropic helper

import Anthropic from '@anthropic-ai/sdk';
import { whyops } from './whyops';

await whyops.initAgent();
const traceId = 'session-123';

const anthropic = whyops.anthropic(
  new Anthropic({ apiKey: process.env.WHYOPS_API_KEY }),
);

anthropic.defaultHeaders = {
  ...(anthropic as any).defaultHeaders,
  'X-Trace-ID': traceId,
  'X-Thread-ID': traceId,
};

const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 800,
  messages: [{ role: 'user', content: 'Summarize this incident.' }],
});

What the helper changes

// whyops.openai(client) mutates the client in place:
// - baseURL -> the WhyOps proxy base URL from the SDK config
// - apiKey -> WHYOPS_API_KEY
// - Authorization -> Bearer WHYOPS_API_KEY
// - X-Agent-Name -> your stable agent name
//
// whyops.anthropic(client) mutates the client in place:
// - baseURL -> the WhyOps proxy base URL from the SDK config
// - apiKey -> WHYOPS_API_KEY
// - x-api-key -> WHYOPS_API_KEY
// - X-Agent-Name -> your stable agent name

Why explicit trace headers are recommended

The proxy route checks X-Trace-ID and X-Thread-ID before it falls back to invisible-signature extraction or auto-generated trace IDs. If your workflow includes later tool execution, manual trace() events, or multi-step orchestration, reusing the same explicit trace ID keeps everything on the same thread more reliably.

Common mistakes

Do not change agentName between startup, proxied traffic, and runtime events.
Do not rely only on auto-generated trace IDs if your app later emits manual tool or runtime events. Set X-Trace-ID yourself and reuse it.
Do not keep using the patched client for direct provider traffic; keep a second unpatched client if you need both paths.
Do not skip provider configuration in the WhyOps dashboard and assume the constructor key alone is enough for proxied upstream traffic.
Do not start with runtime events first if your real goal is proxy instrumentation. Get the proxy path working, then layer runtime events on top.

If you are not using the helper

Go to OpenAI Proxy API or Anthropic Proxy API for direct proxy configuration without the published SDK.

Getting Started

SDK Overview

TypeScript SDK

Vercel AI SDK

LangChain JS (Beta)

Python SDK

Go SDK

Direct APIs

UI Features

Core Concepts

Architecture

TypeScript SDK Proxy Helpers

Quickstart

Runtime Events

Advanced Patterns

Which API key goes where

The recommended order

OpenAI helper

Linking requests to users

Anthropic helper

What the helper changes

Why explicit trace headers are recommended

Common mistakes

If you are not using the helper

Quickstart

Runtime Events

Advanced Patterns

​Which API key goes where

​The recommended order

​OpenAI helper

​Linking requests to users

​Anthropic helper

​What the helper changes

​Why explicit trace headers are recommended

​Common mistakes

​If you are not using the helper

Which API key goes where

The recommended order

OpenAI helper

Linking requests to users

Anthropic helper

What the helper changes

Why explicit trace headers are recommended

Common mistakes

If you are not using the helper