claudekit / updates / message-threads
[ NEW · ]

Claude Platform, message threads 공개 베타 출시 (긴 에이전트 세션의 첫 응답 시간 단축)

Messages API에 대화 전체를 한 번만 보내고 이후에는 새 메시지만 보내는 message threads가 공개 베타로 출시되었습니다. 긴 세션에서 첫 토큰까지 걸리는 시간(TTFT)을 줄여 주며, 토큰 사용량과 요금은 그대로입니다.

공식 발표 →

이 글은 공식 문서를 바탕으로 요약·정리한 내용입니다.

핵심 요약

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_control breakpoint는 최대 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와는 다른 기능입니다 — 이름이 비슷하지만 별개이므로 문서를 찾을 때 구분해야 합니다.
  • 자세한 사용법 — 공식 문서에서 요청별 필드 규칙, 오류 코드, 지원 모델을 확인할 수 있습니다.
§ 4

자주 묻는 질문

자주 묻는 질문
§ 4.1
message threads는 무엇인가요?
Messages API 요청에 thread 파라미터를 추가해, 대화 전체를 한 번만 보내고 이후 턴에서는 새 메시지와 이전 응답의 id만 보내는 기능입니다. 서버가 대화를 잠시 보관했다가 모델 호출 전에 다시 구성합니다.
§ 4.2
토큰 비용도 줄어드나요?
아니요. Claude는 매 턴 대화 전체를 읽기 때문에 토큰 사용량은 그대로이고, 표준 토큰 요금과 기존 rate limit이 적용됩니다. 줄어드는 것은 첫 토큰까지 걸리는 시간(TTFT)입니다.
§ 4.3
어디에서 사용할 수 있나요?
2026년 11월 2일 발표 기준으로 Claude Platform, Claude Platform on AWS, Claude in Microsoft Foundry, Claude Models on Google Cloud (Anthropic managed)에서 공개 베타로 제공됩니다. 요청마다 message-threads-2026-08-12 베타 헤더가 필요하며, SDK의 thread helper를 쓰면 자동으로 추가됩니다.
§ 4.4
Claude Code 사용자도 직접 설정해야 하나요?
발표에 따르면 대부분의 Claude Code 사용자에게는 message threads가 기본으로 켜져 있습니다. 500k에서 1M 토큰 규모의 요청에서 TTFT 중앙값이 약 35% 줄었습니다.
§ 4.5
스레드가 만료되면 어떻게 되나요?
스레드는 마지막 요청 후 5분이 지나면 만료되고, 이어가기 요청은 404 오류를 반환합니다. 이때 전체 대화를 새 create 요청으로 다시 보내면 됩니다. SDK의 thread helper는 이 재전송을 자동으로 한 번 수행합니다.
§ 4.6
Zero Data Retention(ZDR) 대상인가요?
아닙니다. 공식 문서에 따르면 message threads는 ZDR 대상이 아닙니다. 스레드 내용은 암호화되어 메모리에만 보관되고 디스크에 기록되지 않으며, 마지막 사용 후 1시간 이내에 삭제됩니다.