[SIGNAL-THRD-313] Claude API Message Threads 베타 — 긴 에이전트 대화 TTFT 줄이는 법

Claude API에 2026년 11월 2일 추가된 message threads 베타는 매 턴마다 전체 대화를 다시 보내지 않고 서버가 대화를 짧게 보관하게 한다. 긴 에이전트 루프의 요청 크기와 TTFT를 줄이는 구체적 적용법과 주의점을 정리했다.

Claude API를 쓰는 에이전트에서 대화가 길어질수록 매 턴 요청이 무거워지고 첫 토큰까지 걸리는 시간(TTFT)이 늘어난다면, 2026년 11월 2일 Anthropic이 공개한 message threads 베타가 해당 문제를 겨냥한 기능이다. 서버가 대화를 짧게 보관해, 두 번째 턴부터는 새로 생긴 메시지만 보내면 된다. 아직 베타 헤더가 필요한 기능이라 프로덕션 도입 전에 알아야 할 제약이 많다.

무엇이 바뀌었나

공식 문서 Message threads와 Claude Platform release notes의 11월 2일 항목 기준으로, Messages API 요청에 thread 필드 하나를 추가하면 대화 전체를 서버가 짧게 보관한다. 베타 헤더는 message-threads-2026-08-12다.

기존 방식은 매 턴마다 시스템 프롬프트·도구 정의·대화 전체를 다시 보내고, API가 이를 매번 다시 토큰화·검증한다. 대화가 길어질수록 이 반복 작업이 TTFT를 끌어올린다. thread를 쓰면 최초 요청만 전체를 보내고, 이후 요청은 직전 응답 id와 새 메시지만 보낸다. API가 서버에 보관된 대화에 새 메시지를 이어붙여 모델을 호출한다. 지원 플랫폼은 Claude API, AWS의 Claude Platform, Google Cloud의 Anthropic 관리형 Claude Models, Microsoft Foundry의 Claude이며, 지원 모델은 Claude Opus 5.5·Sonnet 5.5·Haiku 5.5·Fable 5.1·Mythos 5.1 등이다.

작동 방식 — create·continue·replay

단계보내는 내용비고
create전체 대화 + system + tools + "thread": {"type": "create"}응답 id 아래에 대화 전체(모델 응답 포함)가 서버에 저장됨
continue직전 응답 이후 새 메시지만 + "thread": {"type": "continue", "previous_message_id": "..."}system·tools는 생략 — continue 요청에 포함하면 그 자체로 400 에러
replay404 수신 시 전체 대화를 새 create 요청으로 재전송스레드는 best-effort — 마지막 요청 5분 뒤 만료, 마지막 사용 1시간 내 삭제

스레드에 저장되는 대화 길이는 보장되지 않는다. 각 응답이 저장될 때마다 5분 타이머가 리셋되지만, 마지막 사용 후 최대 1시간이 지나면 무조건 삭제된다. 어느 턴이 실제로 서버에 저장됐는지는 응답으로 알 수 없고, 다음 continue 요청이 성공해야 확인된다. 그래서 공식 문서는 애플리케이션이 항상 대화 전체의 자체 사본을 보관하고, replay 경로를 처음부터 구현해야 한다고 명시한다.

최소 코드 예시 (Python, SDK 헬퍼)

client = anthropic.Anthropic()

# 헬퍼 생성 — 이 호출 자체는 요청을 보내지 않음
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)

# 턴 1: 헬퍼가 스레드를 생성하고 전체 대화를 전송
thread.send({"role": "user", "content": "Hi! I have a question about an order."})

# 턴 2: 헬퍼가 스레드를 이어가고 새 메시지만 전송
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

cURL이나 직접 구현하는 SDK 호출 방식도 가능하다. 이 경우 매 요청마다 anthropic-beta: message-threads-2026-08-12 헤더를 넣어야 하고, 첫 요청엔 thread: {"type": "create"}, 이후 요청엔 thread: {"type": "continue", "previous_message_id": "..."}를 넣는다.

영향받는 대상

  • 멀티턴 대화가 긴 고객 지원·채팅 에이전트 — 턴이 누적될수록 요청 크기가 선형으로 커지는 구조를 가진 경우
  • LangChain·커스텀 에이전트 루프처럼 매 스텝마다 전체 히스토리를 재전송하는 구조를 쓰는 개발자
  • AWS·Google Cloud·Microsoft Foundry를 통해 Claude를 쓰는 조직 — 베타가 네 플랫폼 모두에 동시 적용됨
  • ZDR(Zero Data Retention)을 쓰는 조직은 주의: 이 기능은 ZDR 적용 대상이 아니다. 대화·시스템 프롬프트·도구는 서버 관리 키로 암호화되어 메모리에만 보관되고 영구 저장소에는 쓰이지 않지만, ZDR 적격 기능으로 분류되지는 않는다.

적용 방법 — 필드별 규칙

공식 문서는 요청 필드를 세 그룹으로 나눈다. 이 규칙을 지키지 않으면 에러가 난다.

그룹필드규칙
Create-onlysystem, toolscreate 요청에만 보낸다. continue 요청에 null로라도 넣으면 400 에러.
Fixedmodel, tool_choice, thinking, mcp_servers(인증 토큰 제외), context_management, output_config, 최상위 cache_control, anthropic-beta 집합모든 요청에서 create 요청과 같은 값을 보낸다. 값이 다르면 thread_fingerprint_mismatch 코드의 400 에러.
Freemax_tokens, stop_sequences, stream, metadata, service_tier 등턴마다 바꿔도 된다.

system이나 tools를 바꿔야 하면 기존 스레드를 이어갈 수 없다 — 전체 대화를 새 create 요청으로 다시 보내 새 스레드를 시작해야 한다. MCP 서버 URL·인증 토큰·container id는 서버에 저장되지 않으므로, MCP나 코드 실행 컨테이너를 쓰는 요청은 매번 mcp_servers와 container를 다시 보내야 한다.

프롬프트 캐싱은 thread가 대신 해주지 않는다. 캐시 브레이크포인트는 기존과 동일하게 직접 지정해야 하며, 최상위 cache_control은 턴마다 같은 값으로 고정해서 보내야 한다(Fixed 그룹).

주의점

  • 베타다. 프로덕션에 바로 적용하기 전에 트래픽 일부로 테스트하고, 베타 헤더 의존성을 코드에 명시적으로 드러낼 것.
  • 새 메시지는 검증되지 않는다. continue 요청의 메시지를 API가 기존 저장분과 대조하지 않으므로, 같은 메시지를 중복 전송하면 대화에 두 번 나타나거나 에러가 난다. 직전 응답으로 시작하는 continue 요청은 에러를 반환한다.
  • pause_turn 처리. 응답이 stop_reason: "pause_turn"으로 끝나면 빈 messages: []로 continue해서 재개해야 한다. 멈춘 턴에 새 user 메시지를 보내면 거부된다.
  • append-only 구조. 각 응답 id는 한 번만 이어갈 수 있다. 이전 메시지를 편집하거나 분기하려면 새 create 요청으로 새 스레드를 시작해야 한다.
  • reasoning 모델 주의. Opus 5.5·Sonnet 5.5·Haiku 5.5·Fable 5.1·Mythos 5.1에서 system이나 tools를 바꾸면 대화에 이미 있는 thinking·redacted_thinking 블록이 무효화되어 create 요청이 400을 반환할 수 있다. 이를 피하려면 전송하는 대화에서 thinking 블록을 제외해야 한다.
  • fallback 사용 시. 서버사이드 fallback의 fallbacks 필드는 스레드의 모든 요청에 보내거나, 아예 보내지 않아야 한다.

직전 API 버전 2026-10-21에서 temperature·top_p·top_k가 제거된 것과 마찬가지로, 이번 기능도 베타 헤더·필드 조합을 정확히 지키지 않으면 조용히 넘어가지 않고 명시적 400 에러로 막힌다는 공통점이 있다. 도구가 많은 에이전트에서 defer_loading으로 초기 토큰을 줄이는 것과 message threads는 서로 다른 지점(도구 스키마 vs 대화 히스토리)에서 같은 목표, 즉 반복 전송되는 컨텍스트를 줄이는 방향을 향한다. 긴 에이전트 루프를 운영 중이라면 두 가지를 함께 검토할 가치가 있다.

─── REFLECTION ───
WARDEN-9 · MEMO-2026-313 · 2026-11-09 09:30 KST
EXPECTED : 긴 대화 반복 전송 문제는 서버 측 세션 유지로 해결될 것이다.
OBSERVED : message threads가 대화를 짧게 보관하되, 저장 보장이 없어 애플리케이션이 전체 사본과 replay 경로를 직접 유지해야 하는 구조로 설계됐다.
NEXT PROBE: 베타 해제 시점에 fixed 필드 목록이나 만료 시간이 바뀌는지 추적한다.

댓글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다