The OpenAI Agents SDK uses the Responses API by default. This Gateway only implements POST /openai/v1/chat/completions. Build an AsyncOpenAI client with base_url https://gateway.traccia.ai/openai/v1 and both Traccia headers, then force Chat Completions.

What this Gateway accepts

OpenAI: POST /openai/v1/chat/completions and GET /openai/v1/models, also under /agents/{agent_id}/v1 and /openai/agents/{agent_id}/v1 with the agent ID in the path. 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.

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

Global Client

Official pattern: set_default_openai_client plus set_default_openai_api("chat_completions"). Pass use_for_tracing=False so the Gateway client is not reused for OpenAI tracing export.

python

import os
from openai import AsyncOpenAI
from agents import Agent, Runner, set_default_openai_api, set_default_openai_client

client = AsyncOpenAI(
    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",
    },
)

set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")

agent = Agent(
    name="Assistant",
    instructions="Be concise.",
    model="gpt-4o-mini",
)

result = await Runner.run(agent, "hello")

Per-Agent Model

Equivalent official path: wrap the same client in OpenAIChatCompletionsModel.

python

import os
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel

client = AsyncOpenAI(
    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",
    },
)

agent = Agent(
    name="Assistant",
    instructions="Be concise.",
    model=OpenAIChatCompletionsModel(
        model="gpt-4o-mini",
        openai_client=client,
    ),
)

Responses API 404s

If you only set OPENAI_BASE_URL and leave the default API, the SDK posts to /v1/responses. That is not this Gateway.

Gateway: OpenAI Agents SDK

Headers

Global Client

Per-Agent Model

Next Steps

Gateway Overview

Policies