入力モードが決めるのは、タスクの開始後もアプリケーションから Agent にメッセージを送り続けられるかどうかです。
テキストや画像などのメッセージ内容を区別するものではなく、応答を逐次表示するかどうかを決めるものでもありません。どちらの入力モードでも、SDK は Agent の応答をメッセージストリームとして返します。応答の処理方法はストリーミング出力を参照してください。
Qoder Agent SDK には 2 種類の入力モードがあります。
選択するときは、タスクの開始後も Agent にメッセージを送る必要があるかだけを考えます。
文字列を
Java の単発クエリは、CLI がそのターンの
ストリーミング入力では、タスク開始後もアプリケーションからメッセージを送れます。マルチターンのチャットだけでなく、実行中のタスクに情報を追加する、方向を変える、後で処理するメッセージを予約するといった用途にも使用できます。
推奨インターフェースは SDK ごとに異なります。
TypeScript のメッセージフィールドは
Python の
この形式は、事前に用意したメッセージにだけ使用してください。Agent が返した直後の内容に基づいて次のメッセージを決めることはできず、
Java では、ユーザー入力を受け取る前に CLI を起動しておくこともできます。
Agent の応答中にも別のメッセージを送信できます。
同じ優先度のメッセージは送信順に処理されます。現在の処理方向をすぐに変えるには
Agent にすぐ応答させず、背景情報だけを追加したい場合があります。その場合は TypeScript で
Java の
まだ処理が始まっていないメッセージをキャンセルするには、まずセッション内で一意の UUID を設定します。TypeScript ではメッセージの
キャンセルに成功すると
Java で別のスレッドからセッションを閉じると、読み取り中のカーソルは
| 入力モード | TypeScript | Python | Java | 使用する場面 |
|---|---|---|---|---|
| 単一メッセージ入力 | query({ prompt: string }) | query(prompt=str) | client.query(OneShotQueryRequest) | 1 回限りのタスク、バッチ処理、CI スクリプト |
| ストリーミング入力 | query({ prompt: AsyncIterable<SDKUserMessage> }) | QoderSDKClient を推奨。事前に確定したメッセージストリームは query() にも渡せます | client.openSession(options) が返す QoderSession | チャット UI、複数メッセージのセッション、実行中の情報追加や方向修正 |
- 必要がない場合は、単一メッセージ入力を使用します。
- 必要がある場合、たとえばユーザーが追加で質問する、または Agent の応答に基づいてアプリケーションが次の処理を決める場合は、ストリーミング入力を使用します。
単一メッセージ入力
文字列を query() に渡すと、独立したタスクが開始されます。タスク開始後、この呼び出しに別のユーザーメッセージを追加することはできません。タスクが完了すると、SDK はセッションを終了します。
ResultMessage を返すと終了します。それでもメッセージストリームを最後まで読んでから、カーソルまたは QoderQuery を閉じてください。ResultOutcome.ERROR はそのターンが失敗したことを表し、例外がスローされないことは成功を意味しません。
単一メッセージ入力でもツール承認は利用できます。Agent がまだ許可されていないツールを実行する必要がある場合、canUseTool / can_use_tool でユーザーに確認できます。そのために prompt をメッセージストリームへ変更する必要はありません。詳しくは承認とユーザー入力を参照してください。
ストリーミング入力
ストリーミング入力では、タスク開始後もアプリケーションからメッセージを送れます。マルチターンのチャットだけでなく、実行中のタスクに情報を追加する、方向を変える、後で処理するメッセージを予約するといった用途にも使用できます。
推奨インターフェースは SDK ごとに異なります。
- TypeScript:
AsyncIterable<SDKUserMessage>をquery()に渡します。この非同期イテレーターは、チャット UI、メッセージキュー、その他のイベントから受け取ったユーザーメッセージを継続してyieldできます。 - Python:
QoderSDKClientでセッションを維持します。client.query(...)で新しいメッセージを送り、client.receive_response()でそのターンの応答を受け取ります。 - Java:
client.openSession(options)でQoderSessionを開きます。session.send(...)で新しいメッセージを送り、同じメッセージカーソルから応答を読み取ります。ResultMessageを読み取るとそのターンは終了です。
複数メッセージのセッション
SDKUserMessage を参照してください。Python では、receive_response() ごとに 1 ターンの応答を受け取ります。ResultMessage を受信した後、次のメッセージを送信できます。
Java では、各入力は 1 つの UserInput です。send() の完了は入力が CLI に書き込まれたことを表すだけで、応答の終了を表すものではありません。同じセッションのメッセージストリームは 1 回しか消費できないため、ターンをまたいで同じカーソルを再利用してください。カーソルを閉じるとセッションも閉じられます。
Python 非同期メッセージストリームの境界
Python の query() は AsyncIterable[dict[str, Any]] も受け取ります。すべてのメッセージがタスク開始前に確定している場合は、この方法で順番に送信できます。次のコードは非同期メッセージストリームの中心部分だけを示しています。query と options の作成方法は、前の完全な例を参照してください。
Python
interrupt() の呼び出しやキュー内メッセージのキャンセルもできません。チャット UI などの対話型アプリケーションでは QoderSDKClient を使用してください。
CLI の事前起動(Java)
Java では、ユーザー入力を受け取る前に CLI を起動しておくこともできます。client.prepare(options) は入力を送らずに起動、認証、初期化を完了し、最初のリクエストの起動遅延をなくします:
Java
PreparedQuery は 1 回だけ変換できます。変換後は新しい QoderSession または QoderQuery がリソースの解放を担います。使わないままの場合は close() を呼び出して破棄してください。
Agent の実行中に入力を追加する
Agent の応答中にも別のメッセージを送信できます。priority は Agent がそのメッセージを処理するタイミングを決めます。
| 値 | 動作 |
|---|---|
now | 現在の応答を停止し、このメッセージをすぐに処理する |
next | デフォルト。次の適切なタイミングで処理する |
later | 現在の応答が終わるまで待つ |
priority: 'now' を使用します。新しいメッセージを送らずに現在の応答だけを止めたい場合は、現在の応答を中断するを使用してください。
Java では、UserInput.Builder の priority(SendPriority.NOW / NEXT / LATER) で優先度を設定します。Java の UserInput のデフォルト優先度は next ではなく NOW です。実行中にメッセージを追加するときは、必要に応じて明示的に設定してください。
次のコードは、前述の TypeScript メッセージジェネレーター、接続済みの Python client セッション、または Java の QoderSession 内に配置します。
応答を開始せずコンテキストを追加する
Agent にすぐ応答させず、背景情報だけを追加したい場合があります。その場合は TypeScript で shouldQuery: false、Python で should_query=False、Java で shouldQuery(false) を設定します。メッセージは会話に追加され、いつ有効になるかは priority で決まります。
現在の応答を中断する
interrupt() を呼び出すと、セッションを終了せずに Agent の現在の応答を停止できます。中断後もメッセージを送信できます。TypeScript では query() が返すオブジェクトで呼び出し、Python では QoderSDKClient を使用し、Java では QoderQuery または QoderSession で呼び出します。
interrupt() は InterruptResult を返します。成功は CLI が中断リクエストを受け付けたことを表すだけで、そのターンがいつ終わるかは引き続き ResultMessage で判断します。
interrupt() はキューで待機中のメッセージを削除しません。不要になったメッセージは個別にキャンセルしてください。セッション全体を終了するには、close メソッドを呼び出すか async with ブロックを終了します。
キュー内メッセージをキャンセルする
まだ処理が始まっていないメッセージをキャンセルするには、まずセッション内で一意の UUID を設定します。TypeScript ではメッセージの uuid フィールド、Python では message_uuid 引数を使用します。Java では ID を自分で生成する必要はありません。send(input) の代わりに session.submit(input) で送信すると、返される MessageSubmission に SDK が割り当てた MessageId がすぐに含まれます。
次のコードはキャンセル操作だけを示しており、q / client と対応するメッセージ UUID がすでに作成されていることを前提とします。
true / True、メッセージが存在しない、またはすでに処理が始まっている場合は false / False を返します。UUID のないメッセージは個別にキャンセルできません。同じセッション内で UUID を再利用しないでください。
Java では、まだ CLI に書き込まれていないメッセージは SDK がローカルでキャンセルします。そのメッセージの written() は CancellationException で完了し、セッションには影響しません。すでに書き込みが始まったメッセージは、CLI が対応する capability をサポートしている場合にだけリモートでのキャンセルを試み、それ以外は false を返します。書き込みの確認だけが必要なら send() を、書き込み前に ID が必要なら submit() を使います。
入力を終了してセッションを閉じる
- TypeScript:文字列プロンプトのタスクが完了すると SDK はセッションを終了します。非同期メッセージストリームでは、イテレーターの終了がメッセージ送信の終了を表します。セッション全体を早期に閉じるには、
AbortControllerを使うかq.close()を呼び出します。 - Python:1 回限りの
query()は自動的に終了します。QoderSDKClientではasync withによる自動接続・切断を推奨しますが、connect()/disconnect()を手動で呼び出すこともできます。 - Java:単発クエリはメッセージストリームを最後まで読んだ後、カーソルまたは
QoderQueryを閉じます。QoderSessionは使い終わったら閉じます。受け付けた入力がすべて CLI に書き込まれることを保証したい場合は、先にcompleteInput()を待ってください。completeInput()は以降の入力を拒否しますが、応答は待ちません。QoderClientを閉じると、それが作成したすべてのクエリとセッションも連鎖的に閉じられます。
messages()、options を再利用します。
自動的に閉じる
外部条件に応じて早期に閉じる
SessionClosedException で終了します。SDK のコールバックやプッシュハンドラー内ではブロッキングの close() を呼び出さず、closeAsync() を使用してください。
セッションを閉じた後は、新しいメッセージを送信できません。