Claude Message Threads API: как работают треды

Claude message threads API позволяет отправить длинный диалог один раз, а в каждом следующем ходу передавать только новые сообщения. Добавьте "thread": {"type": "create"} в первый запрос Messages и заголовок beta message-threads-2026-08-12: API держит диалог в памяти, и следующий запрос отправляет меньше (страница Message threads у Anthropic, 4 ноября 2026).

Это beta на всех моделях. Ею могут пользоваться 17 ID моделей, включая Claude Opus 5.5, который вызывает код ниже. Заголовок beta нужен в каждом запросе треда.

Что экономит тред

Без треда каждый ход несёт всю переписку: системный промпт, описания инструментов, все прошлые сообщения и все результаты инструментов. Тред хранит этот диалог вместе с ответом Claude под id ответа, а запрос continue отправляет только то, что произошло после (страница Message threads, 4 ноября 2026). Меньше данных на каждый ход.

Кэш промптов помогает тому же диалогу иначе. Попадание в кэш удешевляет повторяющийся ввод: на Opus 5.5 это 0,20 USD за миллион токенов против 4 USD за новый ввод (страница цен Anthropic, 4 ноября 2026). Запрос всё равно несёт этот ввод. Тред сокращает то, что вы отправляете; кэш снижает цену повторяющегося. Длинным сессиям нужно и то и другое, а сокращение расхода токенов Claude Code разбирает сторону контекста.

Треды не меняют ни цены, ни лимиты скорости (страница Message threads, 4 ноября 2026). Актуальные тарифы — на странице цены.

Кэш вы включаете сами. Отправляйте cache_control верхнего уровня в каждом запросе, и API применит его к последнему кэшируемому блоку messages этого запроса. Ограничение в четыре точки останова — общее правило кэша промптов для всей платформы, и автоматический кэш занимает одну из четырёх (страница кэша промптов Anthropic, 4 ноября 2026). Распределяйте так:

1. cache_control верхнего уровня, одна точка в каждом запросе треда;
2. одна на system, отправляется с запросом create;
3. одна на tools, тоже при create;
4. одна на самом новом сообщении.

Точки останова на ранее сохранённых сообщениях не входят в этот лимит: запрос continue отправляет только новые сообщения. Отправленная точка остаётся на месте. При повторной отправке диалога уберите точки с прошлых сообщений и оставьте одну на последнем блоке (страница Message threads, 4 ноября 2026).

Первый ход и продолжение

Три шага:

1. Положите ключ Anthropic в ANTHROPIC_API_KEY.
2. Отправьте весь диалог, с system и tools, если пользуетесь ими, плюс "thread": {"type": "create"}.
3. Отправьте только сообщения после последнего ответа плюс "thread": {"type": "continue", "previous_message_id": "<previous id>"}, а system и tools не передавайте.

Каждый запрос несёт заголовок beta и anthropic-version: 2026-10-21, текущую версию (страница версий API Anthropic, 4 ноября 2026).

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'

Сохраните id из этого ответа. Следующий запрос отправит только новое сообщение:

PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON

Храните самый свежий id каждого ответа: тред только дополняется, каждый id ответа можно продолжить один раз, а следующий запрос должен использовать последний (страница Message threads, 4 ноября 2026).

Если нужен другой способ получить ключ API, OmniaKey продаёт доступ к API Claude с теми же ID моделей, так что тело запроса не меняется. Треды — beta на стороне Anthropic, поэтому перед работой в продакшене проверьте, что ваш посредник передаёт поле thread без изменений.

Python SDK ведёт id за вас. Соберите помощник через client.beta.messages.thread(...), который только готовит вызов, и отправляйте каждый ход через thread.send(). Помощник добавляет заголовок beta, создаёт тред на первом ходу, продолжает только с новыми сообщениями и один раз отправляет весь диалог заново в новом запросе create, когда continue возвращает thread_not_found, thread_already_continued или thread_continue_in_flight (страница Message threads, 4 ноября 2026).

import anthropic

client = anthropic.Anthropic()  # читает ANTHROPIC_API_KEY

# Помощник пока ничего не отправляет; он хранит поля, которые повторяются каждый ход.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # в следующий раз продолжайте с этого id

Мы не запускали эти запросы против API Anthropic; форма запросов взята со страницы Message threads. Для потоковой передачи thread.stream(...) и stream.get_final_message() дают тот же ход, а thread.previous_message_id возвращает id, если вы предпочитаете вести его сами.

Что отправлять снова, а что никогда

Фиксированные поля отправляйте с одними и теми же значениями в каждом запросе, system и tools — только в запросе create, а свободные поля могут меняться от хода к ходу.

400 на изменённое фиксированное поле несёт thread_fingerprint_mismatch, а в сообщении перечислены отличающиеся поля. Чтобы изменить такое значение, начните новый тред с полным диалогом и новым значением.

Если пропустить previous_message_id, continue вернёт 400, в теле будет message, но не будет error_code; то же самое при system или tools. Запрос continue должен нести ровно сообщения после последнего ответа.

mcp_servers фиксировано, но URL серверов и токены авторизации живут только в вашем запросе, поэтому отправляйте список в каждом запросе с MCP; токен может смениться между запросами. id контейнера тоже живёт только в вашем запросе, поэтому container отправляйте каждый раз (страница Message threads, 4 ноября 2026).

Серверный fallback решается при create: отправляйте fallbacks в каждом запросе треда или ни в одном. Значение может меняться между ходами, но добавление или удаление поля вернёт thread_fingerprint_mismatch.

Срок жизни, повторная отправка и 404

Тред истекает через 5 минут после последнего запроса, а API удаляет его не позже чем через 1 час после последнего использования. Каждый сохранённый ответ заново запускает эти 5 минут. Треды не подходят для нулевого хранения данных: диалог, системный промпт и инструменты лежат в памяти в зашифрованном виде и никогда не пишутся в долговременное хранилище (страница Message threads, 4 ноября 2026).

Ни одно поле ответа не говорит, сохранила ли API ход — ни при create, ни при continue. Вы узнаёте это из следующего запроса continue, поэтому приложение остаётся источником истины и хранит собственную копию каждого сообщения (страница Message threads, 4 ноября 2026).

Когда continue возвращает 404 thread_not_found, отправьте весь диалог новым запросом create и продолжайте с id этого ответа. Тот же 404 приходит во всех этих случаях:

• тред истёк;
• прошлый ход был обслужен и затем отброшен, например вызов инструмента, обрезанный max_tokens;
• прошлый ответ написала fallback-модель;
• прошлый ответ ещё генерируется;
• запрос пришёл из другой организации, рабочего пространства, от другого пользователя или ключа рабочего пространства;
• новые сообщения добавляют содержимое, которого нет в сохранённом диалоге, например первое изображение в диалоге без изображений.

Повторная отправка всего диалога безопасна и исправляет каждый из этих случаев.

Потоковая передача добавляет правило: продолжайте с id ответа только после message_stop, потому что continue, отправленный раньше, может вернуть 404. Если поток запроса continue оборвался до message_stop, отправьте тот же запрос continue снова, а если вернётся thread_already_continued или thread_continue_in_flight — отправьте весь диалог заново. Оборванный поток помощник SDK оставляет вам на повтор.

Ещё три случая идут своим путём:

• pause_turn: продолжайте с id этого ответа с "messages": []. Если придёт 404, отправьте всё заново вместе с приостановленным ответом.
• stop_reason: "refusal": начните новый тред без хода, который это вызвал; возможно, API уже хранит отклонённый ход.
• запись fallback_message в usage.iterations или в последнем message_delta потока отмечает ответ fallback: отправьте всё заново.

Ошибки

Все пять ошибок треда приходят до запуска модели: запрос не тратит токены, а срок треда не меняется. error.type равен invalid_request_error для 400 и not_found_error для 404 (страница Message threads, 4 ноября 2026).

• 404, thread_not_found: API не может продолжить этот тред. Отправьте весь диалог новым запросом create.
• 400, thread_fingerprint_mismatch: фиксированное поле отличается от значения, сохранённого с тредом. Оставьте его прежним или начните новый тред.
• 400, thread_already_continued: этот id ответа уже использован один раз. Продолжайте с самого свежего id, а если вы его не получили — отправьте всё заново.
• 400, thread_continue_in_flight: continue с тем же id ещё выполняется, обычно это ваша прошлая попытка. Дайте ей завершиться или отправьте всё заново.
• 400, thread_unsupported_request: запрос использует функцию или настройку организации, которых треды не поддерживают. error.details.unsupported называет одно из context_management, cache_control, fallbacks, hipaa или inference_hooks; список может расти, поэтому при незнакомом значении отправьте весь диалог без thread.

Message Batches не принимает поле thread (элемент пакета с ним падает с invalid_request_error), а подсчёт токенов и сжатие возвращают 400; также редактирование контекста, кроме clear_thinking_20251015 с keep: "all". Организации, готовые к HIPAA, и организации с включёнными Inference hooks исключены. Списка, чтения и удаления треда в API нет.

Частые вопросы

Что такое Claude Message Threads API?

Это beta-функция Messages API: она хранит диалог на стороне Anthropic, чтобы следующие ходы отправляли только новые сообщения. Заголовок beta — message-threads-2026-08-12, и каждый запрос добавляет объект thread с type равным create или continue.

Работают ли треды с кэшем промптов?

Да. Тред не кэширует промпт за вас: отправляйте cache_control верхнего уровня в каждом запросе и держитесь четырёх точек останова. Точки на сохранённых сообщениях в этот счёт не входят; верхняя и точки на system или tools входят.

Можно ли сменить модель посреди треда?

Смена модели требует нового треда. model — фиксированное поле, поэтому другое значение вернёт 400 thread_fingerprint_mismatch; начните новый тред с полным диалогом и новой моделью.

Почему continue возвращает 400 без error_code?

В continue нет previous_message_id или в нём есть system либо tools, даже как null. Такие 400 несут message и пропускают error_code, поэтому читайте текст.

Сколько живёт тред и что происходит после истечения?

Тред истекает через 5 минут после последнего запроса и удаляется не позже чем через 1 час после последнего использования. После этого continue вернёт 404 thread_not_found; отправьте весь диалог новым запросом create и продолжайте с его id.

Проверенные источники

• Anthropic: message threads
• Anthropic: кэш промптов
• Anthropic: цены Claude API
• Anthropic: версии API