Stream responses in real-time

By default, the Agent SDK yields a complete AssistantMessage for each non-empty content block, such as a text block or a tool call, after Claude finishes generating that block. To receive incremental updates as text and tool calls are generated, enable partial message streaming.

This page covers output streaming (receiving tokens in real-time). For input modes (how you send messages), see Send messages to agents. You can also stream responses using the Agent SDK via the CLI.

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. Your code then needs to:

Check each message’s type to distinguish StreamEvent from other message types
For StreamEvent, extract the event field and check its type
Look for content_block_delta events where delta.type is text_delta, which contain the actual text chunks

The example below enables streaming and prints text chunks as they arrive. Notice the nested type checks: first for StreamEvent, then for content_block_delta, then for text_delta:

from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent
import asyncio


async def stream_response():
    options = ClaudeAgentOptions(
        include_partial_messages=True,
        allowed_tools=["Bash", "Read"],
    )

    async for message in query(prompt="List the files in my project", options=options):
        if isinstance(message, StreamEvent):
            event = message.event
            if event.get("type") == "content_block_delta":
                delta = event.get("delta", {})
                if delta.get("type") == "text_delta":
                    print(delta.get("text", ""), end="", flush=True)


asyncio.run(stream_response())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the files in my project",
  options: {
    includePartialMessages: true,
    allowedTools: ["Bash", "Read"]
  }
})) {
  if (message.type === "stream_event") {
    const event = message.event;
    if (event.type === "content_block_delta") {
      if (event.delta.type === "text_delta") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

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. 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. Claude Code sets user_message_uuid on the turn’s first non-ping stream event, and again when the message the turn is answering changes, under the conditions in user_message_uuid. The Python StreamEvent doesn’t expose this field. The event field contains the raw streaming event from the Claude API. 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

Claude Code emits an AssistantMessage as each non-empty content block completes, so a response with a text block and a tool call yields two AssistantMessage objects. Each one carries only its own content block, and both share the same message ID, which you read as message.message.id in TypeScript and message.message_id in Python. With partial messages enabled, each AssistantMessage arrives before that block’s content_block_stop event, and you receive messages in this order:

StreamEvent (message_start)
StreamEvent (content_block_start) - text block
StreamEvent (content_block_delta) - text chunks...
AssistantMessage - complete text block
StreamEvent (content_block_stop)
StreamEvent (content_block_start) - tool_use block
StreamEvent (content_block_delta) - tool input chunks...
AssistantMessage - complete tool_use block
StreamEvent (content_block_stop)
StreamEvent (message_delta)
StreamEvent (message_stop)
... tool executes ...
... more streaming events for next turn ...

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Stream responses in real-time

Enable streaming output

StreamEvent reference

Message flow

​Enable streaming output

​StreamEvent reference

​Message flow

Enable streaming output

StreamEvent reference

Message flow