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.
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.
View the code here
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:
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)said I cannot help with order A17 yet.
result 1 {'input_tokens': 5, 'output_tokens': 7}
said I cannot help with order A17 yet.
result 1 {'input_tokens': 10, 'output_tokens': 7}- 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_tokensgrows andoutput_tokensdoes 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 string | An async generator | |
|---|---|---|
| What goes in | One question | A sequence of message dictionaries |
| Session | One exchange | Stays open for every message |
| Context across questions | Only by resuming a stored session | Held by the session itself |
| Images | Not supported | Supported, as content blocks |
| Queueing and interrupts | Not supported | Queueing yes; interrupts need the client class |
| After an error result | query() raises | The session stays alive |
| Built for | A stateless job or a lambda | An 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.
Related
- Previous: Streaming output
- Next: When the CLI will not start
- See also: A conversation with ClaudeSDKClient
- Reference: Streaming input
- 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.