The Gateway is a policy enforcement point, not a tracing product. You keep your provider API key. You add two Traccia headers and change the model base_url(or that client's equivalent). Spend Cap and Model Boundary can deny or reshape this call. Get your Traccia API key from app.traccia.ai only.

Not A Tracing Product

Gateway-only traces are one LLM span per completion (model, prompt, completion, tokens, policy). No tools. No nested agent wraps. No session tree. That is nowhere close to an SDK timeline. Use the Gateway to stop or reshape the provider call. Use the SDK when you need to see what the agent did.

SDK, Gateway, Or Both

Start from whether you can install the Traccia SDK on this agent. Policy coverage and trace depth are not the same choice.

Can you install the SDK on this agent? If yes, go to step 2. If no, use Gateway only.
Do you need a full timeline (tools, nested spans, Loop Cap)? If yes, use SDK only with govern. If some LLM calls still leave through a client you cannot wrap, add Gateway for those calls only.
Do not run govern and the Gateway on the same HTTP call. The SDK check wins and the Gateway never sees that request.

Start Here

Can you install the SDK on this agent?

NoClosed-code, a builder, or raw HTTP

Gateway Only

Policy

Spend Cap and Model Boundary on this LLM call. Loop Cap and tool guards do not apply.

Trace

One LLM span. Not close to the SDK.

openai.chat

Yes, wrap every callYou own the agent code

SDK Only

Policy

Spend Cap, Model Boundary, Loop Cap, and tool guards on this run.

Trace

Full timeline: root, nested LLM spans, tools, prompts, completions.

agent.run

├─ llm.chat

├─ tool.refund

└─ llm.chat

Yes, some calls you cannot wrapInstrumented agents plus closed traffic

SDK + Gateway

Policy

SDK governs instrumented runs. Gateway governs the calls it proxies. Not both on the same call.

Trace

SDK timeline plus one Gateway LLM span. Send a W3C traceparent to nest it.

agent.run

├─ llm.chat

openai.chat Gateway

What Applies

Template	Gateway	SDK
Spend Cap	This LLM call	This LLM call
Model Boundary	This LLM call	This LLM call
Loop Cap	Does not apply	Tool calls in this run
Detective (Cost Spike, Tool Storm)	After traces land	After traces land

Closed-code products must let you set a custom OpenAI, Anthropic, or Gemini URL plus extra headers. If there is no URL knob, the Gateway cannot see the traffic.

Platforms

Each page uses that client's real knob names and the exact URL the Gateway implements. The Anthropic URL is not the same on every SDK. OpenAI Chat Completions is not the OpenAI Responses API.

Platform	Knob	Client Base URL
OpenAI SDK	base_url / baseURL + default_headers	`https://gateway.traccia.ai/openai/v1`
Anthropic SDK	base_url / baseURL + default_headers	`https://gateway.traccia.ai/anthropic (no /v1)`
Gemini SDK	http_options.base_url / httpOptions.baseUrl	`https://gateway.traccia.ai/google`
LangChain	ChatOpenAI base_url; ChatAnthropic base_url	`https://gateway.traccia.ai/openai/v1`
LiteLLM	api_base / base_url + extra_headers	`https://gateway.traccia.ai/openai/v1`
Vercel AI SDK	createOpenAI({ baseURL, headers })	`https://gateway.traccia.ai/openai/v1`
LlamaIndex	OpenAI(api_base=, default_headers=)	`https://gateway.traccia.ai/openai/v1`
CrewAI	LLM(base_url=, extra_headers=)	`https://gateway.traccia.ai/openai/v1`
OpenAI Agents SDK	AsyncOpenAI(base_url=) + chat_completions	`https://gateway.traccia.ai/openai/v1`
n8n	OpenAI credential Base URL, or HTTP Request	`https://gateway.traccia.ai/openai/v1`
HTTP	Full URL + headers	`https://gateway.traccia.ai/openai/v1/chat/completions`

What this Gateway accepts

OpenAI: POST /openai/v1/chat/completions and GET /openai/v1/models. Anthropic: POST /anthropic/v1/messages. Gemini Developer API: POST /google/{v1beta|v1}/models/{model}:generateContent and :streamGenerateContent. Embeddings, the OpenAI Responses API, Assistants, Azure OpenAI paths, Vertex AI paths, and Anthropic Batches are not this Gateway. Those requests 404.

These Paths Are Not This Gateway

Azure OpenAI deployment URLs, the OpenAI Responses API (POST /v1/responses), embeddings, Assistants, Realtime, Anthropic Batches, Anthropic /v1/complete, and Vertex AI Gemini (vertexai=True) are not implemented. Those requests 404. The client must also send both Traccia headers. A URL knob alone is not enough.

Headers

Header	Value
X-Traccia-Api-Key	Workspace key from Settings → API Keys
X-Traccia-Agent-Id	Same Agent ID you would pass to init

Keep the provider API key on the client. The Gateway forwards it and does not store it. Missing Traccia key returns 401. Missing agent ID returns 400.

Native SDK Snippets

These match Integrations → Gateway in the app. Framework wrappers (LangChain, LiteLLM, Vercel AI SDK, n8n) have their own pages because their URL rules differ.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://gateway.traccia.ai/openai/v1",
    default_headers={
        "X-Traccia-Api-Key": os.environ["TRACCIA_API_KEY"],
        "X-Traccia-Agent-Id": "billing-bot",
    },
)

What You See In Traces

Gateway-only traffic still writes a trace, including allows with no policy match. Treat that as an enforcement receipt, not observability. It is one LLM span, not an SDK timeline, and it will not grow into one. You will see model, prompt, completion, billed tokens, and policy on that span. You will not see tools or nested agent wraps. Send a W3C traceparent if you already wrap the run with the SDK so the Gateway span nests under it.

Field	Gateway only	SDK
Spans	One LLM span per completion (openai.chat, anthropic.chat, or google.chat)	Root plus nested LLM, tool, and agent spans
Prompt and completion	On that LLM span (redacted, truncated)	On each LLM span (redacted)
Tools and nested spans	Not captured	Captured
Tokens and cost	Provider usage on allow. $0 and 0 tokens on hard deny	Same billed rules
Policy	Stamped on that span	Stamped on the LLM span

Hard deny never bills. The attempted prompt is kept; there is no completion and no billed usage. PDP estimates stay on traccia.policy.estimated_input_tokens and are not usage. Detective or Warn would-have still ran the provider, so cost and tokens stay billed. Gateway traces look thinner than SDK traces because the Gateway only sees this provider call, not the rest of the agent. If you need the SDK timeline, install the SDK. The Gateway will not fill that gap.

Gateway

SDK, Gateway, Or Both

Gateway Only

SDK Only

SDK + Gateway

What Applies

Platforms

Headers

Native SDK Snippets

What You See In Traces

Next Steps

OpenAI SDK

Policies