AIREITER긴 에이전트 루프에서 매번 수십만 토큰의 대화 이력을 다시 전송하고 있다면 Claude Message Threads가 전송 부담을 덜어줄 수 있다. Anthropic이 2026년 11월 2일 공개 베타로 출시한 이 기능은 500K~1M 토큰 요청에서 첫 토큰까지 걸리는 중앙값 시간을 약 35% 낮춘다. 다만 토큰 청구량은 줄지 않으며, 5분간 유휴 상태가 되면 만료된다는 제약이 있다.
빨라지는 것은 전송, 그대로인 것은 토큰 비용
Message Threads는 Messages API를 위한 임시 서버 측 대화 상태 기능으로, 2026년 11월 2일 공개 베타로 나왔다. 첫 요청에서는 thread: { "type": "create" }와 함께 전체 대화 이력을 보내고, 이후에는 thread: { "type": "continue" } 및 previous_message_id를 사용해 새 메시지만 보낸다. Anthropic의 발표와 플랫폼 문서에 따르면 상태는 암호화된 메모리에만 보관되고 디스크에는 기록되지 않는다. 유휴 상태가 5분 지속되면 만료되며, 마지막 사용 후 늦어도 1시간 안에는 삭제된다.
스레드에 속한 모든 요청에는 베타 헤더 anthropic-beta: message-threads-2026-08-12가 필요하다. 가격과 속도 제한은 변하지 않는다. Claude는 매 턴 전체 대화를 계속 읽기 때문에 입출력 토큰 비용은 동일하다. 달라지는 것은 업로드하는 바이트 수다.
"좋긴 한데 토큰 비용은 줄지 않네요 :( Claude는 매 턴 전체 대화를 계속 읽고, 토큰 사용량도 그대로입니다." — @_navicstein, 공식 출시 스레드에 남긴 답글
공식 발표도 500K~1M 토큰 요청에서 중앙값 TTFT가 약 35% 낮아진다고 밝히며, 토큰 할인은 없다고 명시한다.
Prompt Caching과는 역할이 다르다
Threads는 보내는 데이터를 줄이고, Prompt Caching은 정가로 지불하는 비용을 줄인다. Threads가 자동으로 캐시를 설정해 주는 것은 아니므로 여전히 cache_control 중단점을 지정해야 한다. 아래 캐싱 동작 설명은 구현 분석을 따른다. continuation마다 최상위 cache_control을 유지해야 하며, 캐시 읽기 비용은 기본 입력 비용의 0.1배다. Claude Opus 5.5와 Sonnet 5.5에서는 0.05배다.
Managed-agent session threads와 혼동하지 말 것
검색 결과에는 서로 다른 두 종류의 "thread"가 섞여 나온다. 이 글에서 다루는 Messages API Message Threads는 요청 크기를 줄이기 위한 일시적 기능이며, 목록 조회·읽기·삭제 API가 없다. 반면 Managed-agent session threads(GET /v1/sessions/{session_id}/threads/{thread_id})는 Anthropic managed-agents API 안에서 실행되는 스레드로, 목록·조회·보관 엔드포인트를 제공한다. 문서에서 child thread, 이벤트 스트림, 아카이브를 언급한다면 다른 API를 보고 있는 것이다. 필요한 인터페이스를 확인하려면 session threads API 레퍼런스를 참고하자.
스레드는 생성하고, 이어가고, 만료되면 다시 만든다
실제로 스레드는 추가 전용으로 동작한다. 전체 컨텍스트로 생성하고, 변경분만 이어 보내며, 상태를 잃으면 전체 이력을 재생한다. 분기, 수정, 되감기, 조회 API는 없다. 응답마다 새로운 id가 반환되고, 각 id는 한 번만 continuation에 사용할 수 있다. 이 섹션의 필드 및 오류 규칙은 플랫폼 문서와 이를 정리한 구현 분석을 바탕으로 한다.
생성 요청에는 전체 messages, system, tools를 모두 포함하고 다음을 추가한다.
{
"model": "claude-opus-5-5",
"system": "You are a support agent for Acme. Keep replies short.",
"messages": [{ "role": "user", "content": "Hi! I have a question about an order." }],
"thread": { "type": "create" }
}이후 continuation에는 새로 발생한 내용만 담는다. 일반적으로 사용자 메시지 또는 tool_result 블록이다.
{
"model": "claude-opus-5-5",
"messages": [{ "role": "user", "content": "How long does standard shipping usually take?" }],
"thread": { "type": "continue", "previous_message_id": "msg_xxx_from_create" }
}continuation에서는 system과 tools를 생략해야 한다. "system": null처럼 보내도 400 오류가 난다. 스트리밍을 쓴다면 message_stop 이후에 continuation을 시작해야 하며, 사용할 수 있는 continuation ID는 message_start에서 전달된다.
스레드 진행 중 변경 가능한 필드
Anthropic은 생성 요청 일부의 지문(fingerprint)을 저장한다. 지문에 포함된 값을 바꾸면 thread_fingerprint_mismatch가 반환되며 새 스레드를 만들어야 한다.
| 구분 | 예시 | continuation 규칙 |
|---|---|---|
| 생성 전용 | system, tools | 다시 보내지 말 것, null도 실패 |
| 고정값 | model, tool_choice, thinking, mcp_servers, context_management, output_config, container skills, 최상위 cache_control 처리 | 동일하게 유지해야 함 |
| 변경 가능 | max_tokens, stop_sequences, stream, metadata, service_tier | 턴마다 변경 가능 |
| 항상 재전송 | MCP 서버 URL / 인증 토큰, container ID | 서버 측에 저장되지 않으므로 사용할 때마다 포함 |
Extended Thinking 모델은 특히 주의해야 한다. system 또는 tools를 수정하면 이전 thinking / redacted_thinking 블록이 무효화될 수 있다. 만료 뒤 전체 재생에서 400이 발생하면, 그대로 재시도하지 말고 재생할 이력에서 오래된 thinking 블록을 제거한다.
5분 만료를 전제로 재생 경로를 설계해야 한다
Threads는 최선 노력형 기능으로 다루는 편이 안전하다. 다음 continuation이 성공해야만 저장이 확인되므로 전체 이력, system, tools, 파일 참조를 로컬에 보관해야 한다. 파일은 참조 형태로 유지되므로 스레드 도중 파일을 삭제하면 continuation이 실패한다.
저장된 응답이 생길 때마다 만료 시계가 초기화된다. 5분간 유휴 상태가 지속된 뒤 continuation을 보내면 404가 반환되며, 전체 대화를 새 create 요청으로 재생해야 한다. 데이터는 마지막 사용 후 늦어도 1시간 안에 삭제된다.
| HTTP | 코드 | 발생 원인 | 대응 방법 |
|---|---|---|---|
| 404 | thread_not_found | 만료, 미저장, 잘못된 키/워크스페이스, 텍스트 전용 스레드에 첫 이미지 추가, fallback 모델 응답, 또는 응답 생성 중인 경우 | 키/워크스페이스와 설정을 확인한 뒤 전체 이력으로 새 create를 실행 |
| 400 | thread_fingerprint_mismatch | 고정 필드가 변경됨 | 원래 값을 복원하거나 새 스레드 시작 |
| 400 | thread_already_continued | 해당 previous_message_id를 이미 사용함 | 가장 최신 id에서 continuation 실행 |
| 400 | thread_continue_in_flight | 같은 ID에 대한 동시 continuation | 완료를 기다린 뒤 새 ID를 사용하고, 불가능하면 재생 |
| 400 | thread_unsupported_request | 지원하지 않는 설정(예: 캐시 중단점 4개 초과, 배치) | 설정을 제거하거나 thread 없이 전송 |
문서 요약에 따르면 실패한 thread 요청은 모델 실행 전에 처리된다. 따라서 토큰을 소비하지 않고 만료 타이머도 초기화하지 않는다. 다음 턴을 받기 전에 가장 최근에 성공한 응답 ID를 원자적으로 저장하고, 도구 작업에 부작용이 있다면 재생 과정의 멱등성도 보장해야 한다.
Python 재생 형태는 다음과 같다. 검증된 thread_not_found만 처리하며, fingerprint·동시성·지원되지 않는 요청 오류는 별도 분기가 필요하다.
try:
resp = client.beta.messages.create(
model="claude-opus-5-5",
messages=[new_msg], # delta only
thread={"type": "continue", "previous_message_id": last_id},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)
except NotFoundError: # thread_not_found after checking identity/config
resp = client.beta.messages.create(
model="claude-opus-5-5",
system=SYSTEM, tools=TOOLS,
messages=full_history + [new_msg], # you stored this
thread={"type": "create"},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)프록시와 키 로테이션이 만드는 404 함정
아직 공식 문서에는 없지만 운영자들이 보고한 동작이 있다. 스레드는 이를 생성한 조직, 워크스페이스, 자격 증명에 묶인다. 요청마다 API 키를 교체하는 릴레이를 쓰면 키 A로 생성한 뒤 키 B로 continuation을 시도하게 된다. 이 경우 만료와 똑같이 보인다. 404가 반복되고 전체 재생으로 돌아가므로 지연 시간 개선도 얻지 못한다.
"thread는 생성한 key와 workspace에 바인딩됩니다. key를 바꾸면 404 thread_not_found가 발생합니다. 중계 서비스가 key를 순환하면 먼저 404를 받고 전체를 다시 전송하게 됩니다." — @ak12kpoot (프록시 동작에 관한 중국 개발자 메모)
스레드 하나는 하나의 키에 고정하거나, 키를 풀링하는 경로에서는 threads를 우회하는 편이 낫다.
지원 환경과 제약 사항, 지금 도입할지 판단하는 법
Message Threads는 Claude API, AWS의 Claude Platform, Anthropic이 관리하는 Google Cloud Claude Models, Microsoft Foundry의 Claude에서 사용할 수 있다. 베타 대상은 모든 모델이며 별도 모델 허용 목록이나 명시된 대기 명단은 없다.
출시 계획에서는 지원하지 않는 영역이 더 중요하다.
| 영역 | 상태 |
|---|---|
| Amazon Bedrock | 지원하지 않음 |
| Message Batches | 지원하지 않음 — 배치 내 thread 항목은 실패 |
| 토큰 계산 엔드포인트 | 지원하지 않음 — 전체 이력을 직접 계산해야 함 |
| Compaction / context editing | 지원하지 않음(keep all을 사용한 clear_thinking 제외) |
| Zero data retention, HIPAA-ready, inference hooks | 사용 대상이 아님 |
| 스레드 관리 API | 없음 — 스레드 목록 조회, 읽기, 삭제 불가 |
도입 판단 체크리스트
- 지금 threads를 쓸 경우: 5분 이내 간격으로 수십 턴을 수행하는 활성 코딩 에이전트, 스크린샷을 쓰는 computer-use 루프, 문서 중심 워크플로라면 적합하다. Prompt Caching 및 재생 경로와 함께 구성하자.
- 당분간 건너뛸 경우: 사람이 천천히 진행하는 채팅, 중단되는 워크플로, 배치 파이프라인, ZDR/HIPAA 워크로드, Bedrock 배포 환경에는 맞지 않는다.
- 함께 쓸 때 확인할 점: 모든 요청의 최상위
cache_control은 4개 중단점 제한에 포함된다. 생성 시system/tools의 중단점은 continuation마다 다시 계산된다. 제한을 넘기면thread_unsupported_request가 반환되므로, 둘을 함께 활성화하기 전에 중단점을 통합해야 한다.
함께 보기: Claude API 가격 가이드 2026, Claude Skills API 가이드.
FAQ
어떤 베타 헤더와 파라미터가 필요한가?
스레드의 모든 요청에 anthropic-beta: message-threads-2026-08-12를 보낸다. 첫 호출에는 thread: { "type": "create" }를, 이후에는 thread: { "type": "continue", "previous_message_id": "<last response id>" }를 사용하면 된다.
스레드가 만료되면 어떻게 되나?
다음 continuation에서 404 thread_not_found가 반환된다. 전체 messages와 기존 system/tools를 새 create 요청으로 다시 보낸다. 유휴 만료 시간은 5분이며, 마지막 사용 후 늦어도 1시간 안에 삭제된다.
스레드를 목록으로 보거나, 검사하거나, 삭제할 수 있나?
없다. Messages API threads에는 관리 API가 제공되지 않는다. 로컬에 보관한 이력만이 유일한 영구 기록이다.
Amazon Bedrock에서도 동작하나?
아니다. 지원되는 환경은 Claude API, AWS Claude Platform, Microsoft Foundry, Anthropic이 관리하는 Google Cloud다. Bedrock 요청은 전체 이력을 보내는 방식으로 유지해야 한다.
스레드 중간에 system prompt나 tools를 바꿀 수 있나?
안 된다. 새 system/tools를 적용하려면 새 스레드를 만들어야 한다. continuation에서 변경된 값을 보내면 thread_fingerprint_mismatch가 발생한다. model, tool_choice, thinking 설정도 마찬가지다.
스트리밍, tools, MCP와 함께 쓸 수 있나?
가능하지만 규칙이 있다. continuation 전에 message_stop를 기다리고, 매 턴 MCP URL/토큰과 container ID를 다시 보내야 한다. 또한 fallbacks는 모든 요청에 보내거나 아예 보내지 않아야 한다. fallback 모델의 응답은 저장되지 않으므로 재생해야 한다.