Skip to main content
Streaming input keeps an Agent SDK session open so your application can send it more than one message while it runs. You can also attach images to a message and stop a response partway through to redirect Claude.
Streaming input covers the messages you send. To show Claude’s response as it’s generated, see Stream responses in real-time.

Choose single-shot or streaming input

Choose streaming input for an application that holds a conversation with Claude, such as a chat interface. Use streaming input to attach images to a message, interrupt a response, or switch the model or permission mode while the session runs. A single-shot call passes one prompt string to query(). The call ends after Claude answers it. Single-shot fits a single task, such as a serverless function. To follow up after that call ends, start a new call that resumes the session. For more information, see Continue, resume, and fork.

Send more than one message to a session

  • TypeScript: write an async generator that yields SDKUserMessage objects, and pass it as the prompt of query(). Make the generator wait between yields for the next message from your user.
  • Python: open a ClaudeSDKClient and pass each message to client.query(). Pass a string for a text message. To attach an image, pass an async generator that yields user message dicts.
To have Claude answer each message in its own response, wait for the previous response’s result message before you send the next one:
  • TypeScript: have your generator await a promise. Resolve it in your for await loop over query() when the result message arrives.
  • Python: call client.query() with the next message after your receive_response() loop ends.
A message you send during tool calls reaches Claude after those tool calls finish. Claude then answers it and your earlier message in one response. If the turn ends first, Claude starts a new turn for it. For details, see Turns and budget.

Send a follow-up with an image

This example sends a text question, then a follow-up with an image, and prints Claude’s response to each. Before you run it, save a PNG image as diagram.png in your working directory:
When you run either version, the example prints Response 1 finished: success and Response 2 finished: success. If Claude didn’t see your image, see Image could not be processed.

Feed messages from a chat interface in TypeScript

Feed your user’s messages to your prompt generator through a queue:
  • pushMessage(): your interface’s input handler calls this for each message the user sends.
  • closeInput(): the handler calls this when the user closes the chat.
  • userMessages(): the generator you pass as the prompt of query().
pushMessage() adds each message to an array, and the generator reads from that array. When the array is empty, the generator waits until a message arrives or the chat closes:
Messages you push during a response can share one response. To choose when Claude reads a message you push during a response, set the message’s priority field.

Read each response

Claude ends each response with a result message.
  • TypeScript: the for await loop over query() yields each response’s messages in order. The loop ends after the last response’s result message, once your generator has returned. To match a result to the messages it answers, set a uuid on each message you send, and read the result’s user_message_uuids.
  • Python: start a receive_response() loop for each response, because each loop stops after the next ResultMessage. The client keeps the conversation’s context from one message to the next. For more information, see Automatic session management.
The result message’s subtype field reports how the response ended, such as success or error_during_execution. If the last response ends in an error result:
  • TypeScript: the loop over query() yields that result and then throws. Wrap the loop in try/catch to handle the exception. To keep the conversation going after the throw, start a new query() call that resumes the session. While your generator still has messages to send, an error result for an earlier response doesn’t throw.
  • Python: receive_response() on a ClaudeSDKClient yields the error result without raising.
For what each result subtype means, see Handle the result.

Interrupt Claude’s response

To stop a response partway through and keep the session open, call interrupt() on the object that runs the session:
  • TypeScript: pass an async generator as prompt, save the Query object returned by query(), and call interrupt() on it.
  • Python: call interrupt() on the ClaudeSDKClient. If a receive_response() loop is reading the response, that loop ends at the interrupted response’s ResultMessage. Send your next message after that result arrives.
When you call interrupt() during a response, that response ends with an error_during_execution result. Messages you sent before the interrupt that Claude hadn’t read yet still reach Claude once the interrupted response ends. For what the TypeScript loop does when the last response is an error result, see Read each response. This example asks Claude for a long essay. The example calls interrupt() three seconds after the session starts, then sends a second message to the same session once the interrupted response ends:
When you run either version, the first response stops partway through the essay, and the example prints Response 1 finished: error_during_execution. Claude then answers the second message. The output ends with Response 2 finished: success.

Next steps