Python SDK Proxy Helpers

This page explains the Python proxy helper flow in the exact order users usually get stuck on: which API key belongs where, when to initialize the agent, and what sdk.openai() or sdk.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 common mistakes.

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 sdk.openai(client) or sdk.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 sdk.init_agent_sync() or await sdk.init_agent() 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 sdk.openai(...) or sdk.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

Sync
Async

from openai import OpenAI

sdk.init_agent_sync()
trace_id = "session-123"

client = sdk.openai(OpenAI(api_key="YOUR_WHYOPS_API_KEY"))
client.default_headers = {
    **(client.default_headers or {}),
    "X-Trace-ID": trace_id,
    "X-Thread-ID": trace_id,
    "X-External-User-Id": current_user.id,
}

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Where is order 123?"}],
)

from openai import AsyncOpenAI

await sdk.init_agent()
trace_id = "session-123"

client = sdk.openai(AsyncOpenAI(api_key="YOUR_WHYOPS_API_KEY"))
client.default_headers = {
    **(client.default_headers or {}),
    "X-Trace-ID": trace_id,
    "X-Thread-ID": trace_id,
    "X-External-User-Id": current_user.id,
}

completion = await client.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:

client.default_headers = {
    **(client.default_headers or {}),
    "X-Trace-ID": trace_id,
    "X-Thread-ID": trace_id,
    "X-External-User-Id": current_user.id,
}

Anthropic helper

Sync
Async

from anthropic import Anthropic

sdk.init_agent_sync()
trace_id = "session-123"

client = sdk.anthropic(Anthropic(api_key="YOUR_WHYOPS_API_KEY"))
client.default_headers = {
    **(client.default_headers or {}),
    "X-Trace-ID": trace_id,
    "X-Thread-ID": trace_id,
}

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

from anthropic import AsyncAnthropic

await sdk.init_agent()
trace_id = "session-123"

client = sdk.anthropic(AsyncAnthropic(api_key="YOUR_WHYOPS_API_KEY"))
client.default_headers = {
    **(client.default_headers or {}),
    "X-Trace-ID": trace_id,
    "X-Thread-ID": trace_id,
}

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

What the helper changes

# sdk.openai(client) mutates the client in place:
# - base_url -> the WhyOps proxy base URL from the SDK config
# - api_key -> WHYOPS_API_KEY
# - default_headers -> Authorization + X-Agent-Name
#
# sdk.anthropic(client) mutates the client in place:
# - base_url -> the WhyOps proxy base URL from the SDK config
# - api_key -> WHYOPS_API_KEY
# - default_headers -> x-api-key + X-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 agent_name 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

Python 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