Skip to main content

Documentation Index

Fetch the complete documentation index at: https://whyops.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

CredentialWhere it livesWhat it is used for
WHYOPS_API_KEYYour app environmentAuthenticates agent init, manual events, and the patched provider client talking to WhyOps
WHYOPS_API_KEY in the provider client constructorYour app environmentThe simplest constructor value when you are routing through WhyOps and storing the real provider credential in WhyOps
Provider credential in the WhyOps dashboardWhyOps provider settingsLets 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.
1

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

2. Create and initialize the WhyOps client

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

3. Create the provider SDK client normally

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

4. Patch the provider client with WhyOps

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

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