Claude Agent SDKclaude-agent-sdk 0.2.157 · Python 3.10+
Dashboard
0%

Streaming input

Streaming input is the second of the SDK's two input modes: in place of one prompt string you hand query() an asynchronous generator of message dictionaries, and the session stays open for each one in turn.

Last updated: 20 Oct, 2026 · Claude Agent SDK

Streaming output changed how an answer comes back. This changes how the questions go in. The input modes page calls streaming input the preferred way to use the SDK, and names what the one-shot form cannot do.

Writing the message generator

Syntax: an async def function that yields dictionaries. Each one is a user message in the same shape the SDK yields them in.

python
async def questions():
    yield {"type": "user",
           "message": {"role": "user", "content": "Where is my order A17?"}}

The content may be a string, or a list of content blocks, which is how an image is attached. Two other keys, parent_tool_use_id and session_id, appear in the reference's full shape and are filled in for you when they are left out.

Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports this file. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep it in the same folder.
View the code here
shop_desk.py
import asyncio
import itertools
import json
import re

from claude_agent_sdk import ClaudeAgentOptions, Transport

ORDER = re.compile(r"\b[A-Z]\d+\b")
SESSIONS = itertools.count(1)


class ShopModel:
    """Stands in for Claude: reads the conversation, picks the next step."""

    def __init__(self, script=None):
        self.script = list(script or [])

    def reply(self, said, results):
        # a scripted reply lets a lesson force a step the stand-in would not pick
        if self.script:
            return self.script.pop(0)
        if results:
            return {"text": " ".join(results)}

        # the newest message first, then the last id named earlier in the chat
        orders = ORDER.findall(said[-1]) or ORDER.findall(" ".join(said))[-1:]
        return {"text": f"I cannot help with order {orders[0]} yet." if orders
                else "Which order is this about?"}


class ShopDesk(Transport):
    """Stands in for the Claude Code binary: it runs the loop over JSON lines."""

    def __init__(self, options=None, model=None):
        self.options = options or ClaudeAgentOptions()
        self.model = model or ShopModel()

        # a counted id, not a UUID, so the printed output is the same every run
        self.session_id = f"session-{next(SESSIONS)}"
        self.inbox, self.outbox = asyncio.Queue(), asyncio.Queue()
        self.prompts, self.said = asyncio.Queue(), []
        self.ids, self.setup = itertools.count(1), {}
        self.ready = False

    async def connect(self):
        self.ready = True

    def is_ready(self):
        return self.ready

    async def write(self, data):
        # one JSON line at a time, which is what the SDK writes to a real process
        await self.inbox.put(json.loads(data))

    async def end_input(self):
        # for a real process this would close its standard input
        await self.inbox.put(None)

    async def close(self):
        self.ready = False

    async def send(self, message):
        await self.outbox.put(message)

    async def read_messages(self):
        # the listener and the worker run alongside the SDK's own read loop
        asyncio.create_task(self.listen())
        self.worker = asyncio.create_task(self.work())

        while (message := await self.outbox.get()) is not None:
            if isinstance(message, Exception):
                raise message
            yield message

    async def listen(self):
        while (message := await self.inbox.get()) is not None:
            # a control request is the SDK asking a question; initialize is first
            if message["type"] == "control_request":
                if message["request"]["subtype"] == "initialize":
                    self.setup = message["request"]
                await self.respond(message["request_id"])
            elif message["type"] == "user":
                await self.prompts.put(message["message"]["content"])

        # the input has ended: finish the work in hand, then close the stream
        await self.prompts.put(None)
        await self.worker
        await self.send(None)

    async def respond(self, request_id):
        # the stand-in says yes to every request the SDK makes of it
        await self.send({"type": "control_response", "response": {
            "subtype": "success", "request_id": request_id, "response": {}}})

    async def work(self):
        while (prompt := await self.prompts.get()) is not None:
            await self.turn(prompt)

    async def turn(self, prompt):
        self.said.append(prompt)
        await self.send({"type": "system", "subtype": "init", "model": "shop-desk",
                         "session_id": self.session_id, "tools": []})

        # one round only for now: the tool-calling rounds arrive with the tools
        step = self.model.reply(self.said, [])
        await self.say(step["text"])
        await self.finish("success", 1, step["text"])

    async def say(self, text):
        # with include_partial_messages on, the text goes out a word at a time
        if self.options.include_partial_messages:
            for word in text.split(" "):
                delta = {"type": "text_delta", "text": word + " "}
                await self.send({"type": "stream_event", "uuid": f"ev_{next(self.ids)}",
                                 "session_id": self.session_id, "event": {
                                     "type": "content_block_delta", "index": 0,
                                     "delta": delta}})

        # the whole message still follows, so code written earlier keeps working
        await self.send(self.message("assistant", [{"type": "text", "text": text}]))

    async def finish(self, subtype, turns, text):
        ok = subtype == "success"
        result = {"type": "result", "subtype": subtype, "is_error": not ok,
                  "duration_ms": 0, "duration_api_ms": 0, "num_turns": turns,
                  "session_id": self.session_id, "total_cost_usd": 0.0,
                  "usage": {"input_tokens": len(" ".join(self.said).split()),
                            "output_tokens": len(text.split())}}

        # cost is zero and usage counts words, because no model was called
        result.update({"result": text} if ok else {"errors": [text]})
        await self.send(result)

    def message(self, kind, content, parent=None):
        body = {"role": kind, "content": content}
        if kind == "assistant":
            body.update(model="shop-desk", id=f"msg_{next(self.ids)}")
        return {"type": kind, "message": body, "parent_tool_use_id": parent,
                "session_id": self.session_id}

Sending two questions down one session

The generator goes in where the prompt string went. The second question below names no order, which is the point of it:

Example
from claude_agent_sdk import (AssistantMessage, ClaudeAgentOptions,
                              ResultMessage, query)
from shop_desk import ShopDesk


async def questions():
    # the second question names no order, so it can only be answered from the first
    yield {"type": "user",
           "message": {"role": "user", "content": "Where is my order A17?"}}
    yield {"type": "user",
           "message": {"role": "user", "content": "And when did it ship?"}}

options = ClaudeAgentOptions()
async for message in query(prompt=questions(), options=options,
                           transport=ShopDesk(options)):
    if isinstance(message, AssistantMessage):
        print("said   ", message.content[0].text)
    if isinstance(message, ResultMessage):
        print("result ", message.num_turns, message.usage)
  • Two questions, two answers, one session. Each message gets its own turn and its own result, and the stream does not close between them.
  • The follow-up names no order and is still about A17. The stand-in keeps every message it has been sent, so the second answer is drawn from the first question. That is the context persistence the input modes page lists as the mode's main benefit, shown rather than asserted.
  • input_tokens grows and output_tokens does not. The second turn's input is both questions; its answer is the same seven words. Swap the two questions around and the first answer becomes the one that cannot name an order.
  • The turn count restarts at 1 for each message. The agent loop page says the same of a real session: a turn cap applies per queued message, while a spend cap keeps accumulating across them.

What single message input cannot do

The input modes page lists four things the one-shot form does not support, and they are the reason it calls streaming input preferred:

  • Images attached to a message, which need the content-block form of a message dictionary.
  • Queueing messages as they arrive, so a user typing a second question while the first is being answered has nowhere to put it.
  • Interrupting a turn that is already running.
  • A natural multi-turn conversation, which a one-shot call can only imitate by resuming a stored session on every message.

One capability is not on that list, and it is the reason this lesson uses query() and not the client class: query() accepts a generator but stays unidirectional. All the prompts go in, all the responses come out, and there are no methods for interrupting or switching the model mid-session. Those live on ClaudeSDKClient, in A conversation with ClaudeSDKClient.

Single message input against streaming input

A prompt stringAn async generator
What goes inOne questionA sequence of message dictionaries
SessionOne exchangeStays open for every message
Context across questionsOnly by resuming a stored sessionHeld by the session itself
ImagesNot supportedSupported, as content blocks
Queueing and interruptsNot supportedQueueing yes; interrupts need the client class
After an error resultquery() raisesThe session stays alive
Built forA stateless job or a lambdaAn interactive application

Where the input mode decides the design

  • A chat feature, where each message a user sends should reach a session that is already warm rather than open a new one.
  • A pipeline step, where one prompt in and one result out is the whole contract and a generator would be scaffolding.
  • Anything that sends an image, where the input mode is not a preference: a prompt string has nowhere to put one.
Watch out. An exception inside your generator does not stop the program. The input modes page states that in the Python SDK a generator exception is logged at debug level and the session stalls without raising, so a session that hangs with no output is a reason to turn on debug logging and read your own generator first.
Try it yourself
  • Swap the order of the two yielded questions and read which answer changes.
  • Add a third question that names order B22 and watch which order the last answer is about.
  • Put await asyncio.sleep(1) between the two yields and confirm the first answer arrives before the second question is sent.

Slow is fine. Stopping is the only problem.