anthropics / anthropics/claude-agent-sdk-python

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

Ouverte
#845 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Python
Étoiles
8.1k
Forks
1.3k
Merge moyen
2 j 31 min
PR mergées (30 j)
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

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.