메시지 스레드

“Message thread”(메시지 스레드)를 사용하면 요청이 더 작아지고, 대화가 길어져도 “time to first token”(첫 토큰까지의 시간)이 더 낮고 안정적으로 유지됩니다. 스레드는 긴 에이전트 루프에서 가장 큰 도움이 됩니다. 스레드가 없으면 매 턴마다 전체 대화를 다시 업로드하고, API는 그 전체를 다시 검증하고 토큰화합니다. 스레드를 사용하면 이 작업의 대부분이 새 턴에만 적용됩니다.

“Message thread”(메시지 스레드)는 대화를 짧은 시간 동안 서버에 유지합니다. 전체 대화를 시스템 프롬프트 및 도구와 함께 한 번 보냅니다. 이후의 각 턴에서는 새 메시지와 이전 응답의 id만 보냅니다. API는 모델을 호출하기 전에 대화를 다시 구성합니다. Messages API 요청에 매개변수 하나, thread를 추가하면 됩니다. 응답은 일반적인 메시지입니다.

메시지 스레드의 작동 방식

• 생성. 지금처럼 전체 대화, system, tools를 포함하여 첫 번째 요청을 보내고, "thread": {"type": "create"}를 추가하세요. API는 Claude의 응답을 포함한 대화를 응답 id 아래에 저장합니다.
• 계속. 이전 응답 이후의 메시지만 보내고, "thread": {"type": "continue", "previous_message_id": "<previous id>"}를 추가하세요. 요청에서 system과 tools는 제외하세요. 스레드는 생성 요청의 값을 유지합니다. 다음 턴에는 각각의 새 응답 id를 사용하세요.
• 재전송. 스레드는 최선의 노력(best-effort) 방식으로 제공됩니다. 스레드는 마지막 요청 후 5분이 지나면 만료되며, API는 마지막 사용 후 1시간 이내에 스레드를 삭제합니다. API가 저장하는 각 응답마다 5분이 다시 시작됩니다. API가 더 이상 스레드를 계속할 수 없으면 계속 요청은 404 오류를 반환합니다. 새 생성 요청으로 전체 대화를 다시 보내고, 해당 응답의 id에서 계속하세요. SDK 스레드 헬퍼가 이 재전송을 대신 수행합니다(SDK 헬퍼의 동작 방식 참조). 폴백 모델의 응답 이후에는 스레드에서 폴백 사용하기를 참조하세요.

애플리케이션이 대화의 기준 원본(source of truth)으로 유지됩니다. 모든 메시지의 사본을 직접 보관하고, 처음부터 재전송 경로를 구축하세요. 생성 요청이든 계속 요청이든, 어떤 응답도 API가 해당 턴을 저장했는지 알려주지 않습니다. 이는 다음 계속 요청에서 알게 됩니다. SDK 스레드 헬퍼는 헬퍼 객체가 존재하는 동안 이 사본을 메모리에 보관하며, 다른 곳에는 저장하지 않습니다. 대화가 프로세스보다 오래 유지되어야 한다면 직접 사본을 보관하세요.

SDK로 스레드 사용하기

SDK에는 스레드 요청을 대신 구성해 주는 스레드 헬퍼가 있습니다. Messages 요청과 동일한 필드로 헬퍼를 생성한 다음, 한 번에 한 턴씩 보내세요. 헬퍼는 전체 대화를 메모리에 유지합니다.

이 예제에는 두 개의 턴이 있습니다. 헬퍼는 첫 번째 턴에서 스레드를 생성하고 두 번째 턴에서 이를 계속하며, 베타 헤더도 자동으로 추가합니다. 최상위 cache_control은 선택 사항입니다. 이는 각 턴에서 프롬프트 캐싱을 요청합니다(스레드에서의 프롬프트 캐싱 참조). 이것이 없어도 이후의 각 턴은 새 메시지만 보내지만, 캐시 중단점을 직접 추가하지 않는 한 아무것도 캐시되지 않습니다.

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?"}
)

for block in second.content:
    if block.type == "text":
        print(block.text)

thread 필드를 직접 보내기

예를 들어 cURL, CLI 또는 SDK의 일반적인 create 메서드를 사용하여 스레드 요청을 직접 구성하려면, 각 요청에 thread 필드를 추가하세요.

스레드의 모든 요청에 message-threads-2026-08-12 베타 헤더를 보내세요.

이 예제는 첫 번째 턴에서 스레드를 생성하고 두 번째 턴에서 이를 계속합니다. 최상위 cache_control은 각 턴에서 프롬프트 캐싱을 요청합니다. 이는 대화가 최소 캐시 가능 길이보다 길어지면 적용됩니다.

client = anthropic.Anthropic()

# 턴 1: 전체 대화를 보내고 스레드를 생성합니다
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"},
    betas=["message-threads-2026-08-12"],
)

# 턴 2: 새 메시지와 턴 1 응답의 id만 보냅니다.
# system과 tools는 생략하세요: 스레드가 이를 유지합니다.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

각 요청에서 보낼 내용

API는 MCP 서버 URL, MCP 인증 토큰 또는 컨테이너 id를 저장하지 않습니다. 이를 사용하는 모든 요청에서 mcp_servers와 container를 보내세요. MCP 인증 토큰은 요청 간에 변경될 수 있습니다.

SDK 스레드 헬퍼는 계속 요청에서 system과 tools를 대신 제외하고, 고정 필드는 매 턴마다 다시 보냅니다.

서버 측 폴백을 사용하는 경우, 스레드의 모든 요청에서 fallbacks 필드를 보내거나 어떤 요청에서도 보내지 마세요. 스레드에서 폴백 사용하기를 참조하세요.

생성 전용 필드나 고정 필드를 변경하려면 새 스레드를 시작하세요. 새 값과 함께 생성 요청으로 전체 대화를 보내면 됩니다.

Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5에서는 system 또는 tools를 변경하면 대화에 이미 있는 thinking 및 redacted_thinking 블록이 무효가 되며, 생성 요청이 400 오류를 반환할 수 있습니다. 이를 피하려면 보내는 대화에서 모든 thinking 및 redacted_thinking 블록을 제외하세요. 그러면 모델은 해당 이전 추론 없이 응답합니다. 편집으로 간주되는 것, prefix_mismatch_behavior가 설정되지 않은 경우, API가 유효하지 않은 블록을 처리하는 방식을 참조하세요.

계속 요청에서는 새 메시지만 보내세요. API는 이를 이미 보유한 메시지와 대조하지 않습니다. 다시 보낸 메시지는 대화에 두 번 나타날 수 있으며, 요청이 오류를 반환할 수도 있습니다. 예를 들어 이전 응답으로 시작하는 계속 요청은 오류를 반환합니다.

새 메시지는 일반적으로 user 메시지로 시작합니다. 즉, 다음 사용자 턴이거나 이전 응답의 tool_use에 응답하는 tool_result 블록입니다. 응답이 stop_reason: "pause_turn"으로 중지되면, 해당 응답의 id와 빈 messages 목록("messages": [])을 사용한 계속 요청으로 재개하세요. 해당 요청이 404 오류를 반환하면, 일시 중지된 응답을 포함한 전체 대화를 새 생성 요청으로 재전송하세요. 턴이 일시 중지된 동안에는 새 user 메시지를 보내지 마세요. API가 이를 거부합니다. SDK 스레드 헬퍼를 사용하는 경우, 메시지 없이 send()를 호출하세요. 헬퍼가 이 요청을 보내고 404 오류 시 재전송합니다.

스레드는 추가 전용이며, 각 응답 id는 한 번만 계속할 수 있습니다. 항상 스레드의 최신 응답 id에서 계속하세요. 이전 메시지를 편집하거나 분기하려면 생성 요청으로 새 스레드를 시작하세요. 이전 턴을 요약으로 대체하려면 대화 압축하기를 참조하세요.

스레드에서의 프롬프트 캐싱

스레드는 프롬프트를 자동으로 캐시하지 않습니다. 프롬프트 캐싱은 스레드가 없을 때와 동일하게 작동합니다. 캐시 중단점의 위치는 사용자가 선택합니다.

각 턴을 캐시하려면 앞의 예제처럼 스레드의 모든 요청에서 최상위 cache_control을 보내세요. API는 이를 각 요청의 messages 중 캐시할 수 있는 마지막 블록에 적용합니다. 그러면 각 턴은 이전 대화를 캐시에서 읽고 새 턴을 캐시에 씁니다. 최상위 cache_control은 고정 필드이므로 모든 요청에서 동일한 값을 보내세요.

블록에 cache_control 중단점을 직접 배치할 수도 있습니다.

• 생성 요청에서 보낸 중단점은 tools, system 또는 마지막 블록 이전의 메시지 블록에 있는 경우 이후의 모든 턴에서 계속 작동합니다. 요청의 messages의 마지막 블록에 있는 중단점은 해당 요청에서 캐시를 기록합니다. 각 새 턴을 캐시하려면 모든 요청에 중단점을 보내세요. 중단점이 없는 요청도 대화의 일부를 캐시에서 읽을 수 있습니다.
• 계속 요청은 이전 메시지를 다시 전송할 수 없으므로, 중단점을 전송한 후에는 이동하거나 제거할 수 없습니다.
• thread가 포함된 요청은 최대 4개의 cache_control 중단점을 가질 수 있습니다. 최상위 cache_control도 하나로 계산됩니다. 생성 요청의 system 및 tools에 있는 중단점은 모든 계속 요청에서 다시 계산됩니다. 저장된 이전 메시지의 중단점은 계산되지 않습니다. 중단점이 하나라도 초과되면 thread_unsupported_request 코드와 함께 400 오류가 반환됩니다.
• 메시지 블록에 직접 중단점을 배치하는 경우, 새 생성 요청에서 대화를 재전송할 때 이전 메시지의 중단점을 제거하고 마지막 블록에 하나를 유지하여 요청이 4개 제한 내에 머물도록 하세요.

스트리밍

스레드는 스트리밍과 함께 작동합니다. 응답 id는 message_start 이벤트에서 도착하지만, message_stop 이벤트를 받은 후에만 그 id에서 계속하세요. 그보다 먼저 보낸 계속 요청은 404 오류를 반환할 수 있습니다.

계속 요청의 스트림이 message_stop 전에 끊기면 동일한 계속 요청을 다시 보내세요. 해당 요청이 thread_already_continued 또는 thread_continue_in_flight 오류를 반환하면, 새 생성 요청으로 전체 대화를 재전송하세요.

서버가 아직 응답을 생성하는 중이거나 서버가 응답을 저장한 후에 연결이 끊겼을 수 있습니다. 그래서 API가 재시도를 거부할 수 있습니다. 새 생성 요청으로 전체 대화를 재전송하는 것은 항상 안전합니다.

SDK 스레드 헬퍼는 스트림이 중단된 후 계속 요청을 재시도하지 않습니다. SDK 헬퍼의 동작 방식을 참조하세요.

스레드를 계속할 수 없을 때 복구하기

API가 스레드를 계속할 수 없으면 계속 요청은 error.details.error_code가 thread_not_found로 설정된 404 오류를 반환합니다. 응답은 그 이유를 알려주지 않습니다. 원인에는 다음이 포함됩니다.

• 스레드가 만료되었습니다.
• API가 이전 턴을 제공했지만 저장하지 않았습니다. 예를 들어 API는 max_tokens로 인해 잘린 도구 호출로 끝나는 응답을 저장하지 않습니다.
• 폴백 모델이 이전 응답을 작성했습니다. 스레드에서 폴백 사용하기를 참조하세요.
• 이전 응답이 아직 생성 중입니다.
• 요청이 다른 조직 또는 워크스페이스에서 왔습니다.
• 요청이 스레드를 생성한 사용자 또는 서비스 계정과 다른 사용자 또는 서비스 계정에서 왔습니다. 워크스페이스 키(레거시)로 생성된 스레드는 해당 키에 귀속되므로, 스레드 전체에 동일한 키를 사용하세요.
• 새 메시지가 저장된 대화가 수용할 수 없는 것을 추가합니다. 예를 들어 이미지가 없던 대화의 첫 번째 이미지는 이 오류를 반환할 수 있습니다.

복구하려면 자체 사본의 전체 대화를 system 및 tools와 함께 새 생성 요청으로 보내세요. SDK 스레드 헬퍼는 이 생성 요청을 자체적으로 한 번 보내며, 이때 이전 턴의 cache_control 중단점을 제외합니다. 사본의 이전 메시지에 cache_control 중단점이 있다면 먼저 제거하세요(스레드에서의 프롬프트 캐싱 참조). 그런 다음 새 응답 id에서 이어가세요. 이전 응답을 폴백 모델이 작성했다면 스레드에서 폴백 사용하기를 참조하세요. 소유권 관련 원인을 배제하려면 스레드의 모든 요청에 동일한 API 키와 워크스페이스를 사용하세요. Claude Platform on AWS에서는 스레드의 모든 요청을 해당 스레드를 생성한 IAM 역할 또는 IAM 사용자의 자격 증명으로 서명하세요.

존재하지 않는 모델에 대한 요청도 404 오류를 반환하므로, 재전송하기 전에 error.details.error_code를 확인하세요.

재전송 직후에도 계속 요청이 여전히 404 오류를 반환한다면, API가 해당 대화(예: 매우 큰 대화)를 저장하지 못하는 것일 수 있습니다. 이 경우 thread 없이 보내세요. SDK 스레드 헬퍼는 unsupported_request_behavior를 continue_unthreaded로 설정하여 생성하면 이 작업을 수행합니다. 그렇지 않으면 매 턴마다 재전송합니다.

거부 이후

응답에 stop_reason: "refusal"이 있으면 스레드를 이어가지 마세요. API가 이미 거부된 턴을 보관하고 있을 수 있으며, 계속 요청으로는 이를 제거할 수 없습니다. 거부의 원인이 된 턴을 생략하거나 표현을 바꾼 생성 요청으로 새 스레드를 시작하세요. 거부 및 폴백을 참조하세요. SDK 스레드 헬퍼는 이 작업을 자동으로 수행합니다. 거부된 턴을 유지하지 않으며, 다음 턴에서 새 스레드를 시작합니다.

스레드에서 폴백 사용하기

서버 측 폴백은 Claude API에서 스레드와 함께 사용할 수 있습니다. 스레드를 생성할 때 결정하세요. 스레드의 모든 요청에서 fallbacks를 보내거나, 어떤 요청에서도 보내지 마세요. fallbacks의 값은 요청 간에 변경될 수 있습니다. fallbacks를 추가하거나 제거하는 계속 요청은 thread_fingerprint_mismatch 코드와 함께 400 오류를 반환합니다.

스레드는 하나의 모델을 유지하므로, API는 폴백 모델이 작성한 턴을 저장하지 않습니다. 응답은 평소처럼 받지만, 그 id에서 계속할 수는 없습니다. 각 응답 후에 다음 단계를 따르세요.

1. stop_reason이 "refusal"이면 거부 이후를 따르세요.
2. 그렇지 않으면 usage.iterations에서 fallback_message 항목을 찾으세요. 스트림에서는 마지막 message_delta 이벤트에서 읽으세요. 항목이 없으면 평소처럼 스레드를 계속 진행하세요.
3. 있으면 폴백 모델이 응답을 작성한 것입니다. 해당 응답과 다음 메시지를 포함한 전체 대화를 새 생성 요청으로 보내세요. 이 요청에 server-side-fallback-2026-07-01 베타 헤더를 유지하세요. 다음 두 가지 요청 중 하나를 선택하세요.
   • 동일한 요청을 다시 보내기. model, fallbacks 및 기타 매개변수를 그대로 유지하세요. 요청한 모델이 응답하면 API가 새 스레드를 저장합니다. 폴백 모델이 응답하면 응답에 다시 fallback_message 항목이 포함되고 API는 이를 저장하지 않으므로, 다음 턴에서 이 단계를 반복하세요. 고정 라우팅이 이러한 요청을 폴백 모델로 바로 보낼 수 있으므로, 매 턴마다 전체 대화를 보내게 될 수 있습니다. SDK 스레드 헬퍼는 이 방식으로 동작합니다.
   • 폴백 모델에서 새 스레드 시작하기. model을 해당 fallback_message 항목의 model로 설정하고, fallbacks를 제외하고, 이 모델이 허용하는 매개변수를 사용하세요. API는 이 스레드를 즉시 저장하며, 스레드는 폴백 모델에 유지됩니다. 폴백 시도는 보낸 설정과 다른 설정으로 실행되었을 수 있으므로, API가 첫 번째 요청에서 복사한 값을 거부할 수 있습니다.
4. 해당 요청의 응답으로 1단계로 돌아가세요. 응답에 fallback_message 항목이 없으면, 해당 id로 새 스레드를 이어가세요.

고정 라우팅은 요청이 폴백된 후(생성 요청 또는 thread가 없는 요청) 시작됩니다. 약 1시간 동안, fallbacks를 포함하는 동일한 대화에 대한 이후 생성 요청을 요청한 모델을 시도하지 않고 폴백 모델로 바로 보낼 수 있습니다. API는 이러한 턴을 하나도 저장하지 않으며, 응답된 각 턴은 1시간을 다시 시작합니다. 계속 요청은 이 라우팅을 시작하지 않으며 사용하지도 않습니다. 조직 또는 워크스페이스가 ZDR(zero data retention) 또는 고객 관리형 암호화 키를 사용하는 경우 고정 라우팅은 적용되지 않습니다.

대화 압축하기

스레드는 추가 전용이므로 이전 턴을 요약으로 대체할 수 없습니다. 대화를 압축하려면 요약에서 새 스레드를 시작하세요. 코드에서 요약을 작성하고, 이를 system 및 tools와 함께 새 생성 요청에서 일반 메시지로 보내세요. 온디맨드 압축은 스레드와 함께 사용할 수 없습니다(스레드가 지원하지 않는 기능 참조).

SDK 헬퍼의 동작 방식

헬퍼가 대신 처리하는 작업:

• 스레드를 사용하는 모든 요청에 message-threads-2026-08-12 베타 헤더를 추가합니다.
• 첫 번째 턴에서 스레드를 생성하고 그 이후에는 스레드를 이어가며, 새 메시지만 보내고 system과 tools는 생략합니다.
• 계속 요청이 thread_not_found, thread_already_continued 또는 thread_continue_in_flight를 반환하면 새 생성 요청으로 전체 대화를 한 번 재전송합니다.
• 메시지 없이 send()를 호출하면 pause_turn 응답을 재개합니다.
• 거부 후에는 새 스레드를 시작합니다. 평소처럼 stop_reason: "refusal" 응답을 받지만, 헬퍼는 해당 턴을 유지하지 않고 그 호출에 전달한 메시지를 되돌립니다. thread.append(...)로 추가했거나 헬퍼를 생성할 때 전달한 메시지는 스테이징된 상태로 남습니다. 다음 턴에서는 이 메시지들을 거부된 턴 이전의 대화와 함께 새 생성 요청으로 보냅니다. 표현을 바꾼 메시지를 보내거나, 스테이징된 메시지가 거부의 원인이었다면 해당 메시지를 제외한 params로 새 스레드를 시작하세요.
• 폴백 모델의 응답 후에는 새 생성 요청을 보냅니다. 응답의 usage.iterations에 fallback_message 항목이 있으면, 헬퍼는 해당 응답을 유지하고 다음 턴에서 전체 대화를 새 생성 요청으로 보냅니다. 404 오류를 기다리지 않습니다. 해당 요청은 설정한 model과 fallbacks를 유지합니다.
• 이전 턴을 다시 보낼 때마다(예: 재전송 시 또는 포크의 첫 번째 턴에서) 해당 턴의 cache_control 중단점을 생략합니다. 가장 최근 메시지, system, tools 및 최상위 cache_control은 전달한 그대로 전송됩니다.

직접 처리해야 하는 작업:

• 폴백. API가 폴백 모델로 계속 응답하는 동안, API는 해당 턴을 하나도 저장하지 않으므로 헬퍼는 매 턴마다 전체 대화를 새 생성 요청으로 보냅니다. 요청한 모델로부터 응답을 받으면 다시 계속 요청으로 돌아갑니다. 대신 대화를 폴백 모델로 옮기려면, 스레드에서 폴백 사용하기에서처럼 해당 model을 지정하고 fallbacks를 제외한 params로 새 스레드를 시작하세요.
• 중단된 스트림. 응답 도중 스트림이 끝나면, 헬퍼는 완료된 블록과 도착한 텍스트를 유지하고 다음 턴에서 전체 대화를 새 생성 요청으로 보냅니다. 헬퍼는 자체적으로 재시도하지 않습니다. 대신 중단된 턴을 다시 보내려면 메시지 없이 send()를 호출하세요. 유지된 부분이 도구 호출로 끝나면 다음 메시지에서 이에 응답하세요. 스트림에 stop_reason: "refusal"이 표시된 후 스트림 읽기를 중단하면, 헬퍼는 해당 턴을 거부로 처리합니다.
• 기타 오류. thread_fingerprint_mismatch 및 thread_unsupported_request 오류는 코드로 전달됩니다. thread_unsupported_request 오류 후 thread 없이 계속하려면 unsupported_request_behavior를 continue_unthreaded로 설정하여 헬퍼를 생성하세요. 이 설정을 사용하면, 재전송 후 첫 번째 계속 요청이 다시 thread_not_found를 반환할 때도 헬퍼가 thread 사용을 중단합니다. API가 해당 대화를 저장하지 못할 수 있기 때문입니다. 이 설정이 없으면 헬퍼는 매 턴마다 재전송합니다. 자체 스레드를 생성하는 도구 러너는 기본적으로 이 설정을 사용합니다.

SDK의 베타 도구 러너도 기본적으로 스레드를 사용하며, 러너를 생성할 때 이를 끌 수 있습니다.

기타 헬퍼 메서드

스트리밍. 헬퍼는 스트림이 message_stop에 도달할 때 응답을 기록하므로, 스트림을 끝까지 읽으세요. 일찍 읽기를 중단하는 경우, 다음 턴에서 스레드를 사용할 수 있도록 스트림을 종료하세요.

• Python: with 블록을 벗어납니다.
• TypeScript: 루프를 벗어나거나 abort()를 호출합니다.
• Go: Close를 호출합니다.
• Java 및 Ruby: close()를 호출합니다.
• C#: 열거자를 dispose합니다. await foreach를 벗어나면 이렇게 됩니다.
• PHP: close()를 호출합니다.

C#에서는 스트림을 읽기 시작할 때 요청이 전송됩니다.

C#, Go, Java 및 PHP에서는 거부 후에도 thread.LastMessage가 여전히 이전 턴의 응답을 반환하며, 첫 번째 턴에서는 아무것도 반환하지 않습니다. 거부 내용은 스트림의 이벤트에서 읽으세요.

필드 변경. 업데이트는 아무것도 보내지 않으며 이후의 모든 턴에 적용됩니다. 스레드에 응답이 생긴 후에는 헬퍼가 system 또는 tools를 변경하는 턴을 거부하고, API는 다른 고정 필드의 변경을 거부합니다(각 요청에서 보낼 내용 참조). 이러한 필드 중 하나를 변경하려면 params에서 새 스레드를 시작하거나, 스레드를 포크하고 첫 번째 턴 전에 포크를 업데이트하세요.

포크. 포크는 대화, 필드, 요청 옵션을 복사하며 아무것도 보내지 않습니다. 포크의 첫 번째 턴은 새 생성 요청으로 전체 대화를 보내며, 그 이후 두 스레드는 독립적입니다. 포크는 항상 이전 응답이 아닌 전체 대화에서 시작합니다.

Params. params에는 헬퍼의 필드와 전체 대화가 들어 있습니다. 새 스레드를 시작하려면 params를 헬퍼를 생성하는 메서드에 전달하세요. 예를 들어 다른 system을 사용하거나(각 요청에서 보낼 내용 참조), 이후 턴을 삭제하도록 messages를 잘라낼 수 있습니다. params로 시작한 스레드는 cache_control 중단점을 포함하여 모든 메시지를 주어진 그대로 전송하므로, 제한인 4개를 넘지 않도록 하세요(스레드에서의 프롬프트 캐싱 참조). Ruby를 제외하고 params에는 요청 옵션이 포함되지 않으므로 요청 옵션을 다시 전달하세요.

구조화된 출력. 헬퍼를 생성할 때 출력 형식을 지정하세요. 이후 턴에서는 이를 변경할 수 없습니다. 파싱된 결과를 얻는 방법은 SDK에 따라 다릅니다:

• Python 및 TypeScript: thread.parse(...)를 호출하세요.
• C#: client.Beta.Messages.Thread<T>(...)로 헬퍼를 생성하세요.
• Go: Send는 Params.OutputConfig.Format.Schema가 가리키는 구조체로 언마샬링합니다.
• Java: thread(...)와 outputConfig(MyClass.class)로 헬퍼를 생성하세요.
• PHP: outputConfig가 모델 클래스를 지정하면 send()가 텍스트 블록에 parsed를 설정합니다.
• Ruby: thread(...)에 output_config: {format: MyModel}을 전달한 다음, reply.parsed_output을 읽으세요.

오류

API는 모델이 실행되기 전에 이 표의 오류를 반환합니다. 요청은 토큰을 사용하지 않으며, 스레드와 그 만료 시간은 변경되지 않습니다. error.type은 400 오류의 경우 invalid_request_error이고 404 오류의 경우 not_found_error입니다.

스레드 요청에 대한 일부 400 오류에는 error_code가 없습니다. 예를 들어 previous_message_id가 없는 계속 요청이나 system 또는 tools를 포함하는 계속 요청이 그렇습니다.

다음 예제는 오류 본문을 보여줍니다.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

스레드가 지원하지 않는 기능

스레드는 다음 기능을 지원하지 않습니다.

• Message Batches. thread를 포함하는 요청 항목은 배치 결과에서 invalid_request_error로 끝납니다.
• 토큰 카운팅. thread를 포함하는 토큰 카운팅 요청은 400 오류를 반환합니다. 대신 system 및 tools와 함께 전체 대화를 카운트하세요.
• 압축. 온디맨드 압축은 스레드와 함께 사용할 수 없습니다. thread를 포함하는 요청은 compaction 매개변수를 설정하거나 compact-2026-09-04 베타 헤더와 함께 compaction 블록을 보내면 400 오류를 반환합니다. 대화 압축하기를 참조하세요.
• 컨텍스트 편집. 단, keep: "all"을 사용하는 clear_thinking_20251015는 예외입니다.
• HIPAA 준비가 활성화된 조직.
• Inference hooks가 켜져 있는 조직.

API는 스레드가 지원하지 않는 대부분의 요청을 thread_unsupported_request 코드와 함께 400 오류로 거부합니다. error.details.unsupported가 있으면 여기에는 다음 값 중 하나가 들어 있습니다.

API는 이 목록에 값을 추가할 수 있습니다. 인식하지 못하는 값을 받으면 thread 없이 전체 대화를 보내세요. 이러한 조건 중 여러 개를 충족하는 요청은 그중 하나만 명시하는 오류를 받습니다.

제한 사항

• 스레드를 나열, 읽기 또는 삭제하는 API는 없습니다.
• 스레드는 Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), 및 Claude in Microsoft Foundry에서 사용할 수 있습니다.

가격 및 속도 제한

스레드는 가격이나 속도 제한을 변경하지 않습니다.

데이터 보존

메시지 스레드는 ZDR 적용 대상이 아닙니다. 이 기능을 사용해도 다른 ZDR 적용 대상 기능의 사용에는 영향을 주지 않습니다. API는 스레드를 서버 관리 키로 암호화하여 메모리에 보관하고, 영구 저장소에 절대 쓰지 않으며, 마지막 사용 후 1시간 이내에 삭제합니다.

스레드에는 API가 모델에 보내는 대화, 생성 요청의 system 및 tools, 그리고 이후 요청을 확인하는 데 사용하는 고정 필드의 지문(fingerprint)이 들어 있습니다. 스레드는 파일을 참조로 보관하므로, 스레드를 사용하는 동안 대화가 사용하는 모든 파일을 사용 가능한 상태로 유지하세요.

모든 기능의 ZDR 적용 여부는 API 및 데이터 보존을 참조하세요.

참고 항목

• 프롬프트 캐싱
• 스트리밍
• 오류

제공 여부

메시지 스레드은(는) 모든 모델에서 베타 상태입니다.

API 지원

베타 헤더를 사용하면 실험적 기능과 새로운 모델 기능이 표준 API에 포함되기 전에 액세스할 수 있습니다.