메시지 스트리밍

스트리밍 메시지

메시지를 생성할 때 "stream": true를 설정하여 서버 전송 이벤트(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-7",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

이벤트 처리 없이 최종 메시지 가져오기

텍스트가 도착할 때 처리할 필요가 없다면, SDK는 내부적으로 스트리밍을 사용하면서 .create()가 반환하는 것과 동일한 완전한 Message 객체를 반환하는 방법을 제공합니다. 이는 특히 큰 max_tokens 값을 가진 요청에서 유용하며, SDK가 HTTP 타임아웃을 피하기 위해 스트리밍이 필요합니다.

.stream() 호출은 서버 전송 이벤트로 HTTP 연결을 유지한 다음, .get_final_message()(Python) 또는 .finalMessage()(TypeScript)는 모든 이벤트를 누적하고 완전한 Message 객체를 반환합니다. Go에서는 스트림 루프 내에서 message.Accumulate(event)를 호출하여 동일한 완전한 Message를 구축합니다. Java에서는 MessageAccumulator.create()를 사용하고 각 이벤트에서 accumulator.accumulate(event)를 호출합니다. Ruby에서는 스트림에서 .accumulated_message를 호출합니다. PHP SDK에서는 스트림 이벤트를 수동으로 반복하여 응답을 누적합니다.

이벤트 유형

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

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

message_start: 빈 content를 가진 Message 객체를 포함합니다.
일련의 콘텐츠 블록으로, 각각 content_block_start, 하나 이상의 content_block_delta 이벤트, 그리고 content_block_stop 이벤트를 가집니다. 각 콘텐츠 블록은 최종 Message content 배열의 인덱스에 해당하는 index를 가집니다.
하나 이상의 message_delta 이벤트로, 최종 Message 객체의 최상위 변경을 나타냅니다.
최종 message_stop 이벤트입니다.

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

Ping 이벤트

이벤트 스트림은 또한 임의의 수의 ping 이벤트를 포함할 수 있습니다.

오류 이벤트

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

예제 오류

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

기타 이벤트

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

콘텐츠 블록 델타 유형

각 content_block_delta 이벤트는 주어진 index에서 content 블록을 업데이트하는 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 문자열_이며, 최종 tool_use.input은 항상 _객체_입니다.

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

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

입력 JSON 델타

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를 받고, 닫힙니다. 사고 표시 제어를 참조하세요.

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

사고 델타

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 이벤트가 분산되어 있을 수 있습니다. 형식에 대한 자세한 내용은 이벤트 유형을 참조하세요.

기본 스트리밍 요청

응답

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "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에게 도구를 사용하여 날씨를 보고하도록 요청합니다.

Response

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

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

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

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

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

이 요청은 Claude의 단계별 추론을 보기 위해 스트리밍을 통해 확장된 사고를 활성화합니다.

Response

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-7", "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에게 현재 날씨 정보를 위해 웹을 검색하도록 요청합니다.

Response

event: message_start
data: {"type":"message_start","message":{"id":"msg_01G...","type":"message","role":"assistant","model":"claude-opus-4-7","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 모델의 경우, 모델에게 중단된 지점에서 계속하도록 지시하는 사용자 메시지를 추가해야 합니다. 예를 들어:

Sample prompt

Your previous response was interrupted and ended with [previous_response]. Continue from where you left off.

오류 복구 모범 사례

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

client = anthropic.Anthropic()

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

print(message.content[0].text)

client = anthropic.Anthropic()

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

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-7",
    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)

client = anthropic.Anthropic()

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

client = anthropic.Anthropic()

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