anthropics / anthropics/claude-agent-sdk-python

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

Aberta
#845 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
8.1k
Forks
1.3k
Merge médio
2d 31min
PRs com merge (30d)
1

Descrição

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

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.