anthropics / anthropics/claude-agent-sdk-python

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

Đang mở
#845 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Python
Star
8.1k
Fork
1.3k
Merge trung bình
2 ngày 31 phút
Pull request đã merge (30 ngày)
1

Mô tả

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

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.