anthropics / anthropics/claude-agent-sdk-python
[FEATURE] Add context_management (clear_thinking + clear_tool_uses) as first-class ClaudeAgentOptions parameter
- 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ả
## Feature Request
### Problem
The Anthropic Messages API supports a `context_management` parameter (beta `context-management-2025-06-27`) that enables two server-side context editing strategies:
1. **`clear_thinking_20251015`** — manages thinking blocks (keep all, keep N turns, or use default)
2. **`clear_tool_uses_20250919`** — clears stale tool use/result pairs when input tokens exceed a threshold
These are distinct from the server-side compaction feature (`compact-2026-01-12`, covered by #570). Where compaction summarizes and replaces the entire conversation, `context_management` edits selectively prune specific content types while preserving the rest of the conversation intact.
Currently, `ClaudeAgentOptions` has no parameter for `context_management`, so SDK users cannot configure these strategies.
### Relationship to Existing Issues
- **#443** requests configurable `clear_thinking` — this issue expands that to the full `context_management` config including `clear_tool_uses`
- **#570** requests `context_management.edits` support for the compaction beta — this issue covers the separate `context-management-2025-06-27` beta for selective content editing
### Requested Behavior
Add a `context_management` parameter to `ClaudeAgentOptions` that accepts the full `context_management` JSON config and passes it through to the Messages API. Example:
```python
options = ClaudeAgentOptions(
model="claude-sonnet-4-20250514",
max_thinking_tokens=16000,
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{"type": "clear_thinking_20251015", "keep": "all"},
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 100000},
"keep": {"type": "tool_uses", "value": 5},
"clear_at_least": {"type": "input_tokens", "value": 10000}
}
]
}
)
```
### Use Case
We run an agentic worker system where each task involves 50+ tool calls (Read, Grep, Glob, Bash, Edit, Write). We use Opus-class models with extended thinking enabled, and our architecture is append-only (prompts grow monotonically until compaction).
Without `context_management`:
- Stale tool results (file reads from early in the session) accumulate 50K–100K tokens of context that is no longer relevant
- Default `clear_thinking` behavior (keep last 1 turn) causes KV-cache misses when thinking blocks are cleared, forcing expensive cache re-creation
- Our only option is wholesale compaction at 80% context, which loses all conversation history
With `context_management`:
- `clear_thinking` with `keep: "all"` would maximize KV-cache hits across our long sessions (estimated 20–40% cost reduction on cache-eligible turns)
- `clear_tool_uses` would selectively reclaim 30K–70K tokens per session by clearing stale tool results while keeping the 5 most recent
- This defers compaction, maintaining coherent conversation history for longer and improving task completion quality
### Implementation Notes
Since the SDK wraps the Claude CLI, this likely requires:
1. Adding `context_management` to `ClaudeAgentOptions`
2. Passing it through as a CLI argument or environment variable to the underlying `claude` process
3. The CLI itself would need to forward it to the Messages API
Alternatively, if `extra_args` could support complex JSON config passthrough, that would be a viable interim solution.
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á.