​
概要

Claude Agent SDKは、エージェントとやり取りするための2つの異なる入力モードをサポートしています：
  • ストリーミング入力モード（デフォルト＆推奨） - 永続的でインタラクティブなセッション
  • 単一メッセージ入力 - セッション状態と再開を使用するワンショットクエリ
このガイドでは、各モードの違い、利点、使用例について説明し、アプリケーションに適したアプローチを選択するのに役立ちます。

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

ストリーミング入力モードは、Claude Agent SDKを使用する推奨方法です。エージェントの機能へのフルアクセスを提供し、豊富でインタラクティブな体験を可能にします。 エージェントが長時間実行されるプロセスとして動作し、ユーザー入力を受け取り、割り込みを処理し、許可リクエストを表示し、セッション管理を処理することを可能にします。

​
動作原理

​
利点

画像アップロード

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

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

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

ツール統合

セッション中のすべてのツールとカスタム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);
  }
}