概要
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 ブロックでラップしてください。結果サブタイプについては、結果を処理するを参照してください。