anthropics / anthropics/claude-agent-sdk-python

[FEATURE] Add context_management (clear_thinking + clear_tool_uses) as first-class ClaudeAgentOptions parameter

Đang mở
#581 3 bình luận 3 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ả

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

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.