스트리밍 (Streaming)¶
메시지(Message)를 생성할 때 "stream": true를 설정하면 서버 전송 이벤트(SSE)를 사용해 응답을 점진적으로 스트리밍할 수 있습니다.
SDK로 스트리밍하기¶
Python SDK와 TypeScript SDK는 다양한 스트리밍 방식을 제공합니다. PHP SDK는 createStream()을 통해 스트리밍을 제공합니다. Python SDK는 동기(sync) 및 비동기(async) 스트림을 모두 지원합니다. 자세한 내용은 각 SDK 문서를 참조하세요.
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
model="claude-opus-5",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
이벤트를 직접 처리하지 않고 최종 메시지 가져오기¶
텍스트가 도착하는 대로 처리할 필요가 없다면, SDK는 내부적으로는 스트리밍을 사용하면서도 .create()가 반환하는 것과 동일한 완전한 Message 객체를 돌려주는 방식을 제공합니다. 이는 특히 max_tokens 값이 큰 요청에서 유용한데, SDK가 HTTP 타임아웃을 피하기 위해 스트리밍을 요구하기 때문입니다.
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-opus-5",
) as stream:
message = stream.get_final_message()
for block in message.content:
if block.type == "text":
print(block.text)
.stream() 호출은 서버 전송 이벤트로 HTTP 연결을 유지한 다음, .get_final_message()(Python) 또는 .finalMessage()(TypeScript)가 모든 이벤트를 누적하고 완전한 Message 객체를 반환합니다. Go에서는 스트림 루프 안에서 message.Accumulate(event)를 호출하여 동일한 완전한 Message를 구성합니다. Java에서는 MessageAccumulator.create()를 사용해 각 이벤트마다 accumulator.accumulate(event)를 호출합니다. C#에서는 스트림의 .Aggregate() 확장 메서드를 await하여 완전한 Message를 얻거나, 이벤트를 처리하면서 집계하려면 MessageContentAggregator를 .CollectAsync()에 전달합니다. Ruby에서는 스트림에서 .accumulated_message를 호출합니다. PHP SDK에서는 스트림 이벤트를 수동으로 순회하며 응답을 누적합니다.
이벤트 유형¶
각 서버 전송 이벤트에는 명명된 이벤트 타입과 관련 JSON 데이터가 포함됩니다. 각 이벤트는 SSE 이벤트 이름(예: event: message_stop)을 사용하며, 데이터 안에도 일치하는 이벤트 type을 포함합니다.
각 스트림은 다음과 같은 이벤트 흐름을 따릅니다:
message_start: 빈content를 가진Message객체를 포함합니다.thinking-binding-controls-2026-08-01베타 헤더 아래에서는 이Message객체가input_transformations배열도 함께 담습니다. 스트림 중간에 서버 측 폴백(server-side fallback)이 발생한 후에는 최종message_delta이벤트가 해당 서빙 모델의 항목과 함께 배열을 다시 전달합니다.- 일련의 콘텐츠 블록. 각 콘텐츠 블록은
content_block_start, 하나 이상의content_block_delta이벤트, 그리고content_block_stop이벤트로 구성됩니다. 각 콘텐츠 블록은 최종 Message의content배열에서 자신의 위치를 나타내는index를 가집니다. 한 가지 예외: 서버 측 폴백 응답 중에는 각 모델 경계에서fallback콘텐츠 블록이content_block_start와content_block_stop쌍으로 도착하며, 그 사이에 델타(delta)는 없습니다. - 하나 이상의
message_delta이벤트. 최종Message객체에 대한 최상위 변경 사항을 나타냅니다. - 마지막
message_stop이벤트.
핑(ping) 이벤트¶
이벤트 스트림에는 ping 이벤트가 얼마든지 포함될 수 있습니다.
오류 이벤트¶
API는 가끔 이벤트 스트림에 오류를 보낼 수 있습니다. 예를 들어 사용량이 많은 기간에는 overloaded_error를 받을 수 있는데, 이는 비스트리밍 맥락에서 HTTP 529에 해당합니다:
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}
기타 이벤트¶
버전 관리 정책(versioning policy)에 따라 새로운 이벤트 유형이 추가될 수 있으므로, 코드는 알 수 없는 이벤트 유형을 우아하게(gracefully) 처리해야 합니다.
콘텐츠 블록 델타 유형¶
각 content_block_delta 이벤트는 주어진 index의 content 블록을 업데이트하는 유형(type)의 delta를 포함합니다.
텍스트 델타¶
text 콘텐츠 블록 델타는 다음과 같습니다:
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}
입력 JSON 델타¶
tool_use 콘텐츠 블록의 델타는 블록의 input 필드에 대한 업데이트에 해당합니다. 최대한의 세분성을 지원하기 위해 델타는 부분 JSON 문자열(partial JSON strings)이며, 최종 tool_use.input은 항상 객체(object)입니다.
문자열 델타를 누적한 뒤 content_block_stop 이벤트를 받으면 Pydantic 같은 라이브러리로 부분 JSON 파싱을 수행해 JSON을 파싱하거나, SDK가 제공하는 헬퍼를 사용해 파싱된 증분 값을 접근할 수 있습니다.
tool_use 콘텐츠 블록 델타는 다음과 같습니다:
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
참고: 현재 모델은 input에서 한 번에 하나의 완전한 키-값 속성만 내보낼 수 있습니다. 따라서 도구를 사용할 때 모델이 작업하는 동안 스트리밍 이벤트 사이에 지연이 있을 수 있습니다. input 키와 값이 누적되면 청크된 부분 JSON(partial JSON)으로 여러 content_block_delta 이벤트로 내보내집니다. 이는 향후 모델에서 더 미세한 세분성을 자동으로 지원할 수 있도록 하는 형식입니다.
사고(Thinking) 델타¶
스트리밍을 활성화한 채 thinking을 사용하면 thinking_delta 이벤트를 통해 사고 콘텐츠를 받게 됩니다. 이 델타는 thinking 콘텐츠 블록의 thinking 필드에 해당합니다.
사고 콘텐츠의 경우, content_block_stop 이벤트 직전에 특별한 signature_delta 이벤트가 전송됩니다. 이 서명(signature)은 사고 블록의 무결성을 검증하는 데 사용됩니다.
thinking 구성에서 display: "omitted"로 설정하면 thinking_delta 이벤트가 전송되지 않습니다. 사고 블록이 열리고 단일 signature_delta를 받은 뒤 닫힙니다. display: "updates"(베타)를 사용하면 추론 블록도 같은 방식으로 스트리밍되며, 일부 모델이 도구 호출 사이에 작성하는 진행 업데이트(progress updates)만 thinking_delta 이벤트로 스트리밍됩니다. 사고 표시 제어(Controlling thinking display)를 참조하세요.
전형적인 thinking 델타는 다음과 같습니다:
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}
서명 델타는 다음과 같습니다:
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
전체 HTTP 스트림 응답¶
스트리밍 모드를 사용할 때는 클라이언트 SDK를 사용하세요. 하지만 직접 API 통합을 구축한다면 이러한 이벤트를 직접 처리해야 합니다.
스트림 응답은 다음으로 구성됩니다:
message_start이벤트- 잠재적으로 여러 콘텐츠 블록. 각 블록은 다음을 포함합니다:
content_block_start이벤트- 잠재적으로 여러
content_block_delta이벤트 content_block_stop이벤트- 하나 이상의
message_delta이벤트 message_stop이벤트
응답 전체에 ping 이벤트가 분산되어 있을 수 있습니다. 형식에 대한 자세한 내용은 이벤트 유형을 참조하세요.
기본 스트리밍 요청¶
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-5",
messages=[{"role": "user", "content": "Hello"}],
max_tokens=256,
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
응답:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}
event: message_stop
data: {"type": "message_stop"}
도구 사용 스트리밍 요청¶
이 요청은 날씨를 보고하기 위해 도구를 사용하도록 Claude에게 요청합니다.
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
]
with client.messages.stream(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "any"},
messages=[
{"role": "user", "content": "What is the weather like in San Francisco?"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
응답:
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-5","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}
event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}
event: content_block_stop
data: {"type":"content_block_stop","index":1}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}
event: message_stop
data: {"type":"message_stop"}
thinking(사고) 사용 스트리밍 요청¶
이 요청은 스트리밍과 함께 thinking을 활성화합니다. display: "summarized" 설정은 Claude의 전체 사고 과정(chain of thought) 대신 요약된 사고 후보를 스트리밍합니다.
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-5",
max_tokens=20000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "What is the greatest common divisor of 1071 and 462?",
}
],
) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
print(event.delta.thinking, end="", flush=True)
elif event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
응답:
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5", "stop_reason": null, "stop_sequence": null}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n147 = 7 × 21 + 0"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\nThe remainder is 0, so GCD(1071, 462) = 21."}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 1}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}
event: message_stop
data: {"type": "message_stop"}
웹 검색 도구 사용 스트리밍 요청¶
이 요청은 현재 날씨 정보를 위해 웹을 검색하도록 Claude에게 요청합니다.
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-5",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
messages=[
{"role": "user", "content": "What is the weather like in New York City today?"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
응답:
event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-5","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":2679,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":3}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"I'll check"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the current weather in New York City for you"}}
event: ping
data: {"type": "ping"}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"."}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" City:\n\n# Weather"}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":" in New York City"}}
event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"\n\n"}}
event: content_block_stop
data: {"type":"content_block_stop","index":17}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":10682,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":510,"server_tool_use":{"web_search_requests":1}}}
event: message_stop
data: {"type":"message_stop"}
오류 복구¶
Claude 4.5 및 이전 버전¶
Claude 4.5 모델 및 이전 버전에서는 네트워크 문제, 타임아웃 또는 기타 오류로 인해 중단된 스트리밍 요청을, 스트림이 중단된 지점부터 재개하여 복구할 수 있습니다. 이 방식은 전체 응답을 다시 처리하지 않아도 되게 해줍니다.
기본 복구 전략은 다음과 같습니다:
- 부분 응답 캡처: 오류가 발생하기 전에 성공적으로 받은 모든 콘텐츠를 저장합니다.
- 연속(continuation) 요청 구성: 부분 어시스턴트 응답을 새 어시스턴트 메시지의 시작으로 포함하는 새 API 요청을 만듭니다.
- 스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다.
Claude 4.6 및 이후 버전¶
Claude 4.6 및 이후 모델에서는 동일한 캡처-후-재개 전략이 적용되지만, 2단계가 달라집니다: 부분 응답을 어시스턴트 메시지에 넣는 대신, 모델에게 중단된 지점부터 계속하라고 지시하는 사용자 메시지를 추가합니다.
- 부분 응답 캡처: 오류가 발생하기 전에 성공적으로 받은 모든 콘텐츠를 저장합니다.
- 연속 요청 구성: 부분 응답과 계속하라는 지시를 담은 사용자 메시지로 새 API 요청을 만듭니다. 예:
Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
- 스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다.
오류 복구 모범 사례¶
- SDK 기능 사용: SDK의 내장 메시지 누적 및 오류 처리 기능을 활용하세요.
- 콘텐츠 유형 처리: 메시지에는 여러 콘텐츠 블록(
text,tool_use,thinking)이 포함될 수 있음을 인지하세요. 도구 사용(tool use) 및 확장 사고(extended thinking) 블록은 부분적으로 복구할 수 없습니다. 가장 최근의 텍스트 블록부터 스트리밍을 재개할 수 있습니다.
다음 단계¶
- 중지 이유와 폴백(Stop reasons and fallback) — 스트림이 완료되면 각
stop_reason값을 처리하세요. - 세밀한 도구 스트리밍(Fine-grained tool streaming) — 서버 측 버퍼링 없이 도구 입력 JSON을 스트리밍해 지연시간을 낮추세요.
- Thinking —
thinking_delta와signature_delta이벤트로 사고 출력을 스트리밍하세요. - 클라이언트 SDK(Client SDKs) — 스트리밍, 누적, 재연결을 처리해주는 공식 SDK를 사용하세요.
- 배치 처리(Batch processing) — 실시간 응답이 필요 없을 때 대량의 요청을 비동기로 처리하세요.