클로드 API 메시지 스레드 베타 시작: 바뀐 점과 지금 할 일

클로드 API 메시지 스레드는 긴 대화와 에이전트 루프에서 매번 전체 대화를 다시 보내지 않고, 새 메시지만 보내게 해 주는 베타 기능이다. Anthropic은 2026년 11월 2일 Claude Platform 릴리스 노트에 이 기능을 올리며, 요청이 작아지고 첫 토큰이 나오기까지의 시간이 줄어든다고 밝혔다.

클로드 API 메시지 스레드, 무엇이 달라졌나

상담원과 통화할 때 전화를 걸 때마다 지난 통화 내용을 처음부터 다시 읽어 준다고 생각해 보면 답답하다. 지금까지 Messages API가 그랬다. 대화가 길어질수록 매 턴 같은 내용을 통째로 다시 올려야 했다. 메시지 스레드는 상담원이 통화 내용을 잠깐 메모해 두는 것과 비슷해서, 다음 통화에서는 새로 한 말만 전하면 된다. 다만 메모는 오래 보관되지 않고, 사라지면 처음부터 다시 읽어 줘야 한다.

공식 문서에 따르면 메시지 스레드가 없으면 매 턴 대화 전체를 다시 올리고, API도 그 전체를 다시 검증하고 토큰으로 나눈다. 스레드를 쓰면 이 작업 대부분이 새 턴에만 적용된다. 그래서 대화가 길어져도 요청이 작고 첫 토큰 시간이 낮고 안정적으로 유지되며, 도구를 반복 호출하는 긴 에이전트 루프에서 효과가 가장 크다고 문서는 설명한다.

메시지 스레드 베타 기본 정보

항목	내용
상태	베타
베타 헤더	message-threads-2026-08-12
사용 가능한 곳	Claude API, Claude Platform on AWS, 구글 클라우드의 Claude(Anthropic 관리형), Microsoft Foundry
가격·속도 제한	속도 제한과 가격 모두 바뀌지 않음
스레드 만료	마지막 요청 5분 뒤, 마지막 사용 후 늦어도 1시간 안에 삭제
제로 데이터 보존(ZDR)	해당 없음

지원 모델은 Claude Opus 5.5, Sonnet 5.5, Haiku 5.5부터 Opus 4.5와 Sonnet 4.5까지 문서의 모델 목록에 모두 올라 있다. 구글 클라우드에서는 Anthropic이 관리하는 쪽에서만 베타로 제공되므로, 이 관리 방식이 무엇인지는 구글 클라우드 클로드 Anthropic 관리형 정식 출시 글에서 확인한다.

클로드 API 메시지 스레드 쓰는 법: 만들기와 이어가기

첫 요청은 지금처럼 전체 대화와 system, tools를 보내되 "thread": {"type": "create"}를 더한다. 두 번째부터는 새 메시지만 보내고 "thread": {"type": "continue", "previous_message_id": "<이전 응답 id>"}를 넣는다. 이어가기 요청에는 system과 tools를 넣지 않는다. 스레드가 만들 때의 값을 기억하고 있고, 넣으면 null이어도 400 오류가 난다.

파이썬 SDK에서는 이 두 요청이 다음과 같이 나온다. 공식 문서의 예시를 줄였다.

first = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=1024,
    system="You are a support agent for Acme.",
    messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
    thread={"type": "create"},
    betas=["message-threads-2026-08-12"],
)

second = client.beta.messages.create(
    model="claude-opus-5-5", max_tokens=1024,
    messages=[{"role": "user", "content": "How long does standard shipping usually take?"}],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

직접 요청을 짜기 번거로우면 SDK의 스레드 도우미를 쓴다. client.beta.messages.thread(...)로 도우미를 만들고 thread.send(메시지)를 턴마다 부르면 베타 헤더 추가, 만들기와 이어가기 전환, system·tools 생략을 도우미가 처리한다. 이 도우미는 대화 사본을 메모리에만 두므로 프로세스가 끝나도 대화가 남아야 한다면 사본을 직접 저장해야 한다.

요청마다 바뀌어도 되는 값과 안 되는 값이 나뉜다. 문서의 구분은 아래와 같다.

이어가기 요청에서 필드별 규칙

구분	필드	규칙
만들 때만	system, tools	이어가기 요청에 넣으면 400 오류
고정	model, tool_choice, thinking, 최상위 cache_control 등	매 요청 같은 값, 다르면 thread_fingerprint_mismatch 400 오류
자유	max_tokens, stop_sequences, stream, metadata, service_tier	턴마다 바꿔도 됨

시스템 프롬프트나 도구를 바꾸고 싶으면 스레드를 새로 만들어야 한다. 프롬프트 캐싱도 자동으로 켜지지 않는다. 문서는 매 요청에 같은 최상위 cache_control을 보내 턴마다 캐시하라고 안내하고, thread가 있는 요청에는 cache_control 표시를 최대 4개까지 둘 수 있다고 한다.

스레드가 사라졌을 때: 404와 다시 보내기

스레드는 서버에 잠깐 있는 임시 보관소라서 사라질 수 있다는 전제로 짜야 한다. 문서에 따르면 마지막 요청 5분 뒤에 만료되고, 저장된 응답이 생길 때마다 5분이 다시 시작된다. 이어가기 요청이 error.details.error_code가 thread_not_found인 404를 돌려주면, 내가 가진 전체 대화를 system, tools와 함께 새 만들기 요청으로 다시 보내고 그 응답의 id부터 이어가면 된다. SDK 도우미는 이 다시 보내기를 자동으로 한다.

만료 말고도 404가 나는 경우가 있다. 이전 응답이 아직 생성 중이거나, 응답이 저장되지 않았거나(예: 도구 호출이 max_tokens에서 잘린 응답), 다른 조직·워크스페이스·사용자가 요청한 경우다. 공식 문서에 따르면 404 응답에는 이유가 담기지 않으므로 원인을 가리기보다 항상 전체 대화를 다시 보내는 길을 만들어 둔다. 모델 이름이 틀려도 404가 나니 다시 보내기 전에 error_code를 먼저 본다.

스레드 요청에서 나오는 오류

상태	error_code	할 일
404	thread_not_found	전체 대화를 새 만들기 요청으로 다시 보낸다
400	thread_fingerprint_mismatch	고정 필드를 같은 값으로 맞추거나 새 스레드를 만든다
400	thread_already_continued	가장 최근 응답 id에서 이어간다, 응답을 못 받았다면 다시 보낸다
400	thread_continue_in_flight	진행 중인 요청이 끝나길 기다리거나 다시 보낸다
400	thread_unsupported_request	지원하지 않는 기능을 빼거나 thread 없이 전체 대화를 보낸다

응답 id는 한 번만 이어갈 수 있고, 스레드는 뒤로만 쌓인다. 앞쪽 메시지를 고치거나 갈래를 나누려면 새 스레드를 만든다. 스트리밍을 쓴다면 message_start에서 id가 먼저 오지만 message_stop을 받은 뒤에 이어가야 한다. 거절(stop_reason: "refusal") 응답 뒤에는 공식 문서가 그 스레드를 이어가지 말라고 안내한다. 거절 응답의 과금과 재시도 기준은 Claude API 거부 응답 과금 기준과 재시도 점검법에서 따로 정리했다. 거절 뒤에는 거절을 부른 턴을 빼거나 바꿔 새 스레드를 만든다.

내 서비스도 해당되나: 쓸 수 없는 경우와 데이터 보관

메시지 스레드는 일부 기능과 함께 쓸 수 없다. 공식 문서가 지원하지 않는다고 밝힌 것은 메시지 배치, 토큰 세기, 컴팩션(대화 요약), 컨텍스트 편집(clear_thinking_20251015의 keep: "all" 제외), HIPAA 대응을 켠 조직, 인퍼런스 훅을 켠 조직이다. 인퍼런스 훅이 무엇이고 누가 켜는 기능인지는 클로드 인퍼런스 훅 정식 전환 글에 정리했다. 지원하지 않는 요청은 대부분 thread_unsupported_request 400 오류로 거절된다.

데이터 보관은 개인정보를 다루는 서비스라면 반드시 읽어야 한다. 문서는 스레드가 대화, system, tools를 서버 메모리에 서버 관리 키로 암호화해 두고, 영구 저장소에는 쓰지 않으며, 마지막 사용 후 늦어도 1시간 안에 지운다고 밝힌다. 그래도 이 기능은 제로 데이터 보존(ZDR) 대상이 아니다. 계약에서 제로 데이터 보존이 조건이라면 이 기능을 켜기 전에 계약 담당자와 확인하는 편이 안전하다. 같은 문서에 따르면 스레드는 파일을 참조로만 들고 있으므로 대화가 쓴 파일은 스레드를 쓰는 동안 계속 접근 가능해야 한다.

적용 전후 효과를 모니터링 도구로 비교하려면 클로드 API OpenTelemetry 내보내기 베타 글의 설정 순서를 참고한다.

지금 할 일과 앞으로 확인할 점

1. 운영 코드가 아니라 시험용 흐름 하나에 먼저 적용한다. 긴 대화 챗봇이나 도구 호출을 여러 번 하는 에이전트가 좋다.
2. 베타 헤더 message-threads-2026-08-12를 만들기·이어가기 요청 모두에 붙인다.
3. 내 쪽에 전체 대화 사본을 저장하고, 404가 나면 새 만들기 요청으로 다시 보내는 길을 먼저 만든다.
4. 같은 대화를 스레드 없이 보냈을 때와 스레드로 보냈을 때의 요청 본문 크기와 첫 토큰 시간을 같은 조건에서 비교한다. 요청 크기는 내 서버의 송신 로그로, 첫 토큰 시간은 스트리밍 시작까지 걸린 시간을 직접 재서 본다.

작은 실험은 이렇게 한다. 같은 질문 10개를 이어서 보내는 스크립트를 스레드 없이 한 번, 스레드로 한 번 돌려 10번째 요청의 본문 크기와 첫 토큰까지의 시간을 적는다. 숫자는 환경마다 다르므로 내 서비스에서 직접 잰 값만 믿는다. 성공 기준은 두 가지다. 이어가기 요청 본문에 새 메시지만 들어가고도 응답이 정상으로 오는지, 5분 넘게 쉬었다가 보냈을 때 다시 보내기가 자동으로 이어지는지 본다. 가격과 속도 제한은 그대로이고, 아직 베타라서 제공 방식이 바뀔 수 있으니 릴리스 노트에서 정식 전환과 지원 범위 변경을 확인한다.

자주 묻는 질문

메시지 스레드를 쓰면 API 요금이 줄어드나?

공식 문서는 스레드가 가격과 속도 제한을 바꾸지 않는다고 밝힌다. 줄어드는 것은 요청 크기와 첫 토큰 시간이다.

스레드 내용을 조회하거나 지울 수 있나?

스레드를 나열·조회·삭제하는 API는 없다. 마지막 사용 후 늦어도 1시간 안에 서버가 지운다.

매니지드 에이전트의 세션 스레드와 같은 기능인가?

다른 기능이다. 공식 문서도 메시지 스레드와 클로드 매니지드 에이전트의 세션 스레드가 다르다고 따로 밝힌다.

구독형 요금제에서는 쓸 수 없나?

문서에서 확인되는 사용처는 Claude API, Claude Platform on AWS, 구글 클라우드의 Claude(Anthropic 관리형), Microsoft Foundry뿐이다. 구독형 요금제의 앱에서 켜는 설정은 문서에 나오지 않는다. 이 기능은 Messages API 요청에 thread 항목과 베타 헤더를 직접 넣는 방식이므로, API를 호출하는 코드를 짜는 개발자용 기능으로 보는 것이 맞다. 구독형 앱에서 쓸 수 있는지는 공식 문서에 근거가 없어 단정하지 않는다.