Редактирование контекста
Автоматически управляйте контекстом разговора по мере его роста с помощью редактирования контекста.
Обзор
«Context editing» (редактирование контекста) позволяет выборочно очищать определённое содержимое из истории разговора по мере её роста. Помимо оптимизации затрат и соблюдения ограничений, речь идёт об активном отборе того, что получает Claude: контекст — это ограниченный ресурс с убывающей отдачей, а нерелевантное содержимое снижает сосредоточенность модели. Редактирование контекста даёт вам детальный контроль над этим отбором во время выполнения. Общие принципы управления контекстом описаны в статье Эффективная инженерия контекста. На этой странице рассматриваются:
- Очистка результатов инструментов: лучше всего подходит для агентных рабочих процессов с интенсивным использованием инструментов, где старые результаты инструментов больше не нужны
- Очистка блоков размышлений: для управления блоками размышлений из предыдущих ходов с возможностью сохранить недавние размышления для непрерывности контекста
- Клиентское сжатие в SDK: альтернатива на основе SDK для управления контекстом с помощью резюме (обычно предпочтительнее серверное сжатие)
| Подход | Где выполняется | Стратегии | Как это работает |
|---|---|---|---|
| На стороне сервера | API | Очистка результатов инструментов (clear_tool_uses_20250919)Очистка блоков размышлений ( clear_thinking_20251015) | Применяется до того, как подсказка достигнет Claude. Очищает определённое содержимое из истории разговора. Каждую стратегию можно настраивать независимо. |
| На стороне клиента | SDK | Сжатие | Доступно в SDK для TypeScript и Ruby при использовании tool_runner. Генерирует резюме и заменяет им полную историю разговора. См. Клиентское сжатие. |
Стратегии на стороне сервера
Очистка результатов инструментов
Стратегия clear_tool_uses_20250919 очищает результаты инструментов, когда контекст разговора превышает настроенный вами порог. Это особенно полезно для агентных рабочих процессов с интенсивным использованием инструментов. Более старые результаты инструментов (например, содержимое файлов или результаты поиска) больше не нужны после того, как Claude их обработал.
При активации API автоматически очищает самые старые результаты инструментов в хронологическом порядке. API заменяет каждый очищенный результат текстом-заполнителем, указывающим Claude, что он был удалён. По умолчанию очищаются только результаты инструментов. При желании вы можете очищать как результаты инструментов, так и вызовы инструментов (параметры использования инструментов), установив для clear_tool_inputs значение true.
Очистка блоков размышлений
Стратегия clear_thinking_20251015 управляет блоками thinking из предыдущих ходов ассистента. Эта стратегия даёт вам контроль над сохранением размышлений: вы можете сохранять больше блоков размышлений для поддержания непрерывности рассуждений или очищать их более агрессивно, чтобы сэкономить место в контексте.
Ход ассистента в разговоре может включать несколько блоков содержимого (например, при использовании инструментов) и несколько блоков размышлений (например, при чередующихся размышлениях).
Редактирование контекста выполняется на стороне сервера
Редактирование контекста применяется на стороне сервера до того, как подсказка достигнет Claude. Ваше клиентское приложение сохраняет полную, неизменённую историю разговора. Вам не нужно синхронизировать состояние клиента с отредактированной версией. Продолжайте управлять полной историей разговора локально, как обычно.
В моделях с сохранёнными размышлениями управление контекстом на стороне сервера никогда не делает недействительными блоки размышлений. Изменения более ранних ходов на стороне клиента могут сделать недействительными блоки размышлений во всех последующих ходах ассистента. См. Что должно оставаться неизменным и почему.
Модели с функцией «preserved thinking» (Сохранённые размышления) — это Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 и Claude Haiku 5.5.
Редактирование контекста и кэширование подсказок
Взаимодействие редактирования контекста с кэшированием подсказок («prompt caching») зависит от стратегии:
-
Очистка результатов инструментов: делает недействительными кэшированные префиксы подсказок при очистке содержимого. Чтобы учесть это, очищайте достаточно токенов, чтобы инвалидация кэша была оправданной. Используйте параметр
clear_at_least, чтобы гарантировать очистку минимального количества токенов каждый раз. Вы будете нести затраты на запись в кэш при каждой очистке содержимого, но последующие запросы смогут повторно использовать новый кэшированный префикс. -
Очистка блоков размышлений: когда блоки размышлений сохраняются в контексте (не очищаются), кэш подсказок сохраняется, что обеспечивает попадания в кэш и снижает затраты на входные токены. Когда блоки размышлений очищаются, кэш становится недействительным с той точки, где происходит очистка. Настройте параметр
keepв зависимости от того, что для вас приоритетнее: производительность кэша или доступный объём «context window» (контекстного окна).
Поддерживаемые модели
Редактирование контекста доступно во всех поддерживаемых моделях Claude.
Использование очистки результатов инструментов
Один из способов включить очистку результатов инструментов — указать только тип стратегии. Все остальные параметры конфигурации используют значения по умолчанию:
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Search for recent developments in AI"}],
tools=[{"type": "web_search_20250305", "name": "web_search"}],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)Расширенная конфигурация
Вы можете настроить поведение очистки результатов инструментов с помощью дополнительных параметров:
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Create a simple command line calculator app using Python",
}
],
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000,
},
{"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
# Запускать очистку при превышении порога
"trigger": {"type": "input_tokens", "value": 30000},
# Количество использований инструментов, сохраняемых после очистки
"keep": {"type": "tool_uses", "value": 3},
# Необязательно: очищать не менее указанного числа токенов
"clear_at_least": {"type": "input_tokens", "value": 5000},
# Исключить эти инструменты из очистки
"exclude_tools": ["web_search"],
}
]
},
)Использование очистки блоков размышлений
Используйте очистку блоков размышлений для управления контекстом и кэшированием подсказок в разговорах, которые содержат блоки размышлений из предыдущих ходов:
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Hello"}],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
}
]
},
)Параметры конфигурации для очистки блоков размышлений
Стратегия clear_thinking_20251015 поддерживает следующую конфигурацию:
| Параметр конфигурации | По умолчанию | Описание |
|---|---|---|
keep | {type: "thinking_turns", value: 1} | Определяет, сколько последних ходов ассистента сохраняют свои блоки размышлений. Используйте {type: "thinking_turns", value: N}, где N должно быть > 0, чтобы сохранить последние N ходов, или "all", чтобы сохранить все блоки размышлений. |
Запрос, который включает эту стратегию без keep, получает {type: "thinking_turns", value: 1} на любой модели, включая модели, чьё значение по умолчанию для конкретной модели сохраняет все размышления. Запрос без этой стратегии получает значение по умолчанию для конкретной модели.
N учитывает текущий ход ассистента и ходы без блоков размышлений. Сообщение пользователя, содержащее только блоки tool_result, продолжает текущий ход. Любое другое сообщение пользователя начинает новый ход. Когда запрос заканчивается сообщением, начинающим новый ход, значение 1 очищает размышления из всех предыдущих ходов ассистента.
Примеры конфигураций:
Сохранять блоки размышлений из последних 3 ходов ассистента с учётом текущего хода:
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Hello"}],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 3},
}
]
},
)Сохранять все блоки размышлений (максимизирует попадания в кэш):
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Hello"}],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": "all",
}
]
},
)Комбинирование стратегий
Вы можете использовать очистку блоков размышлений и очистку результатов инструментов вместе:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
messages=[
{
"role": "user",
"content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
}
],
tools=[
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
}
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_thinking_20251015",
"keep": {"type": "thinking_turns", "value": 2},
},
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 50000},
"keep": {"type": "tool_uses", "value": 5},
},
]
},
)
print(response)Параметры конфигурации для очистки результатов инструментов
| Параметр конфигурации | По умолчанию | Описание |
|---|---|---|
trigger | 100 000 входных токенов | Определяет, когда активируется стратегия редактирования контекста. Как только подсказка превышает этот порог, начинается очистка. Это значение можно указать в input_tokens или в tool_uses. |
keep | 3 использования инструментов | Определяет, сколько последних пар использование инструмента/результат сохранять после очистки. API сначала удаляет самые старые взаимодействия с инструментами, сохраняя самые последние. |
clear_at_least | Нет | Гарантирует очистку минимального количества токенов при каждой активации стратегии. Если API не может очистить хотя бы указанное количество, стратегия не будет применена. Это помогает определить, стоит ли очистка контекста нарушения вашего кэша подсказок. |
exclude_tools | Нет | Список имён инструментов, чьи использования и результаты никогда не должны очищаться. Полезно для сохранения важного контекста. |
clear_tool_inputs | false | Управляет тем, очищаются ли параметры вызова инструмента вместе с результатами инструмента. По умолчанию очищаются только результаты инструментов, а исходные вызовы инструментов Claude остаются видимыми. |
Ответ редактирования контекста
Вы можете увидеть, какие правки контекста были применены к вашему запросу, с помощью поля ответа context_management, а также полезную статистику об очищенном содержимом и входных токенах.
{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"content": [
// ...
],
"usage": {
// ...
},
"context_management": {
"applied_edits": [
// When using `clear_thinking_20251015`
{
"type": "clear_thinking_20251015",
"cleared_thinking_turns": 3,
"cleared_input_tokens": 15000
},
// When using `clear_tool_uses_20250919`
{
"type": "clear_tool_uses_20250919",
"cleared_tool_uses": 8,
"cleared_input_tokens": 50000
}
]
}
}Для ответов с потоковой передачей правки контекста включаются в финальное событие message_delta:
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"stop_sequence": null
},
"usage": {
"output_tokens": 1024
},
"context_management": {
"applied_edits": [
// ...
]
}
}Подсчёт токенов
Конечная точка подсчёта токенов поддерживает управление контекстом, позволяя вам заранее увидеть, сколько токенов будет использовать ваша подсказка после применения редактирования контекста.
response = client.beta.messages.count_tokens(
model="claude-opus-5-5",
messages=[{"role": "user", "content": "Continue our conversation..."}],
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 30000},
"keep": {"type": "tool_uses", "value": 5},
}
]
},
)
print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
){
"input_tokens": 25000,
"context_management": {
"original_input_tokens": 70000
}
}В ответе показано как итоговое количество токенов после применения управления контекстом (input_tokens), так и исходное количество токенов до какой-либо очистки (original_input_tokens).
Использование с инструментом памяти
Редактирование контекста можно комбинировать с инструментом памяти. Когда контекст разговора приближается к настроенному порогу очистки, Claude получает автоматическое предупреждение о необходимости сохранить важную информацию. Это позволяет Claude сохранить результаты инструментов или контекст в свои файлы памяти до того, как они будут очищены из истории разговора.
Эта комбинация позволяет вам:
- Сохранять важный контекст: Claude может записать существенную информацию из результатов инструментов в файлы памяти до того, как эти результаты будут очищены.
- Поддерживать длительные рабочие процессы: Claude может продолжать агентные рабочие процессы, которые иначе превысили бы ограничения контекста, выгружая информацию в постоянное хранилище.
- Получать доступ к информации по требованию: Claude может при необходимости найти ранее очищенную информацию в файлах памяти, вместо того чтобы держать всё в активном контекстном окне.
Например, в рабочем процессе редактирования файлов, где Claude выполняет множество операций, Claude может резюмировать выполненные изменения в файлы памяти по мере роста контекста. Когда результаты инструментов очищаются, Claude сохраняет доступ к этой информации через свою систему памяти и может продолжать эффективно работать.
Чтобы использовать обе функции вместе, включите их в вашем запросе к API:
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Hello"}],
tools=[{"type": "memory_20250818", "name": "memory"}],
betas=["context-management-2025-06-27"],
context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)Полный справочник по инструменту памяти, включая команды и примеры, см. в разделе Инструмент памяти.
Клиентское сжатие (SDK)
«Compaction» (сжатие) — это функция SDK, которая автоматически управляет контекстом разговора, генерируя резюме, когда использование токенов становится слишком большим. В отличие от стратегий редактирования контекста на стороне сервера, которые очищают содержимое, сжатие поручает Claude резюмировать историю разговора, а затем заменяет полную историю этим резюме. Это позволяет Claude продолжать работу над длительными задачами, которые иначе превысили бы контекстное окно.
Как работает сжатие
Когда сжатие включено, SDK отслеживает использование токенов после каждого ответа модели:
- Проверка порога: SDK вычисляет общее количество токенов как
input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens(поля токенов кэша см. в разделе Кэширование подсказок). - Генерация резюме: когда порог превышен, подсказка для резюме вставляется как ход пользователя, и Claude генерирует структурированное резюме, обёрнутое в теги
<summary></summary>. - Замена контекста: SDK извлекает резюме и заменяет им всю историю сообщений.
- Продолжение: разговор возобновляется с резюме, и Claude продолжает с того места, где остановился.
Использование сжатия
Добавьте compaction_control в ваш вызов tool_runner, чтобы включить автоматическое резюмирование, когда использование токенов превышает порог.
Что происходит во время сжатия
По мере роста разговора история сообщений накапливается:
До сжатия (приближение к 100 тыс. токенов):
[
{ "role": "user", "content": "Analyze all files and write a report..." },
{ "role": "assistant", "content": "I'll help. Let me start by reading..." },
{
"role": "user",
"content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
},
{ "role": "assistant", "content": "Based on file1.txt, I see..." },
{
"role": "user",
"content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
},
{ "role": "assistant", "content": "After analyzing file2.txt..." }
// ... 50 more exchanges like this ...
]Когда количество токенов превышает порог, SDK вставляет запрос на резюме, и Claude генерирует резюме. Затем вся история заменяется:
После сжатия (снова ~2–3 тыс. токенов):
[
{
"role": "assistant",
"content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
}
]Claude продолжает работу с этого резюме, как если бы это была исходная история разговора.
Параметры конфигурации
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
enabled | boolean | Да | - | Включать ли автоматическое сжатие |
context_token_threshold | number | Нет | 100 000 | Количество токенов, при котором срабатывает сжатие |
model | string | Нет | Та же, что и основная модель | Модель, используемая для генерации резюме |
summary_prompt | string | Нет | См. Подсказка для резюме по умолчанию | Пользовательская подсказка для генерации резюме |
Выбор порога токенов
Порог определяет, когда происходит сжатие. Более низкий порог означает более частое сжатие с меньшими контекстными окнами. Более высокий порог допускает больше контекста, но создаёт риск достижения лимитов.
Использование другой модели для резюме
Вы можете использовать более быструю или дешёвую модель для генерации резюме:
Пользовательские подсказки для резюме
Вы можете предоставить пользовательскую подсказку для предметно-ориентированных нужд. Ваша подсказка должна поручать Claude обернуть резюме в теги <summary></summary>.
Подсказка для резюме по умолчанию
Встроенная подсказка для резюме поручает Claude создать структурированное резюме для продолжения, включающее:
- Обзор задачи: основной запрос пользователя, критерии успеха и ограничения.
- Текущее состояние: что выполнено, какие файлы изменены и какие артефакты созданы.
- Важные открытия: технические ограничения, принятые решения, устранённые ошибки и неудачные подходы.
- Следующие шаги: конкретные необходимые действия, блокирующие факторы и порядок приоритетов.
- Контекст для сохранения: предпочтения пользователя, предметно-ориентированные детали и взятые обязательства.
Такая структура позволяет Claude эффективно возобновить работу, не теряя важного контекста и не повторяя ошибок.
You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:
1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified
2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced
3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)
4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain
5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user
Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.
Wrap your summary in <summary></summary> tags.Ограничения
Инструменты на стороне сервера
При использовании инструментов на стороне сервера SDK может неправильно рассчитывать использование токенов, из-за чего сжатие запускается в неподходящий момент.
Например, после операции веб-поиска ответ API может показать:
{
"usage": {
"input_tokens": 63000,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 270000,
"output_tokens": 1400
}
}SDK вычисляет общее использование как 63 000 + 0 + 270 000 + 1 400 = 334 400 токенов. Однако значение cache_read_input_tokens включает накопленные чтения из множества внутренних вызовов API, выполненных инструментом на стороне сервера, а не ваш фактический контекст разговора. Реальная длина вашего контекста может составлять всего 63 000 input_tokens, но SDK вычисляет 334 тыс. и преждевременно запускает сжатие.
Обходные решения:
- Используйте конечную точку подсчёта токенов, чтобы получить точную длину контекста.
- Избегайте сжатия при интенсивном использовании инструментов на стороне сервера.
Пограничные случаи использования инструментов
Когда SDK запускает сжатие, пока ожидается ответ на использование инструмента, он удаляет блок использования инструмента из истории сообщений перед генерацией резюме. После возобновления с резюме Claude повторно выполняет вызов инструмента, если он всё ещё нужен.
Мониторинг сжатия
Понимание того, когда срабатывает сжатие, помогает настраивать пороги и проверять ожидаемое поведение.
Когда использовать сжатие
Подходящие сценарии использования:
- Длительные агентные задачи, обрабатывающие множество файлов или источников данных
- Исследовательские рабочие процессы, накапливающие большие объёмы информации
- Многошаговые задачи с чётким, измеримым прогрессом
- Задачи, создающие артефакты (файлы, отчёты), которые сохраняются вне разговора
Менее подходящие сценарии использования:
- Задачи, требующие точного воспроизведения деталей начала разговора
- Рабочие процессы, интенсивно использующие инструменты на стороне сервера
- Задачи, которым необходимо поддерживать точное состояние множества переменных
Следующие шаги
Управляйте длинными разговорами с помощью серверного сжатия — рекомендуемой стратегии для большинства сценариев использования.
Снижайте затраты и задержку за счёт кэширования префиксов подсказок и узнайте, как редактирование контекста взаимодействует с кэшем.
Доступность
Claude API
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Amazon Bedrock
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Amazon Bedrock (bedrock-runtime)
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Claude Platform on AWS
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Claude Models on Google Cloud (Google managed)
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Microsoft Foundry
- Статус
- Бета
- API
- Messages API
- Бета-заголовок
- Требуется
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messagesсcontext_management
Кроме Охватываемые модели
Правки контекста (очистка использования инструментов и очистка размышлений) применяются в реальном времени.
Эта страница была полезной?