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

> Learn how to enable and use beta features in the Anthropic Python SDK by passing beta identifiers to the `betas` parameter in your client requests. Get early access to new capabilities.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/messages/messages.py), lines 81-84, the implementation joins your beta identifiers into a comma-separated list:

```python
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:

```python
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:

```python
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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/tools/_beta_runner.py) (lines 349-356) manages the request loop:

```python
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:

```python
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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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.