Gateway

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.

1. Can you install the SDK on this agent? If yes, go to step 2. If no, use Gateway only.
2. 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.
3. Do not run govern and the Gateway on the same HTTP call. The SDK check wins and the Gateway never sees that request.

What Applies

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.

Headers

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. For OpenAI-compatible clients that allow only one extra header, such as n8n, put the agent ID in the URL instead: https://gateway.traccia.ai/agents/<agent-id>/v1. If both are set, the header wins.

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.

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",
    },
)

When Traccia Can't Be Reached

Before each call the Gateway asks Traccia whether it may go ahead. If Traccia does not answer (a timeout, a connection error, a 5xx, or a reply the Gateway cannot use), the Gateway follows your setting: Block calls (the default) or Allow calls. Choose it in the app under Settings → Policy Enforcement: an organization default, and optionally a different choice per workspace, for example allow in development and block in production. Each call follows the setting of the workspace its Traccia API key belongs to.

Every Gateway error carries X-Traccia-Error-Code (policy_unavailable for the 503). The body is in your provider's error format: OpenAI also has code: policy_unavailable, Anthropic has type: api_error, and Gemini has status: UNAVAILABLE. Retry after Retry-After seconds.

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.

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.