Anthropic Python SDK

The Anthropic Python SDK takes a base_url on the client constructor, so pointing it at an LLM Registry entry needs no wrapper and no proxy configuration. It can also send custom headers, which is how the Agent Access Key travels when an entry requires one.

All three credential modes below are verified working against an Anthropic entry.

Setup

Pick the credential mode your entry runs in. You'll find it on the entry's Provider Credential panel.

API Key

The gateway stores the Anthropic credential, so no Anthropic key leaves your machine. api_key carries your Agent Access Key instead.

import anthropic

client = anthropic.Anthropic(
    base_url="https://<gateway-host>/llm/<url-prefix>",
    api_key="<your-agent-access-key>"
)

response = client.messages.create(
    model="<model-id>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

The SDK sends api_key as x-api-key, which the gateway accepts as your credential on this mode. It then attaches the stored Anthropic credential on the outbound side.

Passthrough (Agent Access Key Required)

Two credentials travel on every call, in two separate places: your own Anthropic key in api_key, and the Agent Access Key in a custom header.

import anthropic

client = anthropic.Anthropic(
    base_url="https://<gateway-host>/llm/<url-prefix>",
    api_key="<your-anthropic-api-key>",
    default_headers={"X-Agent-Key": "<your-agent-access-key>"}
)

response = client.messages.create(
    model="<model-id>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

What each argument does:

• api_key carries your own Anthropic key, which the gateway forwards to Anthropic unchanged.
• default_headers carries the Agent Access Key on X-Agent-Key, which identifies you to the gateway. It applies to every request the client makes.
• max_tokens is required by Anthropic's Messages API. The SDK supplies no default.

note

To set the header per call rather than per client, client.messages.create(..., extra_headers={"X-Agent-Key": "<your-agent-access-key>"}) works the same way. Use default_headers when every call goes through the gateway, which is the usual case.

Without a custom header

If setting a header is awkward in your setup, both credentials can travel in api_key instead, combined provider key first and separated by two colons:

client = anthropic.Anthropic(
    base_url="https://<gateway-host>/llm/<url-prefix>",
    api_key="<your-anthropic-api-key>::<your-agent-access-key>"
)

The gateway splits the value apart before authenticating, exactly as it does for clients with only one credential field. The header form above is clearer when you have the choice, since each credential stays in its own place.

Passthrough (No Agent Access Key)

With Require an agent access key off, only your Anthropic key travels and no headers are needed.

import anthropic

client = anthropic.Anthropic(
    base_url="https://<gateway-host>/llm/<url-prefix>",
    api_key="<your-anthropic-api-key>"
)

response = client.messages.create(
    model="<model-id>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

print(response)

Troubleshooting

anthropic.AuthenticationError: missing API key

The gateway received no Agent Access Key on an entry that requires one. It looks for the key in the X-Agent-Key header and nowhere else on a passthrough entry, so this error means default_headers is absent, misspelled, or carrying an empty value.

It does not mean your Anthropic key is wrong. That key is never examined when the Agent Access Key is missing, so the error names the credential that actually failed rather than the one that didn't.

Where to find each value

Placeholder	Where to find it
<gateway-host>	Host from the entry's Overview tab, for example gw.aigateway.example.com
<url-prefix>	The URL prefix field on the entry's Overview tab
<model-id>	A model identifier from the entry's Allowed Models list, for example claude-opus-4-8
<your-agent-access-key>	Generate from the entry's Agent Access Keys step. Plaintext is shown once.
<your-anthropic-api-key>	Your own Anthropic API key, needed only in the passthrough modes

Tips

• Keep credentials out of your source. The snippets inline the values so the shape is clear, but read them from environment variables or a secret store in anything you commit.
• base_url takes no suffix. Paste the entry's endpoint exactly as the Overview tab shows it. The SDK appends /v1/messages itself.
• max_tokens is not optional. Anthropic rejects a Messages API call without it, whether or not the gateway is in the path.
• Working in a different SDK? There are sibling guides for the OpenAI Python SDK and the Google Gen AI Python SDK.