Loading...
    • Developer Guide
    • API Reference
    • MCP
    • Resources
    • Release Notes
    Search...
    ⌘K
    First steps
    Intro to ClaudeQuickstart
    Models & pricing
    Models overviewChoosing a modelWhat's new in Claude 4.6Migration guideModel deprecationsPricing
    Build with Claude
    Features overviewUsing the Messages APIHandling stop reasonsPrompting best practices
    Model capabilities
    Extended thinkingAdaptive thinkingEffortFast mode (beta: research preview)Structured outputsCitationsStreaming MessagesBatch processingPDF supportSearch resultsMultilingual supportEmbeddingsVision
    Tools
    OverviewHow tool use worksTutorial: Build a tool-using agentDefine toolsHandle tool callsParallel tool useTool Runner (SDK)Strict tool useTool use with prompt cachingServer toolsTroubleshootingTool referenceWeb search toolWeb fetch toolCode execution toolMemory toolBash toolComputer use toolText editor tool
    Tool infrastructure
    Manage tool contextTool combinationsTool searchProgrammatic tool callingFine-grained tool streaming
    Context management
    Context windowsCompactionContext editingPrompt cachingToken counting
    Files & assets
    Files API
    Agent Skills
    OverviewQuickstartBest practicesSkills for enterpriseClaude API skillUsing Skills with the API
    Agent SDK
    OverviewQuickstartHow the agent loop works
    Streaming InputStream responses in real-timeConnect MCP serversDefine custom toolsTool searchHandling PermissionsUser approvals and inputControl execution with hooksFile checkpointingStructured outputs in the SDKHosting the Agent SDKSecurely deploying AI agentsModifying system promptsSubagents in the SDKSlash Commands in the SDKAgent Skills in the SDKTrack cost and usageTodo ListsPlugins in the SDK
    MCP in the API
    MCP connectorRemote MCP servers
    Claude on 3rd-party platforms
    Amazon BedrockMicrosoft FoundryVertex AI
    Prompt engineering
    OverviewConsole prompting tools
    Test & evaluate
    Define success and build evaluationsUsing the Evaluation ToolReducing latency
    Strengthen guardrails
    Reduce hallucinationsIncrease output consistencyMitigate jailbreaksStreaming refusalsReduce prompt leak
    Administration and monitoring
    Admin API overviewData residencyWorkspacesUsage and Cost APIClaude Code Analytics APIAPI and data retention
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Guides

    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
    • Single Message Input - 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

    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

    Implementation Example

    Single Message Input

    Single message input is simpler but more limited.

    When to Use Single Message Input

    Use single message input when:

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

    Limitations

    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

    Was this page helpful?

    • Overview
    • Streaming Input Mode (Recommended)
    • How It Works
    • Benefits
    • Implementation Example
    • Single Message Input
    • When to Use Single Message Input
    • Limitations
    • Implementation Example
    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

    import { query } from "@anthropic-ai/claude-agent-sdk";
    import { readFile } from "fs/promises";
    
    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: await readFile("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);
      }
    }
    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);
      }
    }