Capability Matrix

The xmAI gateway routes requests across multiple provider families. Each channel declares the capabilities it supports. When a request requires a capability that the target channel cannot represent, the gateway either drops it gracefully or rejects the request with a 400 error, and signals what happened via the X-Gateway-Degraded response header.

Capability Overview

Adapter	server_tool_web_search	extended_thinking	cache_control_block_level	anthropic-beta header
openai	No	No	No	Stripped
azure-openai	No	No	No	Stripped
anthropic	Yes	Yes	Yes	Passed through
bedrock	Yes	Yes	Yes	AWS whitelist filtered
vertex	No	Yes	Yes	Passed through
google	No	No	No	Stripped

What Are These Capabilities?

All three boolean capabilities are Anthropic-native protocol features, specific to the /v1/messages API. They only apply when a client sends a request using the Anthropic protocol — the OpenAI /v1/chat/completions endpoint has no equivalent concepts and is not affected by capability filtering.

Capability	Anthropic Protocol Feature	Trigger in Request Body
server_tool_web_search	Server-side web search tool	tools: [{type: "web_search_20250305"}]
extended_thinking	Extended chain-of-thought reasoning	thinking: {type: "enabled"}
cache_control_block_level	Block-level prompt caching	messages[].content[].cache_control or system[].cache_control

When the gateway routes a request from the Anthropic protocol entry (/v1/messages) to a non-Anthropic upstream (e.g., OpenAI, Google), these features cannot be represented and are silently dropped. The X-Gateway-Degraded header tells the client exactly what was lost.

How anthropic-beta Headers Work

Anthropic's API uses the anthropic-beta HTTP request header to opt in to experimental features:

POST /v1/messages
anthropic-beta: web-search-2025-03-05,prompt-caching-scope-2026-01-05

Each beta value unlocks a specific feature. The gateway handles this header differently depending on the channel's upstream provider:

Adapter	anthropic-beta Handling
anthropic (direct)	Passed through to the Anthropic API as-is
bedrock	Only beta values on the AWS allowlist (AWS_ALLOWED_ANTHROPIC_BETA) are forwarded; others are stripped
vertex	Forwarded to the Vertex Anthropic endpoint (limited beta support)
openai / azure-openai / google	Ignored — beta headers are meaningless for non-Anthropic providers

Beta filtering is fully automatic — no admin configuration required. The gateway handles it at runtime based on the adapter type. There is no anthropic_beta_supported field in the admin UI.

TIP

Clients do not need to worry about which betas a channel supports. Simply include the anthropic-beta header as you would with the Anthropic API directly. The gateway will forward supported betas and silently strip unsupported ones.

Capability Field Details

• server_tool_web_search: Anthropic-native web search tool. Only anthropic and bedrock can represent this natively. Vertex AI does not expose this tool in its Anthropic-compatible endpoint.
• extended_thinking: Streaming budget tokens / extended reasoning. Supported by anthropic, bedrock, and vertex.
• cache_control_block_level: Block-level cache_control prompt caching. Supported by anthropic, bedrock, and vertex.
• anthropic_beta_supported: Declares which anthropic-beta header values the channel can forward to the upstream. Bedrock requires the model to be on Anthropic's Converse API allowlist for beta features; the Invoke API path does not support them.

X-Gateway-Degraded Response Header

When the gateway drops a capability during cross-family translation, it sets the X-Gateway-Degraded response header. Multiple values are comma-separated.

Header Value	Reason
server_tool_web_search_dropped	target_family_cannot_represent_anthropic_native_web_search
extended_thinking_dropped	target_family_cannot_represent_extended_thinking
prompt_caching_dropped	target_family_cannot_represent_block_level_cache_control
server_tool_web_search_unavailable	no_channel_declares_capability_for_model — returns HTTP 400

Example

HTTP/1.1 200 OK
X-Gateway-Degraded: server_tool_web_search_dropped, prompt_caching_dropped

This means the request included a web search tool and block-level cache_control, but the selected channel could not represent either. Both were silently dropped and the request was forwarded without them.

Degradation Handling on the Client Side

Detecting degradation

Check for the header in every response when your request includes advanced Anthropic features:

const response = await fetch('/v1/messages', { method: 'POST', body: JSON.stringify(payload) })
const degraded = response.headers.get('X-Gateway-Degraded')
if (degraded) {
  const dropped = degraded.split(',').map(s => s.trim())
  console.warn('Gateway degraded capabilities:', dropped)
}

Retry strategy

If your application requires a specific capability, you should:

1. Check the header on every response that involves advanced features.
2. Do not retry blindly — if server_tool_web_search_unavailable is returned as a 400, there is no channel available for that model that declares web search support. Retrying will produce the same result.
3. For soft drops (*_dropped values), consider routing the request to a different model or notifying the user that the feature was unavailable.

UI hints

Present degradation to end users in plain language. Examples:

Degraded value	Suggested user message
server_tool_web_search_dropped	"Web search was not available for the selected model. The response was generated without it."
extended_thinking_dropped	"Extended thinking mode was not available for the selected model and was skipped."
prompt_caching_dropped	"Prompt caching was not applied. Latency and cost may be higher than expected."

Admin Configuration

Capabilities are declared per-channel in the admin dashboard under Channels → Edit → Capabilities.

Capability flags

Flag	Description
server_tool_web_search	Enable if the upstream endpoint supports Anthropic's native web search tool
extended_thinking	Enable if the upstream endpoint supports budget_tokens / extended reasoning
cache_control_block_level	Enable if the upstream endpoint supports block-level cache_control

Example: Bedrock channel

For a Bedrock channel using Anthropic models via the Converse API:

• Enable server_tool_web_search, extended_thinking, and cache_control_block_level.
• Ensure the target model is on Anthropic's Converse API beta allowlist before enabling anthropic_beta_supported.
• Bedrock's Invoke API path does not support beta headers — only use Invoke channels for non-beta workloads.

Cross-family pitfalls

Scenario	Pitfall
Routing an Anthropic request to an OpenAI channel	All three capabilities will be dropped. X-Gateway-Degraded will list all three if they were requested.
Bedrock Invoke vs. Converse	Invoke does not support anthropic-beta. Declare capabilities accordingly and use separate channels for each path.
Vertex web search	Vertex does not expose server_tool_web_search. Do not enable that capability on Vertex channels.
Google (Gemini native)	None of the three capabilities are supported. Web search on Gemini uses a different mechanism not covered by this matrix.

Known Limitations

• Vertex AI: server_tool_web_search is not supported, even for Anthropic-family models routed through Vertex. Do not enable this capability on Vertex channels.
• Bedrock anthropic_beta: Beta features require Anthropic's explicit model allowlist on the Converse API. Contact Anthropic or your AWS account team to request access.
• Silent drops vs. hard errors: The gateway only returns a 400 for server_tool_web_search_unavailable (no capable channel found). All other degradations are silent drops accompanied by the X-Gateway-Degraded header. Your application must opt in to checking this header.
• No partial caching: If cache_control_block_level is dropped, none of the cache_control hints in the request are applied. There is no fallback to session-level caching.