Route Claude CLI traffic through AI Gateway and Azure

Create an AI Model Provider entity to define your connection and store your authentication credentials:

kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" << 'EOF'
ai_gateway_model_providers:
  - ref: azure-claude
    name: azure-claude
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    type: anthropic
    config:
      auth:
        type: basic
        headers:
          - name: x-api-key
            value: !secret {source: !env AZURE_AI_FOUNDRY_TOKEN}
EOF

ai-quickstart references the AI Gateway created by the quickstart script in the prerequisites above, instead of creating a new one.

The AI Model Provider uses the following settings:

• type: anthropic: Specifies that this provider speaks Anthropic’s native Messages API format. Azure AI Foundry serves Claude models through this same native API, so don’t use type: azure.
• config.auth.headers[0].value: !secret {source: !env AZURE_AI_FOUNDRY_TOKEN}: Loads the API key from your environment at apply time so it is not embedded in the config, and kongctl redacts it in plan and diff output.

Create an AI Model entity to declare which upstream models are available, configure how client requests are routed, and specify which AI Model Provider to use.

Create an AI Policy entity using request transformer to remove extra fields that Azure AI Foundry’s Claude API does not support.

kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" << 'EOF'
ai_gateway_policies:
  - ref: claude-code-compat
    name: claude-code-compat
    display_name: claude-code-compat
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    type: request-transformer-advanced
    enabled: true
    global: false
    config:
      add:
        headers:
          - "anthropic-version:2023-06-01"
      remove:
        headers:
          - anthropic-beta
        querystring:
          - beta
        body:
          - output_config
          - context_management
          - mcp_servers
          - container
          - service_tier
ai_gateway_models:
  - ref: claude-code-azure-sonnet
    display_name: claude-code-azure-sonnet
    name: claude-code-azure-sonnet
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    type: model
    enabled: true
    formats:
      - type: anthropic
    config:
      route:
        paths:
          - /
        model:
          body_param: model
          values:
            - claude-code-azure-sonnet
    capabilities:
       - generate
    policies:
      - !ref claude-code-compat#name
    targets:
      - name: claude-sonnet-4-6
        provider: azure-claude
        config:
          type: anthropic
          upstream_url: !env AZURE_AI_FOUNDRY_UPSTREAM_URL
EOF

The AI Policy uses the following settings:

• type: request-transformer-advanced: Modifies requests before AI Gateway forwards them upstream.
• config.add.headers: Adds the anthropic-version header Azure AI Foundry’s native Anthropic endpoint requires. Claude Code doesn’t send this header itself, and Foundry rejects requests without it with a 400.
• config.remove.headers / config.remove.querystring / config.remove.body: Strips Anthropic-beta-only fields — the anthropic-beta header, beta query string, and body fields like mcp_servers and container — that Claude Code sends but that Azure AI Foundry’s Claude deployment doesn’t support.
• name: claude-code-compat: The identifier you use to attach the policy.
• targets.name:: The name of your own Claude deployment in Azure AI Foundry

Claude Code beta features vary by version and may add other incompatible fields over time. If you still see a 400 error mentioning an unexpected field after applying this Policy, add that field to the appropriate remove list and re-apply.

The AI Model uses the following settings:

• name/display_name: claude-code-azure-sonnet: The identifier you pass to claude --model. Claude Code uses this, not the upstream target name, to select the model.
• formats: [type: anthropic]: Declares that this model accepts requests in Anthropic-compatible format, matching what Claude Code sends natively.
• config.route.paths: [/]: Configures the base path where this model’s routes are accessible.
• capabilities: [generate]: Enables text generation. For a model using the anthropic format, generate creates a /messages endpoint matching Anthropic’s native Messages API, so combined with your base path, clients send requests to /v1/messages.
• policies: Attaches the claude-code-compat policy created in the previous step, so its header and body transformations apply to every request sent through this model.
• targets: Specifies which upstream model to route requests to. provider: azure-claude references the AI Provider created earlier, and name: claude-sonnet-4-6 must match the name of your Claude deployment in Azure AI Foundry.
• targets[0].config.upstream_url: The base Azure AI Foundry endpoint from the prerequisites, ending at /anthropic. AI Gateway appends the rest of the Anthropic Messages API path automatically.

Now, we can start a Claude Code session that points it to the local AI Gateway endpoint:

export ANTHROPIC_BASE_URL=http://localhost:8000/

CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 \
  claude --allowedTools "WebSearch,Read" --model "claude-code-azure-sonnet"

Tell me about the Madrid Skylitzes manuscript.

Claude Code might prompt you approve its web search for answering the question. When you select Yes, Claude will produce a full-length response to your request:

The Madrid Skylitzes is a remarkable 12th-century illuminated Byzantine
manuscript that represents one of the most important surviving examples
of medieval historical documentation. Here are the key details:

What it is

The Madrid Skylitzes is the only surviving illustrated manuscript of John
Skylitzes' "Synopsis of Histories" (Σύνοψις Ἱστοριῶν), which chronicles
Byzantine history from 811 to 1057 CE - covering the period from the death
of Emperor Nicephorus I to the deposition of Michael VI.

Artistic Significance

- 574 miniature paintings (with about 100 lost over time)
- Lavishly decorated with gold leaf, vibrant pigments, and intricate
detailing
- Depicts everything from imperial coronations and battles to daily life
in Byzantium
- The only surviving Byzantine illuminated chronicle written in Greek

Unique Collaboration

The manuscript is believed to be the work of 7 different artists from
various backgrounds:
- 4 Italian artists
- 1 English or French artist
- 2 Byzantine artists