How to Enable and Use Beta Features in the Anthropic Python SDK

To enable beta features in the Anthropic Python SDK, pass a list of beta identifiers to the betas parameter of any client.beta.* method, which automatically injects the anthropic-beta HTTP header into your API requests.

The Anthropic Python SDK provides early access to preview functionality through a dedicated beta namespace. Whether you are testing structured outputs, web search, or new tool-use capabilities, knowing how to properly enable and use beta features in the Anthropic Python SDK allows you to experiment with cutting-edge API capabilities before they reach general availability.

Understanding Beta Feature Architecture

The SDK segregates stable and experimental functionality under the client.beta namespace. When you invoke methods within this namespace, the SDK constructs HTTP requests that include special headers identifying which preview features your application supports.

The Beta Namespace

All beta-specific methods reside under client.beta, such as client.beta.messages.create(). This architectural separation ensures that production code using stable endpoints remains unaffected while allowing developers to opt into experimental behavior.

Header Injection Mechanism

The SDK automatically constructs the anthropic-beta header from the betas argument you provide. In src/anthropic/resources/beta/messages/messages.py, lines 81-84, the implementation joins your beta identifiers into a comma-separated list:

extra_headers = {
    **strip_not_given({
        "anthropic-beta": ",".join(str(e) for e in betas)
        if is_given(betas) else not_given
    }),
    **(extra_headers or {}),
}

This header is then transmitted with every request to the Anthropic API, signaling the server to enable specific preview behaviors.

Methods to Enable Beta Features

You can enable beta functionality at three granularities: per-call, client-wide, or through automated tool runners.

Per-Call Opt-In

Pass the betas list directly to individual method calls when you want to enable preview features for specific requests only. This approach provides the safest migration path for testing:

from anthropic import Anthropic

client = Anthropic()

response = client.beta.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Give me a JSON summary of the weather."}],
    betas=["structured-outputs-2025-12-15"],
)

print(response)

Client-Level Default Headers

For applications requiring consistent beta access across multiple calls, configure default headers during client initialization. This eliminates the need to specify betas on every invocation:

from anthropic import Anthropic

client = Anthropic(default_headers={"anthropic-beta": "web-search-2025-10-01"})

resp = client.beta.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Search the web for the latest AI news."}],
)

Beta Tools and Automation

The SDK provides specialized decorators and runners for beta tool-use features. The @beta_tool decorator, defined in src/anthropic/lib/tools/_beta.py, automatically generates JSON schemas from Python function signatures, while the tool_runner in src/anthropic/lib/tools/_beta_runner.py (lines 349-356) manages the request loop:

import json
from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool
def get_weather(location: str) -> str:
    """Return mock weather data for a city."""
    return json.dumps({
        "location": location,
        "temperature": "68°F",
        "condition": "Sunny",
    })

runner = client.beta.messages.tool_runner(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    tools=[get_weather],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

for msg in runner:
    print(msg)

You can combine beta flags with the tool runner to access structured output formats:

runner = client.beta.messages.tool_runner(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    betas=["structured-outputs-2025-12-15"],
    tools=[get_weather],
    messages=[{"role": "user", "content": "Give me a JSON weather report for London."}],
)

for msg in runner:
    print(msg.parsed)

How Beta Features Work Under the Hood

When you invoke a beta method, the SDK executes a specific request flow. First, it builds the payload using the maybe_transform helper. Next, it injects the anthropic-beta header either from your per-call betas argument or the client's default headers. The underlying httpx client transmits the request, and the SDK parses the response into beta-specific models such as BetaMessage or ParsedBetaMessage located under anthropic.types.beta.

Summary

• Access all beta methods through the client.beta namespace to isolate experimental functionality from stable endpoints.
• Enable specific preview features by passing a list of identifiers to the betas parameter, which the SDK converts into the anthropic-beta HTTP header in src/anthropic/resources/beta/messages/messages.py.
• Set permanent beta access via default_headers during client initialization for applications requiring consistent preview feature usage.
• Leverage the @beta_tool decorator and tool_runner helper in src/anthropic/lib/tools/_beta_runner.py to automate tool definitions and execution loops with beta features enabled.

Frequently Asked Questions

How do I know which beta identifiers are available for the Anthropic SDK?

Anthropic announces available beta programs through official documentation and release notes. Each beta feature, such as "structured-outputs-2025-12-15" or "web-search-2025-10-01", has a specific string identifier that you must pass exactly as documented to the betas parameter.

Can I use multiple beta features simultaneously in a single request?

Yes, the SDK supports enabling multiple beta features by passing a list of identifiers to the betas argument. The header injection code in src/anthropic/resources/beta/messages/messages.py concatenates these into a comma-separated string, allowing the API server to activate multiple preview capabilities concurrently.

What is the difference between @beta_tool and the standard tool decorators?

The @beta_tool decorator, implemented in src/anthropic/lib/tools/_beta.py, specifically targets preview tool-use APIs that may have different schemas or behaviors than stable releases. It introspects function signatures to generate compatible JSON schemas while the tool_runner manages the interaction loop, automatically feeding results back to the model as implemented in src/anthropic/lib/tools/_beta_runner.py.

Will beta features become breaking changes in future SDK versions?

Beta features are subject to change or removal as they mature toward general availability. Code using client.beta methods and beta-specific headers should be considered experimental. Monitor the anthropics/anthropic-sdk-python repository for migration guides when preview features transition to stable releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}