핵심 요약
Claude Platform의 Messages API에 message threads가 공개 베타로 추가되었습니다. 대화 전체를 한 번만 보내면 이후 턴에서는 새 메시지만 보내면 되므로, 대화가 길어져도 **첫 토큰까지 걸리는 시간(TTFT, time to first token)**이 낮게 유지됩니다.
코딩 에이전트는 한 세션에서 수백 번 요청을 보내기도 하고, 대화가 수십만 토큰에 이르면 이를 매번 다시 보내는 것만으로 응답 시작이 늦어집니다. 대부분의 Claude Code 사용자에게는 이미 기본으로 켜져 있으며, 500k에서 1M 토큰 규모의 요청에서 TTFT 중앙값이 약 35% 줄었습니다.
주요 기능
-
새 메시지만 보내는 요청 방식
스레드 없이는 매 턴 대화 전체를 업로드하고, API가 이를 다시 검증하고 토큰화합니다. 스레드를 쓰면 이 작업 대부분이 새 턴에만 적용됩니다. 첫 요청에는 평소처럼 전체 대화와
system,tools를 보내면서thread파라미터를 추가하고, 이후 요청에는 새 메시지와 이전 응답의id만 보냅니다.// 첫 요청 "thread": {"type": "create"} // 이후 요청 (system, tools는 생략) "thread": {"type": "continue", "previous_message_id": "<이전 응답의 id>"} -
SDK thread helper
스레드 요청을 직접 구성하지 않아도 되도록 SDK에 helper가 제공됩니다. 첫 턴에 스레드를 만들고 이후 턴에는 새 메시지만 보내며, 베타 헤더도 자동으로 추가합니다. 스레드를 이어갈 수 없을 때(
thread_not_found등)는 전체 대화를 한 번 다시 보내 복구합니다. Python 기준client.beta.messages.thread(...)로 만들고thread.send(...)로 턴을 보냅니다. -
긴 세션에 맞춘 활용 범위
발표에서 꼽은 대상은 지연 시간이 중요한 진행 중인 세션입니다. 도구 실행 결과와 파일 수정이 계속 쌓이는 장기 실행 코딩 에이전트, 스크린샷을 매 턴 다시 올릴 필요 없이 스레드에 유지하는 computer use 에이전트, 문서와 이미지가 많은 작업이 해당합니다.
-
네 가지 제공 경로에서 베타 제공
네이티브 Claude Platform, Claude Platform on AWS, Claude in Microsoft Foundry, Claude Models on Google Cloud (Anthropic managed)에서 쓸 수 있습니다. 직접 요청을 구성할 때는 모든 요청에
message-threads-2026-08-12베타 헤더를 보내야 합니다.
알아두면 좋은 점
- 토큰 사용량과 요금은 줄지 않습니다 — Claude는 매 턴 대화 전체를 읽으므로 토큰 사용량은 그대로이고, 표준 토큰 요금과 기존 rate limit이 적용됩니다.
- prompt caching은 별도로 지정해야 합니다 — 스레드가 프롬프트를 자동으로 캐시하지는 않습니다. 매 턴을 캐시하려면 최상위
cache_control을 모든 요청에 보내야 하며,thread를 쓰는 요청의cache_controlbreakpoint는 최대 4개입니다. - 스레드는 오래 유지되지 않습니다 — 마지막 요청 후 5분이 지나면 만료되고, 마지막 사용 후 1시간 이내에 삭제됩니다. 이어갈 수 없으면 이어가기 요청이 404 오류를 반환하므로 전체 대화를 다시 보내야 합니다. 대화 원본은 애플리케이션에서 직접 보관해야 하며, 재전송 경로를 처음부터 구현하도록 문서에서 안내합니다.
- 중간에 바꿀 수 없는 값이 있습니다 —
model,thinking,tool_choice, 최상위cache_control등은 스레드의 모든 요청에서 같은 값이어야 합니다. 스레드는 뒤에 추가만 가능하므로 이전 메시지를 수정하거나 분기하려면 새 스레드를 만들어야 합니다. - 함께 쓸 수 없는 기능이 있습니다 — Message Batches, 토큰 카운팅, compaction(긴 대화를 요약해 줄이는 기능), 일부를 제외한 context editing은 지원되지 않습니다. HIPAA readiness나 Inference hooks를 켠 조직도 사용할 수 없습니다.
- ZDR 대상이 아닙니다 — 스레드 내용은 서버 관리 키로 암호화되어 메모리에만 보관되고 디스크에 기록되지 않지만, Zero Data Retention(ZDR) 대상 기능은 아닙니다. 다른 ZDR 대상 기능의 사용에는 영향을 주지 않습니다.
- Claude Managed Agents의 session threads와는 다른 기능입니다 — 이름이 비슷하지만 별개이므로 문서를 찾을 때 구분해야 합니다.
- 자세한 사용법 — 공식 문서에서 요청별 필드 규칙, 오류 코드, 지원 모델을 확인할 수 있습니다.