Messages모델 기능

메시지 스트리밍

텍스트, 도구 사용, 확장 사고 델타를 포함하여 server-sent events로 Messages API 응답을 점진적으로 스트리밍합니다.

Message를 생성할 때 "stream": true를 설정하면 server-sent events(SSE)를 사용하여 응답을 점진적으로 스트리밍할 수 있습니다.

SDK를 사용한 스트리밍

Python 및 TypeScript SDK는 여러 가지 스트리밍 방식을 제공합니다. PHP SDK는 createStream()을 통해 스트리밍을 제공합니다. Python SDK는 동기 및 비동기 스트림을 모두 지원합니다. 자세한 내용은 각 SDK의 문서를 참조하세요.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) 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-4-8",
) as stream:
    message = stream.get_final_message()

print(message.content[0].text)

.stream() 호출은 server-sent events로 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에서는 스트림 이벤트를 수동으로 반복하여 응답을 누적합니다.

이벤트 유형

각 server-sent event는 명명된 이벤트 유형과 관련 JSON 데이터를 포함합니다. 각 이벤트는 SSE 이벤트 이름(예: event: message_stop)을 사용하며, 데이터에 일치하는 이벤트 type을 포함합니다.

각 스트림은 다음과 같은 이벤트 흐름을 사용합니다:

message_start: 빈 content를 가진 Message 객체를 포함합니다.
일련의 콘텐츠 블록으로, 각각 content_block_start, 하나 이상의 content_block_delta 이벤트, 그리고 content_block_stop 이벤트를 가집니다. 각 콘텐츠 블록은 최종 Message content 배열에서의 인덱스에 해당하는 index를 가집니다. 한 가지 예외: 서버 측 폴백 응답 중에는 각 모델 경계에서 fallback 콘텐츠 블록이 중간에 델타 없이 content_block_start와 content_block_stop 쌍으로 도착합니다.
최종 Message 객체에 대한 최상위 변경 사항을 나타내는 하나 이상의 message_delta 이벤트.
최종 message_stop 이벤트.

message_delta 이벤트의 usage 필드에 표시되는 토큰 수는 누적 값입니다.

Ping 이벤트

이벤트 스트림에는 임의의 수의 ping 이벤트가 포함될 수도 있습니다.

오류 이벤트

API는 때때로 이벤트 스트림에서 오류를 전송할 수 있습니다. 예를 들어, 사용량이 많은 기간에는 overloaded_error를 받을 수 있으며, 이는 비스트리밍 컨텍스트에서 일반적으로 HTTP 529에 해당합니다:

Example error

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

기타 이벤트

버전 관리 정책에 따라 새로운 이벤트 유형이 추가될 수 있으며, 코드는 알 수 없는 이벤트 유형을 적절하게 처리해야 합니다.

콘텐츠 블록 델타 유형

각 content_block_delta 이벤트는 주어진 index에서 content 블록을 업데이트하는 유형의 delta를 포함합니다.

텍스트 델타

text 콘텐츠 블록 델타는 다음과 같습니다:

Text delta

event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

입력 JSON 델타

tool_use 콘텐츠 블록의 델타는 블록의 input 필드에 대한 업데이트에 해당합니다. 최대 세분성을 지원하기 위해 델타는 _부분 JSON 문자열_인 반면, 최종 tool_use.input은 항상 _객체_입니다.

문자열 델타를 누적하고 content_block_stop 이벤트를 받으면 Pydantic과 같은 라이브러리를 사용하여 부분 JSON 파싱을 수행하거나, 파싱된 증분 값에 접근할 수 있는 헬퍼를 제공하는 SDK를 사용하여 JSON을 파싱할 수 있습니다.

tool_use 콘텐츠 블록 델타는 다음과 같습니다:

Input JSON delta

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

참고: 현재 모델은 한 번에 input에서 하나의 완전한 키와 값 속성만 내보내는 것을 지원합니다. 따라서 도구를 사용할 때 모델이 작업하는 동안 스트리밍 이벤트 사이에 지연이 있을 수 있습니다. input 키와 값이 누적되면 청크로 나뉜 부분 json과 함께 여러 content_block_delta 이벤트로 내보내지므로, 이 형식은 향후 모델에서 더 세밀한 세분성을 자동으로 지원할 수 있습니다.

사고 델타

스트리밍이 활성화된 상태에서 확장 사고를 사용하면 thinking_delta 이벤트를 통해 사고 콘텐츠를 받게 됩니다. 이러한 델타는 thinking 콘텐츠 블록의 thinking 필드에 해당합니다.

사고 콘텐츠의 경우, content_block_stop 이벤트 직전에 특별한 signature_delta 이벤트가 전송됩니다. 이 서명은 사고 블록의 무결성을 검증하는 데 사용됩니다.

사고 구성에서 display: "omitted"가 설정된 경우, thinking_delta 이벤트는 전송되지 않습니다. 사고 블록이 열리고, 단일 signature_delta를 받은 후 닫힙니다. 사고 표시 제어를 참조하세요.

일반적인 사고 델타는 다음과 같습니다:

Thinking delta

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

서명 델타는 다음과 같습니다:

Signature delta

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-4-8",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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"}

도구 사용이 포함된 스트리밍 요청

도구 사용은 매개변수 값에 대한 세밀한 스트리밍을 지원합니다. eager_input_streaming으로 도구별로 활성화하세요.

이 요청은 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-4-8",
    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)

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-8","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"}

확장 사고가 포함된 스트리밍 요청

이 요청은 스트리밍과 함께 확장 사고를 활성화합니다. display: "summarized" 설정은 전체 사고 과정 대신 Claude의 추론에 대한 압축된 요약을 스트리밍합니다.

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    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)

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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-4-8",
    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)

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-8","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_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","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":"{\"query"}}

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":" \"weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1 }

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

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 모델 및 이전 버전의 경우, 네트워크 문제, 타임아웃 또는 기타 오류로 인해 중단된 스트리밍 요청을 스트림이 중단된 지점부터 재개하여 복구할 수 있습니다. 이 접근 방식을 사용하면 전체 응답을 다시 처리하지 않아도 됩니다.

기본 복구 전략은 다음과 같습니다:

부분 응답 캡처: 오류가 발생하기 전에 성공적으로 수신된 모든 콘텐츠를 저장합니다
계속 요청 구성: 부분 어시스턴트 응답을 새 어시스턴트 메시지의 시작 부분으로 포함하는 새 API 요청을 생성합니다
스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다

Claude 4.6 및 이후 버전

Claude 4.6 및 이후 모델의 경우, 동일한 캡처 및 재개 전략이 적용되지만 2단계가 변경됩니다. 부분 응답을 어시스턴트 메시지에 배치하는 대신, 모델에게 중단된 지점부터 계속하도록 지시하는 사용자 메시지를 추가합니다.

부분 응답 캡처: 오류가 발생하기 전에 성공적으로 수신된 모든 콘텐츠를 저장합니다
계속 요청 구성: 부분 응답과 계속하라는 지시를 포함하는 사용자 메시지로 새 API 요청을 생성합니다. 예를 들어:
Sample prompt
```
Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
```
스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다

오류 복구 모범 사례

SDK 기능 사용: SDK의 내장 메시지 누적 및 오류 처리 기능을 활용하세요
콘텐츠 유형 처리: 메시지에는 여러 콘텐츠 블록(text, tool_use, thinking)이 포함될 수 있다는 점에 유의하세요. 도구 사용 및 확장 사고 블록은 부분적으로 복구할 수 없습니다. 가장 최근의 텍스트 블록부터 스트리밍을 재개할 수 있습니다.

다음 단계

중지 이유 및 폴백

스트림이 완료되면 각 stop_reason 값을 처리하세요.

세밀한 도구 스트리밍

더 낮은 지연 시간을 위해 서버 측 버퍼링 없이 도구 입력 JSON을 스트리밍하세요.

확장 사고

thinking_delta 및 signature_delta 이벤트로 확장 사고 출력을 스트리밍하세요.

클라이언트 SDK

스트리밍, 누적 및 재연결을 처리해 주는 공식 SDK를 사용하세요.

배치 처리

실시간 응답이 필요하지 않을 때 대량의 요청을 비동기적으로 처리하세요.

Was this page helpful?

Messages모델 기능

메시지 스트리밍

텍스트, 도구 사용, 확장 사고 델타를 포함하여 server-sent events로 Messages API 응답을 점진적으로 스트리밍합니다.

Message를 생성할 때 "stream": true를 설정하면 server-sent events(SSE)를 사용하여 응답을 점진적으로 스트리밍할 수 있습니다.

SDK를 사용한 스트리밍

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

이벤트를 처리하지 않고 최종 메시지 가져오기

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-4-8",
) as stream:
    message = stream.get_final_message()

print(message.content[0].text)

이벤트 유형

각 스트림은 다음과 같은 이벤트 흐름을 사용합니다:

message_start: 빈 content를 가진 Message 객체를 포함합니다.
일련의 콘텐츠 블록으로, 각각 content_block_start, 하나 이상의 content_block_delta 이벤트, 그리고 content_block_stop 이벤트를 가집니다. 각 콘텐츠 블록은 최종 Message content 배열에서의 인덱스에 해당하는 index를 가집니다. 한 가지 예외: 서버 측 폴백 응답 중에는 각 모델 경계에서 fallback 콘텐츠 블록이 중간에 델타 없이 content_block_start와 content_block_stop 쌍으로 도착합니다.
최종 Message 객체에 대한 최상위 변경 사항을 나타내는 하나 이상의 message_delta 이벤트.
최종 message_stop 이벤트.

message_delta 이벤트의 usage 필드에 표시되는 토큰 수는 누적 값입니다.

Ping 이벤트

이벤트 스트림에는 임의의 수의 ping 이벤트가 포함될 수도 있습니다.

오류 이벤트

Example error

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

기타 이벤트

버전 관리 정책에 따라 새로운 이벤트 유형이 추가될 수 있으며, 코드는 알 수 없는 이벤트 유형을 적절하게 처리해야 합니다.

콘텐츠 블록 델타 유형

각 content_block_delta 이벤트는 주어진 index에서 content 블록을 업데이트하는 유형의 delta를 포함합니다.

텍스트 델타

text 콘텐츠 블록 델타는 다음과 같습니다:

Text delta

event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

입력 JSON 델타

tool_use 콘텐츠 블록 델타는 다음과 같습니다:

Input JSON delta

event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

사고 델타

일반적인 사고 델타는 다음과 같습니다:

Thinking delta

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

서명 델타는 다음과 같습니다:

Signature delta

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-4-8",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=256,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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"}

도구 사용이 포함된 스트리밍 요청

도구 사용은 매개변수 값에 대한 세밀한 스트리밍을 지원합니다. eager_input_streaming으로 도구별로 활성화하세요.

이 요청은 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-4-8",
    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)

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-opus-4-8","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"}

확장 사고가 포함된 스트리밍 요청

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    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)

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "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-4-8",
    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)

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-8","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_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"server_tool_use","id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","name":"web_search","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":"{\"query"}}

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":" \"weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" NY"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"C to"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"day\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1 }

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"web_search_tool_result","tool_use_id":"srvtoolu_014hJH82Qum7Td6UV8gDXThB","content":[{"type":"web_search_result","title":"Weather in New York City in May 2025 (New York) - detailed Weather Forecast for a month","url":"https://world-weather.info/forecast/usa/new_york/may-2025/","encrypted_content":"Ev0DCioIAxgCIiQ3NmU4ZmI4OC1k...","page_age":null},...]}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: content_block_start
data: {"type":"content_block_start","index":3,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":3,"delta":{"type":"text_delta","text":"Here's the current weather information for New York"}}

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 및 이전 버전

기본 복구 전략은 다음과 같습니다:

부분 응답 캡처: 오류가 발생하기 전에 성공적으로 수신된 모든 콘텐츠를 저장합니다
계속 요청 구성: 부분 어시스턴트 응답을 새 어시스턴트 메시지의 시작 부분으로 포함하는 새 API 요청을 생성합니다
스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다

Claude 4.6 및 이후 버전

부분 응답 캡처: 오류가 발생하기 전에 성공적으로 수신된 모든 콘텐츠를 저장합니다
계속 요청 구성: 부분 응답과 계속하라는 지시를 포함하는 사용자 메시지로 새 API 요청을 생성합니다. 예를 들어:
Sample prompt
```
Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.
```
스트리밍 재개: 중단된 지점부터 나머지 응답을 계속 수신합니다

오류 복구 모범 사례

SDK 기능 사용: SDK의 내장 메시지 누적 및 오류 처리 기능을 활용하세요
콘텐츠 유형 처리: 메시지에는 여러 콘텐츠 블록(text, tool_use, thinking)이 포함될 수 있다는 점에 유의하세요. 도구 사용 및 확장 사고 블록은 부분적으로 복구할 수 없습니다. 가장 최근의 텍스트 블록부터 스트리밍을 재개할 수 있습니다.

다음 단계

중지 이유 및 폴백

스트림이 완료되면 각 stop_reason 값을 처리하세요.

세밀한 도구 스트리밍

더 낮은 지연 시간을 위해 서버 측 버퍼링 없이 도구 입력 JSON을 스트리밍하세요.

확장 사고

thinking_delta 및 signature_delta 이벤트로 확장 사고 출력을 스트리밍하세요.

클라이언트 SDK

스트리밍, 누적 및 재연결을 처리해 주는 공식 SDK를 사용하세요.

배치 처리

실시간 응답이 필요하지 않을 때 대량의 요청을 비동기적으로 처리하세요.

Was this page helpful?

SDK를 사용한 스트리밍

이벤트를 처리하지 않고 최종 메시지 가져오기

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

콘텐츠 블록 델타 유형

텍스트 델타

입력 JSON 델타

사고 델타

전체 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청

확장 사고가 포함된 스트리밍 요청

웹 검색 도구 사용이 포함된 스트리밍 요청

오류 복구

Claude 4.5 및 이전 버전

Claude 4.6 및 이후 버전

오류 복구 모범 사례

다음 단계

SDK를 사용한 스트리밍

이벤트를 처리하지 않고 최종 메시지 가져오기

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

콘텐츠 블록 델타 유형

텍스트 델타

입력 JSON 델타

사고 델타

전체 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청

확장 사고가 포함된 스트리밍 요청

웹 검색 도구 사용이 포함된 스트리밍 요청

오류 복구

Claude 4.5 및 이전 버전

Claude 4.6 및 이후 버전

오류 복구 모범 사례

다음 단계

SDK를 사용한 스트리밍

이벤트를 처리하지 않고 최종 메시지 가져오기

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

콘텐츠 블록 델타 유형

텍스트 델타

입력 JSON 델타

사고 델타

전체 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청

확장 사고가 포함된 스트리밍 요청

웹 검색 도구 사용이 포함된 스트리밍 요청

오류 복구

Claude 4.5 및 이전 버전

Claude 4.6 및 이후 버전

오류 복구 모범 사례

다음 단계

SDK를 사용한 스트리밍

이벤트를 처리하지 않고 최종 메시지 가져오기

이벤트 유형

Ping 이벤트

오류 이벤트

기타 이벤트

콘텐츠 블록 델타 유형

텍스트 델타

입력 JSON 델타

사고 델타

전체 HTTP 스트림 응답

기본 스트리밍 요청

도구 사용이 포함된 스트리밍 요청

확장 사고가 포함된 스트리밍 요청

웹 검색 도구 사용이 포함된 스트리밍 요청

오류 복구

Claude 4.5 및 이전 버전

Claude 4.6 및 이후 버전

오류 복구 모범 사례

다음 단계