Filtering Anthropic Beta Headers
Anthropic clients such as Claude Code send every beta feature they use as one comma-separated anthropic-beta header. Claude on AWS Bedrock and GCP Vertex AI rejects the whole request with a 400 if any single value is unsupported, and which values are supported differs by provider and by model. headerValueFilters on an AIServiceBackend removes individual values from that header before the request reaches the backend, so one unsupported value does not fail the request.
Filter Modes
Each filter names a header and a mode:
Allowlistforwards only the listed values and drops everything else. A new beta value is dropped until you add it, so requests keep working but the feature it gates stays off.Denylist(the default) drops only the listed values and forwards everything else. A new beta value reaches the backend without a config change, but if the backend rejects it, requests fail until you add it to the list.
Example
apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIServiceBackend
metadata:
name: my-bedrock-claude
spec:
schema:
name: AWSAnthropic
backendRef:
name: my-bedrock-backend
kind: Backend
group: gateway.envoyproxy.io
headerValueFilters:
- name: anthropic-beta
mode: Allowlist
values:
- context-1m-2025-08-07
- interleaved-thinking-2025-05-14
- tool-search-tool-2025-10-19
anthropic-beta-filters.yaml has complete examples with full value lists, with an Allowlist and a Denylist for both AWS Bedrock (AWSAnthropic) and GCP Vertex AI (GCPAnthropic). The AWS Allowlist matches the built-in list.
Things to Know When Writing a Filter
- Only
GCPAnthropicandAWSAnthropicbackends honorheaderValueFilters, only for theanthropic-betaheader, and only on/v1/messagesrequests. Setting it on a backend with any other schema is rejected. - On
AWSAnthropic, values are matched after Anthropic-API-only names are rewritten to their Bedrock names, so list the Bedrock name. For example,advanced-tool-use-2025-11-20is rewritten totool-search-tool-2025-10-19before the filter runs, so a filter entry foradvanced-tool-use-2025-11-20never matches. - On
AWSAnthropic, a backend without ananthropic-betafilter falls back to a built-in list of values known to be accepted by Bedrock. This fallback is deprecated and will be removed in a future release. Once you configure a filter, the built-in list no longer applies, so aDenylistmust cover every value your clients send that Bedrock rejects. To keep the current behavior, use theAllowlistfrom the AWS example above. GCPAnthropichas no built-in list. Without a filter, every value is forwarded to Vertex AI unchanged.- An empty
valueslist leaves the header unchanged. OnAWSAnthropicit still counts as a configured filter, so it also turns off the built-in list.