Chapter 11

Streaming Input

Understanding the two input modes for Claude Agent SDK and when to use each

Overview

The Claude Agent SDK supports two distinct input modes for interacting with agents:

Streaming Input Mode

Default & Recommended

A persistent, interactive session with full access to all agent capabilities

Single Message Input

Simpler, but limited

One-shot queries that use session state and resuming

This guide explains the differences, benefits, and use cases for each mode to help you choose the right approach for your application.

Streaming Input Mode

Recommended

Streaming input mode is the preferred way to use the Claude Agent SDK. It provides full access to the agent's capabilities and enables rich, interactive experiences.

It allows the agent to operate as a long-lived process that takes in user input, handles interruptions, surfaces permission requests, and handles session management.

How It Works

Interactive Flow Diagram

App

Agent

Tools

Environment

Initialize: App initializes connection with AsyncGenerator

Benefits

Image Uploads

Attach images directly to messages for visual analysis and understanding

Queued Messages

Send multiple messages that process sequentially, with ability to interrupt

Tool Integration

Full access to all tools and custom MCP servers during the session

Hooks Support

Use lifecycle hooks to customize behavior at various points

Real-time Feedback

See responses as they're generated, not just final results

Context Persistence

Maintain conversation context across multiple turns naturally

Implementation Example

streaming-example.ts

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

async function* generateMessages() {
  // First message
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Analyze this codebase for security issues"
    }
  };

  // Wait for conditions or user input
  await new Promise(resolve => setTimeout(resolve, 2000));

  // Follow-up with image
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Review this architecture diagram"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Process streaming responses
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Single Message Input

Single message input is simpler but more limited. Use it for straightforward, one-shot queries.

When to Use Single Message Input

Use single message input when:

1You need a one-shot response
2You do not need image attachments, hooks, etc.
3You need to operate in a stateless environment, such as a lambda function

Limitations

Warning

Single message input mode does not support:

Direct image attachments in messages
Dynamic message queueing
Real-time interruption
Hook integration
Natural multi-turn conversations

Implementation Example

single-message.ts

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

// Simple one-shot query
for await (const message of query({
  prompt: "Explain the authentication flow",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// Continue conversation with session management
for await (const message of query({
  prompt: "Now explain the authorization process",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Feature Comparison

Compare the capabilities of each input mode at a glance:

Feature	Streaming Input	Single Message
Image Uploads
Message Queueing
Real-time Streaming
Hook Integration
Session Persistence
Simple Setup
Stateless Operation
Lambda Compatible

Quick Summary

Choose Streaming Input when:

• Building interactive applications
• Need real-time feedback
• Working with images or files
• Require full agent capabilities

Choose Single Message when:

• Simple one-shot queries
• Stateless environments (Lambda)
• Minimal setup required
• No advanced features needed

Other Types

Configure Permissions