ガイド

ストリーミング入力

Claude Agent SDKの2つの入力モードとそれぞれの使用場面について理解する

概要

Claude Agent SDKは、エージェントとやり取りするための2つの異なる入力モードをサポートしています：

ストリーミング入力モード（デフォルト＆推奨） - 永続的でインタラクティブなセッション
単一メッセージ入力 - セッション状態と再開を使用するワンショットクエリ

このガイドでは、各モードの違い、利点、使用例について説明し、アプリケーションに適したアプローチを選択するのに役立ちます。

ストリーミング入力モード（推奨）

ストリーミング入力モードは、Claude Agent SDKを使用する推奨方法です。エージェントの機能へのフルアクセスを提供し、豊富でインタラクティブな体験を可能にします。

エージェントが長時間実行されるプロセスとして動作し、ユーザー入力を受け取り、割り込みを処理し、許可リクエストを表示し、セッション管理を処理することを可能にします。

動作原理

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

利点

画像アップロード

視覚的分析と理解のためにメッセージに直接画像を添付

キューイングされたメッセージ

順次処理される複数のメッセージを送信、割り込み可能

ツール統合

セッション中のすべてのツールとカスタムMCPサーバーへのフルアクセス

フックサポート

様々なポイントで動作をカスタマイズするためのライフサイクルフックを使用

リアルタイムフィードバック

最終結果だけでなく、生成される応答をリアルタイムで確認

コンテキストの永続化

複数のターンにわたって会話コンテキストを自然に維持

実装例

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

async function* generateMessages() {
  // 最初のメッセージ
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "このコードベースをセキュリティ問題について分析してください"
    }
  };
  
  // 条件またはユーザー入力を待機
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // 画像付きのフォローアップ
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "このアーキテクチャ図をレビューしてください"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// ストリーミング応答を処理
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";

// シンプルなワンショットクエリ
for await (const message of query({
  prompt: "認証フローを説明してください",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// セッション管理で会話を継続
for await (const message of query({
  prompt: "次に認可プロセスを説明してください",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

ガイド

ストリーミング入力

Claude Agent SDKの2つの入力モードとそれぞれの使用場面について理解する

概要

Claude Agent SDKは、エージェントとやり取りするための2つの異なる入力モードをサポートしています：

ストリーミング入力モード（デフォルト＆推奨） - 永続的でインタラクティブなセッション
単一メッセージ入力 - セッション状態と再開を使用するワンショットクエリ

このガイドでは、各モードの違い、利点、使用例について説明し、アプリケーションに適したアプローチを選択するのに役立ちます。

ストリーミング入力モード（推奨）

動作原理

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

利点

画像アップロード

視覚的分析と理解のためにメッセージに直接画像を添付

キューイングされたメッセージ

順次処理される複数のメッセージを送信、割り込み可能

ツール統合

セッション中のすべてのツールとカスタムMCPサーバーへのフルアクセス

フックサポート

様々なポイントで動作をカスタマイズするためのライフサイクルフックを使用

リアルタイムフィードバック

最終結果だけでなく、生成される応答をリアルタイムで確認

コンテキストの永続化

複数のターンにわたって会話コンテキストを自然に維持

実装例

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

async function* generateMessages() {
  // 最初のメッセージ
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "このコードベースをセキュリティ問題について分析してください"
    }
  };
  
  // 条件またはユーザー入力を待機
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // 画像付きのフォローアップ
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "このアーキテクチャ図をレビューしてください"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// ストリーミング応答を処理
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";

// シンプルなワンショットクエリ
for await (const message of query({
  prompt: "認証フローを説明してください",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// セッション管理で会話を継続
for await (const message of query({
  prompt: "次に認可プロセスを説明してください",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}