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

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

query() には 2 つの入力モードがあります：
  • シングルメッセージクエリモード：1 つのユーザーメッセージを送信し、SDK は応答完了後にセッションを閉じます。クイックスタート を参照してください。
  • マルチメッセージセッションモード：セッションを開いたまま、モデルとマルチターン対話を行います。

​
マルチメッセージセッション

ユーザーメッセージを順番に産出するシーケンスを定義します： 
import { qodercliAuth, query, type SDKUserMessage } from '@qoder-ai/qoder-agent-sdk';

async function* messages(): AsyncGenerator<SDKUserMessage> {
  yield {
    type: 'user',
    message: { role: 'user', content: [{ type: 'text', text: 'Analyze this codebase for security issues' }] },
    parent_tool_use_id: null,
  };

  // 次のメッセージを産出する前に任意の外部条件を待つことができます
  await new Promise((resolve) => setTimeout(resolve, 2000));

  yield {
    type: 'user',
    message: { role: 'user', content: [{ type: 'text', text: 'Now write a short report' }] },
    parent_tool_use_id: null,
  };
}

for await (const msg of query({
  prompt: messages(),
  options: {
    auth: qodercliAuth(),
    allowedTools: ['Read', 'Grep'],
  },
})) {
  if (msg.type === 'result' && msg.subtype === 'success') {
    console.log(msg.result);
  }
}
モデルはユーザーメッセージを受け取るたびに 1 ターン応答します。メッセージシーケンスが終了するとセッションは自動的に閉じます。メッセージフィールドの定義は SDKUserMessage を参照してください。

​
セッションライフサイクルの管理

マルチメッセージセッションでは、query() が返すオブジェクトのライフサイクルは呼び出し側が管理します。SDK はメッセージシーケンスが自然に終了した場合のみセッションを閉じます。それ以外のすべてのケースでは呼び出し側がいつ終了するかを決定する必要があり、さもないとセッションはハングし続けます。 呼び出し側が能動的にクローズを管理する必要がある一般的なシナリオ：
  • メッセージシーケンス自体が終了しない場合、例えば外部入力をループ待ちするジェネレータ： 
    async function* fromUserUI(): AsyncGenerator<SDKUserMessage> {
  while (true) {
    const text = await waitForUserInput();   // UI の入力ソース
    yield {
      type: 'user',
      message: { role: 'user', content: [{ type: 'text', text }] },
      parent_tool_use_id: null,
    };
  }
}
  • メッセージシーケンスが正常に終了する前に終了したい場合：タイムアウト、ユーザーキャンセル、その他のビジネス条件。
2 つのクローズ方法：

​
自動管理（推奨。Node 22+ または explicit resource management 対応ランタイム）

セッションのライフタイムが関数 / コードブロックのスコープと一致する場合に使用します——スコープを抜けると自動的に解放されます。 
{
  await using q = query({ prompt: fromUserUI(), options: { auth: qodercliAuth() } });
  for await (const msg of q) { /* ... */ }
}  // スコープを抜けると自動的にクローズ

​
手動クローズ

クローズのトリガーが外部から来る場合に使用します：タイムアウト、ユーザーのキャンセル、その他のビジネス条件など。 
const q = query({ prompt: fromUserUI(), options: { auth: qodercliAuth() } });
setTimeout(() => q.close(), 30_000);   // 30 秒後に強制クローズ

for await (const msg of q) { /* ... */ }