2026년 11월 2일, Anthropic의 Messages API에 대화 기록을 서버 측에서 유지하는 message threads가 베타로 제공되었습니다.
기존의 Messages API는 stateless(상태 비저장) 방식이었습니다. 매번 요청 시 과거 대화 기록 전체를 포함해야 했습니다. message threads를 사용하면, API가 대화 기록을 서버 측에 보관합니다. 두 번째 요청부터는 새로운 메시지만 보내면 됩니다.
이를 통해 얻을 수 있는 효과는 다음 두 가지입니다.
- 요청 크기가 작아짐
- 첫 토큰이 반환되기까지의 시간(TTFT)이 단축됨
📌 영향을 받는 사람
- 긴 대화를 다루는 채팅 앱 개발자
- 툴 호출을 반복하는 에이전트 루프 구현자
- Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude in Microsoft Foundry 중 Messages API를 사용하는 모든 사용자
이번 기능은 베타 제공이며, 이용하려면 베타 헤더 지정이 필요합니다. 기존 코드는 아무것도 변경하지 않아도 계속 작동하므로 대응이 필수적이지는 않습니다. 다만, '5분 만료'라는 사양이 있습니다. 채택할 경우, 이 부분을 고려한 설계가 필요합니다.
| 항목 | 내용 |
|---|
| 기능명 | message threads |
| ... | |
| |
| 삭제 | 마지막 사용으로부터 1시간 이내 |
상태 비저장(stateless) API에서는 대화가 길어질수록 매번 보내야 하는 데이터가 늘어납니다. 에이전트 루프의 경우, 툴 호출과 결과의 왕복이 수십 번에 달하기도 합니다. 이 경우, 동일한 기록을 여러 번 다시 전송하게 됩니다.
message threads에서는 기록을 서버 측에 보관합니다. 클라이언트가 보내는 것은 차분(diff)만이기 때문에 요청 크기가 작아집니다. 그만큼 TTFT도 단축됩니다.
이 기능에서 가장 주의해야 할 점은 스레드의 수명입니다.
- 마지막 요청으로부터 5분 만료됨 -
- 마지막 사용으로부터 1시간 이내에 삭제됨
⚠️ 주의
5분을 초과하여 간격이 벌어지는 처리에서는 스레드가 만료됩니다. 예를 들어, 사용자 입력 대기 시간이 긴 채팅이나, 시간이 오래 걸리는 외부 처리를 거치는 에이전트가 이에 해당합니다. 이러한 처리에서는 만료 후에 대화를 재구성하는 처리가 필수입니다.
재구성을 위해서는 클라이언트 측에도 대화 기록의 사본이 필요합니다. 서버 측에 있으니 안심하고 생각하여, 로컬 기록을 버려서는 안 됩니다.
- 대상 파악: 긴 대화나 에이전트 루프가 있는지 확인합니다. 짧은 단발성 상호작용이 중심이라면 효과는 제한적입니다. -
- 검증 환경에서 테스트: 베타 헤더
message-threads-2026-08-12를 붙여 요청 크기와 TTFT가 어떻게 변하는지 측정합니다. -
- 만료 대응 구현: 5분을 초과하여 간격이 벌어질 가능성이 있다면, 대화 재구성 처리를 추가합니다. -
- 본격 배포는 신중하게: 베타 버전이므로 사양이 변경될 수 있습니다. 본격 배포 시에는 기존 방식(conventional way)으로 폴백(fallback)할 수 있도록 해두는 것이 안전합니다. -
- 사용 환경 확인: 대응 환경은 위에 언급된 4가지입니다. 그 외의 환경에서는 전제하지 마십시오.
💡 Tips
팀에서 CLAUDE.md를 운영하고 있다면, 다음과 같은 방침을 추가하면 AI 코딩 지원도 일관된 구현이 쉬워집니다. ## Claude API / Messages API 이용 방침 - 긴 대화나 에이전트 루프에서는 message threads (베타 헤더: message-threads-2026-08-12) 사용을 검토한다 - 두 번째 요청부터는 새로운 메시지만 보내면 된다 - 스레드는 마지막 요청으로부터 5분 만료, 마지막 사용으로부터 1시간 이내에 삭제되므로, 만료 시 대화 재구성 처리를 구현한다 - 대응 환경: Claude API, AWS, Google Cloud (Anthropic managed), Microsoft Foundry
⚠️ 주의
제공된 정보에는 스레드 생성 방법이나 식별자 전달 방식과 같은 구체적인 요청 사양이 포함되어 있지 않습니다. 아래는 공개 정보를 바탕으로 확인된 범위(베타 헤더 이름, 만료 동작)에 따른 설계의 개요입니다.
... 부분과 함수명은 설명용 가정이므로, 실제 파라미터명은 공식 문서를 통해 확인해 주십시오.
import anthropic
client = anthropic.Anthropic()
history = []
...
import anthropic
client = anthropic.Anthropic()
BETA = "message-threads-2026-08-12"
...
핵심 포인트는 세 가지입니다.
-
이력(History)은 클라이언트에도 보관: 만료되어 재작성이 필요하기 때문입니다.
-
만료를 예외로 처리: 에러 발생 시 분기 처리를 처음부터 설계에 포함합니다.
-
베타 헤더는 한 곳에서 관리: GA 전환이나 버전 업데이트 시 교체가 용이해집니다.
-
Messages API에 서버 측 대화 저장 기능인 message threads가 베타로 추가되었습니다.
- 사용을 위해서는 베타 헤더
message-threads-2026-08-12가 필요합니다.
- 두 번째 요청부터는 새로운 메시지만 보내면 되므로, 요청 크기가 작아지고 TTFT(Time To First Token)도 단축됩니다.
- 긴 대화나 에이전트 루프에서 특히 효과를 기대할 수 있습니다.
-
스레드는 마지막 요청 시점으로부터 5분 후에 만료되며, 최종 사용 후 1시간 이내에 삭제됩니다. 5분을 초과하는 간격으로 처리를 할 경우, 대화를 처음부터 다시 만드는(재구성) 처리가 필수적입니다.
- 지원 환경은 Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude in Microsoft Foundry 등입니다.
-
기존 코드에 영향을 주지 않으며, 적용은 선택 사항입니다. 먼저 검증 환경에서 크기와 TTFT의 변화를 측정하는 것을 권장합니다.
베타 기능이므로 사양은 향후 변경될 수 있습니다. 도입 전에 공식 문서를 통해 최신 사양을 확인해 주십시오.
