AI 뉴스 · 15분 읽기

Claude API Message Threads: 긴 에이전트 세션에서 달라지는 점

Anthropic의 Messages API는 대화를 서버에 잠시 보관합니다. Message Threads가 지연 시간을 줄이는 방식과 변하지 않는 토큰 과금, 베타 이용 규칙을 살펴봅니다. 긴 에이전트 세션에서 스레드를 만들고 이어가는 방법과 만료 시 복구 절차도 설명합니다.

전체 기록을 다시 보내는 대신 서버에 보관된 빛나는 대화 타임라인에 짧은 메시지 턴이 추가되는 모습을 그린 일러스트.

Claude API Message Threads를 사용하면 Messages API가 짧은 기간 대화를 서버에 보관하므로, 이후 각 턴에서 전체 기록을 다시 보내는 대신 새 메시지만 전송합니다. 2026년 11월 초 공개 베타로 발표된 이 기능은 긴 에이전트 실행에서 요청 크기와 첫 토큰까지 걸리는 시간을 줄여 주지만, 과금되는 토큰 사용량은 정확히 그대로입니다.

코딩 어시스턴트나 여러 단계의 도구 루프를 만들어 봤다면 40번째 턴의 고충을 알 것입니다. 모델이 명령을 실행하거나 스크린샷을 살펴볼 때마다 클라이언트는 이전의 모든 프롬프트, 응답, 도구 결과를 묶어 전체를 네트워크로 다시 보냅니다. Message Threads는 이러한 전송 및 검증 병목에 대한 Anthropic의 해결책입니다. 다만 활성화 전에 설계에 반영해야 할 5분 만료, prompt caching, 데이터 보존 관련 엄격한 규칙이 몇 가지 있습니다.

Claude API Message Threads란?

Message Threads는 Claude Messages API용 서버 측 대화 캐시로, 베타에서는 message-threads-2026-08-12 헤더를 통해 활성화합니다. 모든 API 호출을 전체 채팅 기록이 필요한 백지 상태로 취급하는 대신, 서버가 턴 사이에 대화를 메모리에 보관하므로 클라이언트는 마지막 응답 이후 변경된 내용만 전송합니다.

Anthropic의 2026년 11월 2일 릴리스 노트와 문서에 따르면 이는 Claude Managed Agents의 세션 스레드와 별개입니다. 베타의 모든 모델에서 /v1/messages에 직접 작동하며, 직접 사용하는 Claude API, Claude Platform on AWS, Claude Models on Google Cloud(Anthropic 관리), Claude in Microsoft Foundry에서 이용할 수 있습니다.

턴 사이에 Anthropic은 서버 관리 키로 암호화된 스레드를 서버 메모리에 보관하며, 영구 디스크 저장소에는 절대 기록하지 않습니다.

Message Threads는 무엇을 절약하고 무엇은 절약하지 못할까?

Message Threads는 긴 대화에서 네트워크 업로드 크기와 첫 토큰까지의 시간(TTFT)을 줄이지만, 과금되는 토큰 수를 줄이거나 속도 제한을 바꾸지는 않습니다.

에이전트 세션이 수십만 토큰으로 커지면, 예를 들어 코딩 루프가 큰 파일을 읽거나 컴퓨터 사용 에이전트가 스크린샷을 주고받을 때 흔히 그렇듯, 매 턴 해당 페이로드를 다시 보내고 검증하느라 모델이 생성을 시작하기도 전에 눈에 띄는 지연이 발생합니다. Anthropic에 따르면 대부분의 Claude Code 사용자에게 Message Threads가 기본으로 켜져 있으며, 500k~1M 토큰을 담은 요청에서 TTFT 중앙값이 약 35% 감소합니다.

청구 금액은 달라지지 않습니다. HTTP 요청에 최신 사용자 메시지나 도구 출력만 들어 있어도 Claude는 매 턴 전체 대화를 읽습니다. 표준 토큰 요금이 적용됩니다. 2026년 11월 기준 Claude Opus 5.5의 공시 가격은 입력 토큰 100만 개당 $4(캐시된 경우 $0.20), 출력 토큰 100만 개당 $20이며, Sonnet 5.5는 입력 $2(캐시된 경우 $0.10), 출력 $10입니다(요금 수준 비교는 AI API 가격 비교와 Claude Opus 5.5 대 Sonnet 5.5 가이드를 참조하세요).

Message Threads로 달라지는 점 그대로인 점
후속 턴의 HTTP 요청 페이로드가 작아짐 매 턴 전체 대화의 토큰을 읽고 과금함
첫 토큰까지의 시간 단축(Anthropic에 따르면 Claude Code의 500k–1M 토큰 요청에서 TTFT 중앙값이 ~35% 감소) 표준 API 토큰 가격과 기존 속도 제한
스레드 생성 시 system과 tools를 한 번 전송 메시지 기록의 원본은 계속 앱에서 관리

스레드를 생성하고 이어가려면?

일반적인 /v1/messages 요청에 "thread": {"type": "create"}와 message-threads-2026-08-12 베타 헤더를 넣어 스레드를 시작한 다음, 다음 턴에서 응답의 id를 previous_message_id로 전달해 이어갑니다. Anthropic의 SDK를 사용한다면 client.beta.messages.thread(...) 헬퍼가 생성과 이어가기 흐름을 관리하고 베타 헤더를 자동으로 추가합니다.

처음 create를 호출할 때는 그 시점까지의 전체 대화와 함께 system 및 tools를 포함합니다.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 2048,
  "system": "You are a careful repository refactoring assistant.",
  "tools": [
    {
      "name": "run_tests",
      "description": "Run the project test suite",
      "input_schema": { "type": "object", "properties": {} }
    }
  ],
  "thread": {
    "type": "create"
  },
  "messages": [
    { "role": "user", "content": "Check why the auth test is failing." }
  ]
}

API는 Claude의 답변을 포함해 저장된 대화를 나타내는 id(예: msg_01XYZ...)가 담긴 표준 메시지 응답을 반환합니다. 다음 턴에서는 tool_result나 사용자의 다음 프롬프트 같은 새 메시지만 보내고 해당 id를 참조합니다.

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 2048,
  "thread": {
    "type": "continue",
    "previous_message_id": "msg_01XYZ..."
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01ABC...",
          "content": "FAIL src/auth.test.ts: expected 200, got 401"
        }
      ]
    }
  ]
}

문서를 건너뛰면 놓치기 쉬운 규칙

Anthropic은 스레드의 전체 수명 동안 엄격한 일관성을 요구합니다.

  • 생성 시에만 쓰는 필드: 모든 continue 요청에서 system과 tools를 생략해야 합니다. 다시 보내면 400 오류가 반환됩니다.
  • 고정 필드: model, tool_choice, thinking, mcp_servers(각 서버의 인증 토큰 제외), context_management, output_config, 컨테이너 스킬, 최상위 cache_control, anthropic-beta 헤더 값의 정확한 집합은 최초 create 호출과 일치해야 합니다. 하나라도 바꾸면 400 thread_fingerprint_mismatch 오류가 발생합니다.
  • 턴별 필드: max_tokens, stop_sequences, stream, metadata, service_tier는 턴마다 자유롭게 변경할 수 있습니다.
  • 추가만 가능한 기록: 각 응답 id는 한 번만 이어갈 수 있으며 항상 최신 응답 id에서 이어가야 합니다. 이전 메시지를 수정하거나 대화를 분기해야 한다면 create로 새 스레드를 시작해야 합니다.

Message Thread는 얼마나 오래 유지될까?

Message Thread는 마지막 요청 후 5분이 지나면 만료되고 마지막 사용 후 늦어도 1시간 이내에 서버 메모리에서 영구 삭제됩니다. 응답이 성공적으로 저장될 때마다 5분 타이머가 초기화됩니다.

스레드는 휘발성 메모리에 최선형 캐시로 보관되므로 API 응답은 특정 턴이 성공적으로 저장됐는지 미리 알려 주지 않습니다. 다음 continue 호출에서야 알 수 있습니다. 5분의 시간이 지났거나 서버가 스레드를 일찍 제거했다면 API는 404 오류를 반환합니다.

클라이언트가 404를 받았을 때 복구 방법은 간단합니다. 전체 대화 기록을 system 및 tools와 함께 새 "thread": {"type": "create"} 요청으로 다시 보내면 됩니다. 애플리케이션이 계속 원본을 관리하며 모든 메시지와 도구 결과의 완전한 사본을 자체적으로 보관해야 합니다.

Message Threads는 prompt caching과 어떻게 작동할까?

Message Threads와 prompt caching은 긴 컨텍스트 문제의 서로 다른 부분을 해결하며, 스레드를 활성화해도 prompt caching이 자동으로 켜지지는 않습니다. Message Threads는 네트워크로 업로드하고 검증하는 바이트 수를 줄이고, prompt caching은 반복되는 입력 토큰의 비용을 줄입니다(예를 들어 AI API 가격 비교에서 설명하듯 Sonnet 5.5 입력 토큰의 가격을 100만 개당 $2에서 $0.10으로 낮춥니다).

더 빠른 TTFT와 더 낮은 입력 토큰 비용을 모두 원한다면 둘 다 활성화해야 합니다. 스레드 안의 각 턴을 캐시하려면 최초 create 요청에 최상위 cache_control을 포함하고 모든 continue 요청에서도 동일한 최상위 cache_control을 계속 보내야 합니다(최상위 cache_control은 스레드 전체에서 일치해야 하는 고정 필드 중 하나임을 기억하세요). Anthropic은 thread가 설정되었을 때 cache_control 중단점을 최대 4개 허용합니다.

누가 Message Threads를 켜야 할까?

장시간 실행되는 코딩 루프, 컴퓨터 사용 워크플로, 문서가 많은 다중 턴 에이전트를 운영하는 팀이 가장 뚜렷한 효과를 볼 수 있습니다. 반면 엄격한 규정 준수 요건이 있거나 배치 파이프라인을 사용하는 팀은 사용을 포기해야 할 수도 있습니다. 도구를 사용하는 루프와 일반 챗봇의 차이가 생소하다면 AI 에이전트란 무엇인가 가이드에서 기초를 살펴볼 수 있습니다.

Message Threads가 가장 적합한 경우:

  • 코딩 에이전트: 파일을 읽고 컴파일러를 실행하며 활성 상태인 5분 이내에 수십 번의 빠른 턴을 반복하는 루프입니다. (Anthropic은 이미 대부분의 Claude Code 사용자에게 기본으로 활성화했습니다.)
  • 컴퓨터 사용 에이전트: 매 턴 새로운 데스크톱 또는 브라우저 스크린샷을 첨부하는 워크플로입니다. 이전 스크린샷을 서버에 보관하면 단계마다 수 메가바이트의 base64 이미지 데이터를 다시 업로드하지 않아도 됩니다.
  • 문서와 이미지가 많은 채팅: 사용자가 큰 PDF나 이미지 모음을 업로드하고 연이어 후속 질문을 하는 대화형 세션입니다. 에이전트가 AI Studio 같은 도구에서 스크립트를 작성하고 렌더링을 시작하는 등 외부 미디어 파이프라인을 조율하더라도, 용량이 큰 계획 컨텍스트와 참조 이미지를 서버 측 스레드에 보관하면 조정 루프의 응답성을 유지할 수 있습니다.

2026년 11월 기준 차단되거나 지원되지 않는 경우:

  • Zero Data Retention(ZDR) 및 HIPAA 조직: Message Threads는 ZDR 대상이 아니며, HIPAA 준비 상태를 활성화한 조직은 사용할 수 없습니다.
  • 지원되지 않는 API 기능: thread는 Message Batches, thread를 포함하는 토큰 수 계산 요청, 주문형 압축, 대부분의 컨텍스트 편집 전략(clear_thinking_20251015와 keep: "all"의 조합 제외), 또는 Inference hooks를 켠 조직에서 사용할 수 없습니다.

내가 실제로 취할 방법

Claude Messages API에서 에이전트 구동 환경을 관리한다면, 규정 준수 요건이 허용하는 한 단일 작업이 정기적으로 100k 토큰을 넘고 턴 간격이 5분 미만인 모든 곳에서 Message Threads를 활성화하겠습니다. 제가 따를 도입 체크리스트는 다음과 같습니다.

  1. 로컬 대화 저장소를 그대로 유지합니다. 서버에 보관된 스레드는 전송 가속 수단으로만 취급하고 데이터베이스로 사용하지 마세요. 지금처럼 모든 사용자 턴, 어시스턴트 응답, 도구 결과를 로컬에 추가합니다.
  2. continue에 자동 404 대체 처리를 추가합니다. continue 호출이 404를 반환하면(5분 동안 유휴 상태였거나 최선형 캐시에서 제거된 경우 모두) 이를 처리하고 즉시 전체 로컬 기록을 "thread": {"type": "create"}, system, tools와 함께 다시 보냅니다.
  3. 최상위 cache_control과 함께 사용합니다. 청구서가 줄어들 것으로 기대하며 Message Threads를 켜지 마세요. create와 continue 호출 양쪽에 최상위 cache_control을 넣어 TTFT 속도 향상과 함께 캐시된 입력에 대한 90% 이상의 할인을 받으세요. AI API 가격 비교에서 500k 토큰에 대한 캐시 미적용 및 적용 입력 비용을 계산해 보세요.
  4. 생성 시 스레드 구성을 고정합니다. 에이전트 루프가 작업 도중 tools, system, thinking, anthropic-beta 헤더를 동적으로 변경하지 않는지 점검하세요. 그렇지 않으면 400 thread_fingerprint_mismatch 오류가 발생합니다.
  5. 먼저 ZDR 및 HIPAA 설정을 확인합니다. 작업 공간이 Zero Data Retention 또는 HIPAA 준비 상태에 의존한다면 Message Threads를 꺼 두세요. 베타는 어느 쪽에도 적합하지 않습니다.

자주 묻는 질문

Message Threads를 사용하면 Claude API 토큰 비용이 줄어드나요?

아니요. 후속 HTTP 요청마다 새 메시지만 담겨 있어도 Claude는 매 턴 전체 대화 기록을 읽습니다. 전체 입력 및 출력 토큰에 표준 Claude 요금이 과금되고 기존 속도 제한도 계속 적용됩니다. 반복되는 컨텍스트의 입력 토큰 요금을 낮추려면 Message Threads와 prompt caching을 함께 사용하세요.

Message Threads를 사용해도 prompt caching이 필요한가요?

네. Message Threads는 이전 메시지를 네트워크로 다시 업로드하고 검증하지 않도록 대화를 서버 메모리에 보관할 뿐입니다. prompt caching을 자동으로 활성화하지 않습니다. 매 턴 캐시된 입력 가격을 적용받으려면 최초 create 요청과 이후 모든 continue 요청에 최상위 cache_control을 보내세요(중단점은 총 4개까지).

5분 동안 사용하지 않으면 어떻게 되나요?

Message Thread는 마지막 요청 후 5분이 지나면 만료됩니다(마지막 사용 후 늦어도 1시간 이내에 메모리에서 삭제됩니다). 스레드가 만료된 후 continue 요청을 보내면 API가 404 상태 코드를 반환합니다. 클라이언트는 해당 404를 처리하고 "thread": {"type": "create"}와 함께 전체 대화를 다시 보내 새 스레드를 시작해야 합니다.

Message Threads는 AWS, Azure, Google Cloud에서 이용할 수 있나요?

네. Anthropic의 2026년 11월 2일 릴리스 노트에 따르면 공개 베타(message-threads-2026-08-12)는 직접 사용하는 Claude API, Claude Platform on AWS, Claude Models on Google Cloud(Anthropic 관리), Claude in Microsoft Foundry에서 이용할 수 있습니다.

Claude Code는 이미 Message Threads를 사용하나요?

네. Anthropic에 따르면 대부분의 Claude Code 사용자에게 Message Threads가 기본으로 켜져 있으며, 500k~1M 토큰의 요청에서 첫 토큰까지 시간의 중앙값이 약 35% 감소합니다.

기능 세부 사항 최종 확인: 2026년 11월 3일. 다음 검토: 2026년 12월 3일.

출처

작성자

Chunyu Cai

Chunyu Cai는 Lotook, LLC의 CEO이자 기업가로, AI 모델과 에이전트, 그리고 이들이 일상 업무를 어떻게 바꾸는지에 관해 글을 씁니다. Chunyu Cai는 Imperial College London에서 석사 학위를 받았습니다.