Stream responses in real-time

Stream responses in real-time 문서는 Claude Code 공식 문서(agent-sdk/streaming-output)를 한국어로 정리한 가이드입니다. Get real-time responses from the Agent SDK as text and tool calls stream in 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Get real-time responses from the Agent SDK as text and tool calls stream in

한국어 가이드 범위: agent-sdk/streaming-output 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Stream responses in real-time
Enable streaming output
StreamEvent reference
Message flow
Stream text responses
Stream tool calls
Build a streaming UI
Known limitations
다음 단계

상세 내용

Stream responses in real-time

Enable streaming output

To enable streaming, set include_partial_messages (Python) or includePartialMessages (TypeScript) to true in your options. This causes the SDK to yield StreamEvent messages containing raw API events as they arrive, in addition to the usual AssistantMessage and ResultMessage.

StreamEvent reference

When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK:

주요 항목:

Python: StreamEvent (import from claude_agent_sdk.types)
TypeScript: SDKPartialAssistantMessage with type: 'stream_event'

Event Type	Description
`message_start`	Start of a new message
`content_block_start`	Start of a new content block (text or tool use)
`content_block_delta`	Incremental update to content
`content_block_stop`	End of a content block
`message_delta`	Message-level updates (stop reason, usage)
`message_stop`	End of the message

Message flow

With partial messages enabled, you receive messages in this order:

Stream text responses

To display text as it's generated, look for content_block_delta events where delta.type is text_delta. These contain the incremental text chunks. The example below prints each chunk as it arrives:

Stream tool calls

Tool calls also stream incrementally. You can track when tools start, receive their input as it's generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types:

주요 항목:

content_block_start: tool begins
content_block_delta with input_json_delta: input chunks arrive
content_block_stop: tool call complete

Build a streaming UI

This example combines text and tool streaming into a cohesive UI. It tracks whether the agent is currently executing a tool (using an in_tool flag) to show status indicators like [Using Read...] while tools run. Text streams normally when not in a tool, and tool completion triggers a "done" message. This pattern is useful for chat interfaces that need to show progress during multi-step agent tasks.

Known limitations

주요 항목:

Structured output: the JSON result appears only in the final ResultMessage.structured_output, not as streaming deltas. See structured outputs for details.

다음 단계

Now that you can stream text and tool calls in real-time, explore these related topics:

주요 항목:

Interactive vs one-shot queries: choose between input modes for your use case
Structured outputs: get typed JSON responses from the agent
Permissions: control which tools the agent can use

실습 체크리스트

공식 문서와 로컬/SDK 버전을 대조합니다.
관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

## StreamEvent reference

When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK:

* **Python**: `StreamEvent` (import from `claude_agent_sdk.types`)
* **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'`

Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here's the structure of each type:

The `parent_tool_use_id` field is always `None` in Python and `null` in TypeScript. Stream events are emitted for the main session only; token-level deltas from subagents aren't forwarded. To attribute output to a subagent, use complete messages, which carry `parent_tool_use_id`. See [Detect subagent invocation](/docs/en/agent-sdk/subagents#detect-subagent-invocation).

The `event` field contains the raw streaming event from the [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Common event types include:

| Event Type            | Description                                     |
| :-------------------- | :---------------------------------------------- |
| `message_start`       | Start of a new message                          |
| `content_block_start` | Start of a new content block (text or tool use) |
| `content_block_delta` | Incremental update to content                   |
| `content_block_stop`  | End of a content block                          |
| `message_delta`       | Message-level updates (stop reason, usage)      |
| `message_stop`        | End of the message                              |

## Message flow

With partial messages enabled, you receive messages in this order:

Without partial messages enabled (`include_partial_messages` in Python, `includePartialMessages` in TypeScript), you receive all message types except `StreamEvent`. Common types include `SystemMessage` (session initialization), `AssistantMessage` (complete responses), `ResultMessage` (final result), and a compact boundary message indicating when conversation history was compacted (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` with subtype `"compact_boundary"` in Python).

## Stream text responses

To display text as it's generated, look for `content_block_delta` events where `delta.type` is `text_delta`. These contain the incremental text chunks. The example below prints each chunk as it arrives:

## Stream tool calls

Tool calls also stream incrementally. You can track when tools start, receive their input as it's generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types:

* `content_block_start`: tool begins
* `content_block_delta` with `input_json_delta`: input chunks arrive
* `content_block_stop`: tool call complete

Stream responses in real-time

핵심 요약

Get real-time responses from the Agent SDK as text and tool calls stream in

한국어 가이드 범위: agent-sdk/streaming-output 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Stream responses in real-time
Enable streaming output
StreamEvent reference
Message flow
Stream text responses
Stream tool calls
Build a streaming UI
Known limitations
다음 단계

상세 내용

Stream responses in real-time

Enable streaming output

StreamEvent reference

When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK:

주요 항목:

Python: StreamEvent (import from claude_agent_sdk.types)
TypeScript: SDKPartialAssistantMessage with type: 'stream_event'

Event Type	Description
`message_start`	Start of a new message
`content_block_start`	Start of a new content block (text or tool use)
`content_block_delta`	Incremental update to content
`content_block_stop`	End of a content block
`message_delta`	Message-level updates (stop reason, usage)
`message_stop`	End of the message

Message flow

With partial messages enabled, you receive messages in this order:

Stream text responses

Stream tool calls

주요 항목:

content_block_start: tool begins
content_block_delta with input_json_delta: input chunks arrive
content_block_stop: tool call complete

Build a streaming UI

Known limitations

주요 항목:

Structured output: the JSON result appears only in the final ResultMessage.structured_output, not as streaming deltas. See structured outputs for details.

다음 단계

Now that you can stream text and tool calls in real-time, explore these related topics:

주요 항목:

Interactive vs one-shot queries: choose between input modes for your use case
Structured outputs: get typed JSON responses from the agent
Permissions: control which tools the agent can use

실습 체크리스트

공식 문서와 로컬/SDK 버전을 대조합니다.
관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

## StreamEvent reference

When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK:

* **Python**: `StreamEvent` (import from `claude_agent_sdk.types`)
* **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'`

Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here's the structure of each type:

The `parent_tool_use_id` field is always `None` in Python and `null` in TypeScript. Stream events are emitted for the main session only; token-level deltas from subagents aren't forwarded. To attribute output to a subagent, use complete messages, which carry `parent_tool_use_id`. See [Detect subagent invocation](/docs/en/agent-sdk/subagents#detect-subagent-invocation).

The `event` field contains the raw streaming event from the [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Common event types include:

| Event Type            | Description                                     |
| :-------------------- | :---------------------------------------------- |
| `message_start`       | Start of a new message                          |
| `content_block_start` | Start of a new content block (text or tool use) |
| `content_block_delta` | Incremental update to content                   |
| `content_block_stop`  | End of a content block                          |
| `message_delta`       | Message-level updates (stop reason, usage)      |
| `message_stop`        | End of the message                              |

## Message flow

With partial messages enabled, you receive messages in this order:

Without partial messages enabled (`include_partial_messages` in Python, `includePartialMessages` in TypeScript), you receive all message types except `StreamEvent`. Common types include `SystemMessage` (session initialization), `AssistantMessage` (complete responses), `ResultMessage` (final result), and a compact boundary message indicating when conversation history was compacted (`SDKCompactBoundaryMessage` in TypeScript; `SystemMessage` with subtype `"compact_boundary"` in Python).

## Stream text responses

To display text as it's generated, look for `content_block_delta` events where `delta.type` is `text_delta`. These contain the incremental text chunks. The example below prints each chunk as it arrives:

## Stream tool calls

Tool calls also stream incrementally. You can track when tools start, receive their input as it's generated, and see when they complete. The example below tracks the current tool being called and accumulates the JSON input as it streams in. It uses three event types:

* `content_block_start`: tool begins
* `content_block_delta` with `input_json_delta`: input chunks arrive
* `content_block_stop`: tool call complete

Stream responses in real-time

핵심 요약

문서 구성

상세 내용

Stream responses in real-time

Enable streaming output

StreamEvent reference

Message flow

Stream text responses

Stream tool calls

Build a streaming UI

Known limitations

다음 단계

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Stream responses in real-time

핵심 요약

문서 구성

상세 내용

Stream responses in real-time

Enable streaming output

StreamEvent reference

Message flow

Stream text responses

Stream tool calls

Build a streaming UI

Known limitations

다음 단계

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드