メインコンテンツへスキップ

概要

Claude Agent SDK は、エージェントと対話するための 2 つの異なる入力モードをサポートしています。
  • ストリーミング入力モード(デフォルト&推奨)- 永続的でインタラクティブなセッション
  • シングルメッセージ入力 - セッション状態を使用して再開する 1 回限りのクエリ
このガイドでは、各モードの違い、利点、ユースケースについて説明し、アプリケーションに適したアプローチを選択するのに役立てます。 ストリーミング入力モードは、Claude Agent SDK を使用する推奨される方法です。エージェントの機能へのフルアクセスを提供し、豊かでインタラクティブなエクスペリエンスを実現します。 エージェントが長期間実行されるプロセスとして動作し、ユーザー入力を受け取り、割り込みを処理し、権限リクエストを表示し、セッション管理を処理することができます。

仕組み

利点

画像アップロード

メッセージに画像を直接添付して、ビジュアル分析と理解を実現

キューに入れたメッセージ

複数のメッセージを順序立てて処理し、割り込み機能を備えて送信

ツール統合

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

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

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

コンテキスト永続性

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

実装例

TypeScript SDK では、例えば読み込むファイルが見つからない場合など、メッセージジェネレータが例外をスローすると、ストリームは元のエラーではなく「Claude Code process aborted by user」というエラーで終了するため、そのメッセージが表示された場合は、まずジェネレータ内のコードを確認してください。エラーの前に、バンドルされた SDK ソースの長い縮小化された行が表示される場合もあるため、出力の最後まで読んでエラーテキストを確認してください。Python SDK では、ジェネレータの例外はデバッグレベルでログに記録され、セッションは例外を発生させずにスタールします。そのため、ストリーミングセッションが出力なくハングする場合は、デバッグログを有効にしてジェネレータを確認してください。

シングルメッセージ入力

シングルメッセージ入力はより単純ですが、より制限されています。

シングルメッセージ入力を使用する場合

シングルメッセージ入力は以下の場合に使用してください。
  • 1 回限りのレスポンスが必要な場合
  • 画像添付またはセッション中の制御メソッドが不要な場合
  • Lambda 関数などのステートレス環境で動作する必要がある場合

制限事項

シングルメッセージ入力モードは以下をサポートしていません
  • メッセージ内の直接的な画像添付
  • 動的なメッセージキューイング
  • リアルタイム割り込み
  • 自然なマルチターン会話
クエリが error_max_turns などのエラー結果で終了する場合、シングルメッセージの query() 呼び出しは最終結果メッセージを生成した後、失敗テキストを含むエラーを発生させます。コードが続行する必要がある場合は、ループを try ブロックでラップしてください。結果サブタイプについては、結果を処理するを参照してください。

実装例