多轮对话

query() 有两种输入模式：

• 单消息查询模式：一次提交一条用户消息，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);
  }
}

模型每收到一条用户消息回一轮，消息序列结束后会话自动关闭。消息字段定义见 SDKUserMessage。

​

管理会话生命周期

多消息会话下，query() 返回对象的生命周期由调用方掌握。SDK 只会在消息序列自然结束时顺带关闭会话；其余情况都需要调用方主动决定何时收尾，否则会话会一直挂着。

常见的需要调用方主动管理的场景：

• 消息序列本身不会结束，例如循环等外部输入的 generator：

  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,
      };
    }
  }
  

• 想在消息序列正常结束之前提前终止：超时、用户取消、其他业务条件。

两种关闭方式：

​

自动管理（推荐，Node 22+ 或支持显式资源管理的运行时）

适合会话生命周期和某个函数 / 代码块一致的场景，离开作用域时自动释放。

{
  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) { /* ... */ }