Python Anthropic: per-run additional_beta_flags leaks into request kwargs

[rg-ve]

Description

agent-framework-anthropic leaks per-run additional_beta_flags into the raw Anthropic request kwargs.

Passing additional_beta_flags per run is consumed by _prepare_betas(...), but the key remains in the final request kwargs and causes:

TypeError: AsyncMessages.create() got an unexpected keyword argument 'additional_beta_flags'

Workaround: set beta flags on the AnthropicClient constructor instead of per-run options.

Environment

• Repo: microsoft/agent-framework
• Local commit tested: 4ad96b64e755f5d25d5b859e1c7b43b64088a56f
• Python packages installed editable from local repo:
  • python/packages/core
  • python/packages/anthropic
• agent-framework-core: 1.3.0
• agent-framework-anthropic: 1.0.0b260507
• anthropic: 0.80.0
• Python: 3.14
• Model tested: claude-opus-4-7

Minimal repro

import asyncio
import os
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.anthropic import AnthropicClient

@tool(approval_mode="never_require")
def lookup_ticket(ticket_id: Annotated[str, "Ticket id"]) -> str:
    """Look up a test ticket."""
    return '{"ticket_id":"40076","status":"open","priority":"high"}'

async def main():
    client = AnthropicClient(
        api_key=os.environ["ANTHROPIC_API_KEY"],
        model="claude-opus-4-7",
    )

    agent = Agent(
        client=client,
        name="AnthropicOptionsRepro",
        instructions="Use lookup_ticket exactly once for ticket 40076, then summarize it.",
        tools=[lookup_ticket],
        default_options={
            "model": "claude-opus-4-7",
            "max_tokens": 4096,
            "thinking": {"type": "adaptive", "display": "omitted"},
            "output_config": {"effort": "low"},
            "additional_beta_flags": ["extended-cache-ttl-2025-04-11"],
            "tools": [lookup_ticket],
        },
    )

    async for chunk in agent.run("Validate ticket 40076 now.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)

asyncio.run(main())

Expected: additional_beta_flags should be consumed into betas only.

Actual: it is also forwarded as a raw kwarg to AsyncMessages.create(...), which rejects it.

Root cause

From agent_framework_anthropic/_chat_client.py:

• _prepare_options(...) copies all options except instructions and response_format into run_options.
• _prepare_betas(...) consumes additional_beta_flags into betas.
• additional_beta_flags is not removed from run_options before calling AsyncMessages.create(...).

Compatibility note: Opus 4.7 thinking shape

With additional_beta_flags moved to the AnthropicClient constructor as a workaround, a live streaming local-tool loop succeeds with:

thinking={"type": "adaptive", "display": "omitted"}
output_config={"effort": "low"}

This is the expected Opus 4.7 API shape. thinking={"type":"enabled","budget_tokens":...} is expected to return a 400 on Opus 4.7 and is not being reported as a bug here.

There is a separate type/doc freshness gap: agent_framework_anthropic._chat_client.ThinkingConfig currently documents only enabled / disabled plus budget_tokens, while Opus 4.7 uses adaptive thinking. The runtime pass-through works, so this is documentation/typing freshness rather than the runtime failure above.

Expected fix

Pop/filter additional_beta_flags from run_options after consuming it into betas, before dispatching to Anthropic.

[rg-ve]

Additional data point after filing:

I reran the same repro against claude-opus-4-7.

Results:

• thinking={"type":"adaptive","display":"omitted"} + output_config={"effort":"low"}: passes for Opus 4.7. The streaming tool loop calls the local function and returns the tool result.
• thinking omitted entirely: passes for Opus 4.7.
• thinking={"type":"enabled","budget_tokens":1024}: fails for Opus 4.7 with:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

So the adaptive omitted replay failure I reported appears with claude-sonnet-4-6, while Opus 4.7 requires the adaptive/output_config shape and handles this particular tool-loop repro correctly.

The separate additional_beta_flags issue still reproduces in the request-shape path: _prepare_options() consumes it into betas but leaves additional_beta_flags in the final raw Anthropic kwargs if passed per-run. In my live runs I worked around that by setting beta flags on the AnthropicClient constructor.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: AnthropicClient._prepare_options() in python/packages/anthropic/agent_framework_anthropic/_chat_client.py copies all options into run_options (line 582-583) and calls _prepare_betas() (line 619) which reads additional_beta_flags, but never pops the key from run_options. When run_options is unpacked into AsyncMessages.create(**run_options) at lines 542/551, the unexpected kwarg causes TypeError. Fix: add run_options.pop("additional_beta_flags", None) after line 619, similar to the existing pop of allow_multiple_tool_calls at line 586.

• Failing test: python/packages/anthropic/tests/test_beta_flags_leak_5764.py
• Files examined: python/packages/anthropic/agent_framework_anthropic/_chat_client.py, python/packages/anthropic/tests/test_anthropic_client.py, python/packages/anthropic/pyproject.toml
• Tests run: python/packages/anthropic/tests/test_beta_flags_leak_5764.py
• Reported version: 1.0.0b260507
• Current version: 1.0.0b260507