​
概要

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

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

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

​
動作原理

​
利点

画像アップロード

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

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

順次処理される複数のメッセージを送信し、中断する機能

ツール統合

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

フックサポート

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

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

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

コンテキストの永続化

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

​
実装例

import { query } from "@anthropic-ai/claude-code";
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);
  }
}

​
単一メッセージ入力

単一メッセージ入力はより簡単ですが、より制限があります。

​
単一メッセージ入力を使用する場合

以下の場合に単一メッセージ入力を使用してください：
  • ワンショットレスポンスが必要な場合
  • 画像添付、フックなどが不要な場合
  • Lambda関数などのステートレス環境で動作する必要がある場合

​
制限事項

単一メッセージ入力モードは以下をサポートしません：
  • メッセージ内の直接的な画像添付
  • 動的メッセージキューイング
  • リアルタイム中断
  • フック統合
  • 自然な複数ターン会話

​
実装例

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

// シンプルなワンショットクエリ
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);
  }
}