anthropics / anthropics/claude-agent-sdk-python
[FEATURE] Allow opting into additional anthropic-beta headers (e.g. token-efficient-tools-2025-02-19)
- Dominant language
- Python
- Stars
- 8.1k
- Forks
- 1.3k
- Avg merge
- 2d 31m
- Merged PRs (30d)
- 1
Description
## Summary
`ClaudeAgentOptions.betas` is typed as `list[SdkBeta]` where
`SdkBeta = Literal["context-1m-2025-08-07"]`, so the SDK currently
rejects any other beta flag. This blocks opting into Anthropic beta
features that ship only as HTTP headers, such as
`token-efficient-tools-2025-02-19`.
Enabling that header reduces output tokens on tool-use workloads by
up to ~14% (per the Anthropic token-efficient tools announcement),
which is material for agent systems that make many tool calls per turn.
## Current behavior (SDK 0.1.61)
```python
from claude_agent_sdk import ClaudeAgentOptions
# types.py
# SdkBeta = Literal["context-1m-2025-08-07"]
ClaudeAgentOptions(betas=["token-efficient-tools-2025-02-19"]) # type error
```
`extra_args: dict[str, str | None]` passes CLI flags to the bundled
Claude CLI, not HTTP headers, so it is not a workaround.
## Proposal
One of:
1. **Loosen `SdkBeta`** to `Literal["context-1m-2025-08-07", ...] | str`
and pass unknown values through as `anthropic-beta` header entries.
2. **Add `extra_headers: dict[str, str]`** to `ClaudeAgentOptions` that
the SDK forwards to `anthropic.Anthropic` (or the Bedrock/Vertex
equivalents), so users can set `{"anthropic-beta": "token-efficient-tools-2025-02-19"}`
explicitly.
Option 2 is more general and would also unblock the use cases in
related issues (e.g. #626 cache-control injection on Bedrock).
## Use case
In a multi-agent system with ~13 specialist agents, each turn can make
5-20 tool calls. Reducing output tokens 10-14% per tool-use turn is a
meaningful cost saving. Opt-in via header is the documented Anthropic
surface; we just need the SDK to let it through.
## Environment
- `claude-agent-sdk==0.1.61` (also reproduces on 0.1.63)
- Python 3.12
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.