anthropics / anthropics/claude-agent-sdk-python

[FEATURE] Allow opting into additional anthropic-beta headers (e.g. token-efficient-tools-2025-02-19)

未关闭
#845 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
Python
星标
8.1k
派生
1.3k
平均合并
2 天 31 分钟
30 天内合并 PR
1

描述

## 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

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。