Как сохранять контекст агентов без повторной отправки сообщений: разбор Message Threads в Claude API

Бета-заголовок message-threads-2026-08-12 сохраняет историю диалога на сервере Anthropic, снижая задержку до первого токена на 35% в длинных сессиях агентов.

Компания Anthropic 2 ноября 2026 года начала открытое бета-тестирование механизма Message Threads для Messages API. Функция решает проблему роста сетевых задержек в циклических сценариях автономных агентов и длительных сессиях: вместо повторной передачи всей истории диалога на каждом шаге клиент отправляет только новые реплики, а сервер восстанавливает контекст из защищённой оперативной памяти.

Раздел документации Message threads в Claude Platform Docs. Источник: Anthropic

В типовом цикле работы агента (coding loop, работа с инструментами, анализ репозиториев) контекст непрерывно расширяется: к исходному системному промпту добавляются десятки вызовов инструментов и результаты их выполнения.
Без использования серверных тредов клиентское приложение вынуждено пересылать полный массив сообщений при каждом обращении к эндпоинту /v1/messages.
Повторная загрузка сотен тысяч токенов увеличивает сетевой оверхед и заставляет инфраструктуру API заново валидировать и токенизировать весь массив входящих данных.
По замерам Anthropic, в сессиях объёмом от 500 тыс. до 1 млн токенов механизм Message Threads сокращает медианное время до генерации первого токена (TTFT) примерно на 35% за счёт устранения лишней валидации.

Работа с тредом строится через единый параметр thread, передаваемый в тело запроса. Протокол разделяет взаимодействие на две фазы:

Фаза инициализации (create): первый запрос содержит полный набор сообщений, системную инструкцию system, список инструментов tools и параметр "thread": {"type": "create"}. Сервер сохраняет контекст и присваивает сессии идентификатор ответа id.
Фаза продолжения (continue): в последующих запросах передаются только новые реплики (сообщения пользователя или блоки tool_result) вместе с параметром "thread": {"type": "continue", "previous_message_id": "id_ответа"}.
Поля system и tools на шаге продолжения не передаются: сервер автоматически подставляет значения, зафиксированные при вызове create.

Для работы с бета-функционалом во все запросы добавляется заголовок anthropic-beta: message-threads-2026-08-12. Базовый сценарий формирования полезной нагрузки выглядит следующим образом:

import json create_payload = { "model": "claude-opus-5-5", "max_tokens": 1024, "system": "Ты — автономный агент.", "messages": [{"role": "user", "content": "Инициализация задачи"}], "thread": {"type": "create"}, } continue_payload = { "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Следующий шаг"}], "thread": {"type": "continue", "previous_message_id": "msg_01XyZ"}, } assert "system" in create_payload assert "system" not in continue_payload print("OK: payloads validated")

В официальном Python SDK Anthropic предусмотрен вспомогательный класс client.beta.messages.thread(...), который самостоятельно отслеживает previous_message_id, удаляет системные промпты из последующих запросов и повторяет создание сессии в случае сбоя.

Спецификация документации разделяет параметры вызова на три строгие категории:

Параметры только для фазы create: поля system и tools. Попытка передать любое из них в запросе continue (даже со значением null) приводит к ошибке HTTP 400.
Фиксированные параметры (Fixed): поля model, tool_choice, thinking, mcp_servers, context_management, output_config и верхнеуровневый cache_control. Их значения обязаны в точности совпадать с параметрами создания треда, иначе API возвращает ошибку thread_fingerprint_mismatch.
Свободные параметры (Free): поля max_tokens, stop_sequences, stream, metadata и service_tier могут свободно меняться от шага к шагу.
Особенность серверов MCP: адреса серверов и токены авторизации не кэшируются на сервере, поэтому блок mcp_servers отправляется при каждом вызове инструмента.

Внедрение Message Threads меняет логику передачи данных по сети, но не влияет на внутреннюю тарификацию модели:

Сравнение базового режима Messages API и серверных тредов. Данные: Anthropic

Стоимость генерации: Claude обрабатывает полный контекст при каждом ответе, поэтому количество потребляемых токенов и стандартные тарифы остаются без изменений.
Время жизни серверного контекста: тред хранится в оперативной памяти и становится неактивным через 5 минут после последнего обращения. Каждый успешный ответ продлевает таймер ещё на 5 минут, а окончательное удаление происходит через 1 час.
Безопасность данных: треды шифруются серверным ключом в RAM и никогда не сохраняются на постоянный диск. Функция не поддерживает регламенты Zero Data Retention (ZDR) и HIPAA readiness.

Серверные треды функционируют по принципу best-effort кэша. Клиентское приложение обязано оставаться единственным источником истины (source of truth) для всей истории сообщений.

Если запрос continue завершается кодом 404 с кодом ошибки thread_not_found (истечение пятиминутного таймера, рестарт инстанса или переключение между воркспейсами), клиент немедленно отправляет новый запрос create со всей накопленной локально историей.
Аналогичный перезапуск требуется при возникновении конфликтов параллельных запросов thread_already_continued или thread_continue_in_flight.
При возникновении отказа модели (stop_reason: refusal) продолжение текущего треда блокируется: необходимо удалить или скорректировать вызвавшую отказ реплику и открыть новый тред.

def should_replay(status_code: int, error_code: str) -> bool: """Определяет необходимость перезапуска треда через create.""" return status_code == 404 and error_code in ( "thread_not_found", "thread_already_continued", "thread_continue_in_flight", ) assert should_replay(404, "thread_not_found") is True assert should_replay(400, "thread_fingerprint_mismatch") is False print("OK: replay logic verified")

Отсутствие управления тредами: в API нет методов для получения списка активных сессий, ручного чтения их содержимого или явного удаления.
Пакетная обработка: Message Threads не поддерживаются в Message Batches API, запросы с параметром thread в батче отклоняются с ошибкой invalid_request_error.
Подсчёт токенов: эндпоинт предварительного расчёта /v1/messages/count_tokens не принимает параметр thread и требует передачи полной истории с system и tools.
Компакция на лету: динамическое сжатие контекста через бета-заголовок compact-2026-09-04 несовместимо с тредами, так как тред строго append-only; для сокращения истории требуется вручную собрать саммари и открыть новый тред.
В сентябре 2026 года Anthropic перевела в общедоступный статус функционал Cache Diagnostics, а в начале ноября расширила возможности управления длинным контекстом серверными тредами.