マルチターンセッションとストリーミング入力

このトピックでは、Cortexコードエージェント SDK にプロンプトを送信するための主な方法について説明します。すなわち、 query() によってセッションのライフサイクルが管理されるようにすることを必要とする場合の 単一プロンプトクエリ 、増分プロンプトを配信するための ストリーミングされる入力、および交換間でコンテキストを維持するインタラクティブな会話のための マルチターンセッション です。

入力パターン

SDK には3つの入力パターンがあります。

モード

使用するタイミング

API

単一プロンプト入力

query() でプロンプトを1つ送信して、SDK によってセッションのライフサイクルが管理されるようにします。エージェントが ResultMessage を生成するまで、出力は引き続きストリーミングされます。

TypeScript およびPythonの両方の query()

ストリーミングされる入力

単一のプロンプト文字列の代わりに、非同期イテラブルからユーザーメッセージを増分送信します

TypeScript およびPythonの両方の query() 、さらに TypeScript の Query.streamInput()

マルチターンセッション

インタラクティブな会話: 複数のプロンプトの送信、コンテキストの維持、セッションのライフサイクルの制御

createCortexCodeSession() （TypeScript）または``CortexCodeSDKClient`` （Python）

単一プロンプトクエリ

query() 関数は、SDK を使用するための最も簡単な方法です。単一のプロンプト文字列または SDK ユーザーメッセージの非同期イテラブルを送信することができ、エージェントが ResultMessage を生成するまでイベントをストリームバックします。このモードでは、「単一のプロンプト」は入力パターンを指します。出力は引き続き正常にストリーミングされます。

import { query } from "cortex-code-agent-sdk";

for await (const message of query({
  prompt: "Explain how the auth module works",
  options: { cwd: process.cwd() },
})) {
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
}

query() 関数は、セッションのライフサイクル全体を管理します。セッションを作成し、プロンプトを送信するとともにイベントを生成して、結果が到達するかイテレーターが使用され残余分がなくなったときにセッションを閉じます。

maxTurns / max_turns とは異なります。単一プロンプトのクエリでは、エージェントは引き続き構成されたターン制限に従い、必要な数の内部ターンを取得することができます。maxTurns: 1 または max_turns=1 の設定は、エージェントを1つの内部ターンに制限する別の制約であり、 error_max_turns 結果を生成する可能性があります。

マルチターンセッション

複数回の交換を必要とする会話には、セッションを使用してください。エージェントはターン間でコンテキストを保持するため、後続のプロンプトは、ファイルの読み取り、分析の実行、先行するターンで説明されたトピックを参照できます。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({ cwd: process.cwd() });

// First turn
await session.send("Read the database connection module");
for await (const event of session.stream()) {
  if (event.type === "assistant") {
    for (const b of event.content) {
      if (b.type === "text") process.stdout.write(b.text);
    }
  }
  if (event.type === "result") break;
}

// Second turn -- context from the first turn is preserved
await session.send("What error handling patterns does it use?");
for await (const event of session.stream()) {
  if (event.type === "assistant") {
    for (const b of event.content) {
      if (b.type === "text") process.stdout.write(b.text);
    }
  }
  if (event.type === "result") break;
}

await session.close();

セッションライフサイクル

  1. createCortexCodeSession(options) を呼び出してセッションを開始します。これにより CLI プロセスが生成されます。

  2. session.send(prompt) を呼び出してユーザーメッセージを送信します。

  3. session.stream() を反復して応答を受信します。result イベントが表示されたら反復を停止します。

  4. 追加のターンを実施する場合は、ステップ2～3を繰り返します。

  5. session.close() を呼び出して、セッションを終了しプロセスをクリーンアップします。

先行するセッションを継続する

先行するセッションから会話を再開することができます。エージェントは以前の会話履歴をロードし、中断したところから続行します。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

// Continue the most recent conversation
const session = await createCortexCodeSession({
  cwd: process.cwd(),
  continue: true,
});

await session.send("What were we working on?");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}
await session.close();

ID によって特定のセッションを再開することもできます。

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
});

セッションをフォークする

フォークすると、既存のセッションの全会話履歴を保持して開始される新しいセッションが作成されます。元のセッションは変更されません。これは、元の会話を失うことなく代替アプローチを検討するのに役立ちます。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const forked = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
  forkSession: true,
});

await forked.send("Let's try a different approach");
for await (const event of forked.stream()) {
  if (event.type === "result") break;
}
await forked.close();

ターンを中断する

アプリケーションは、エージェントがターンを処理している間に中断をリクエストすることができます。これには、CLI の:kbd:Esc を押すのと同じ効果があります。セッションはさらにプロンプトが表示されるまで維持されます。

直接中断呼び出し

interrupt() メソッドを呼び出して中断リクエストを直接送信します。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({ cwd: process.cwd() });

await session.send("Analyze every file in this large codebase");

// Interrupt after 10 seconds
setTimeout(() => session.interrupt(), 10_000);

for await (const event of session.stream()) {
  if (event.type === "result") break;
}

// Session is still alive -- send another prompt
await session.send("Just summarize the top-level structure instead");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

await session.close();

コントローラーを停止/イベントを中止

セッション作成時に中止シグナルを渡すこともできます。信号が起動すると、SDK は自動的に同じ中断リクエストを送信します。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const controller = new AbortController();

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  abortController: controller,
});

await session.send("Analyze every file in this large codebase");

// Trigger interrupt from anywhere
setTimeout(() => controller.abort(), 10_000);

for await (const event of session.stream()) {
  if (event.type === "result") break;
}
await session.close();

注釈

TypeScript で、abort() メソッドにより中断リクエストをトリガーする AbortController を渡します。Pythonでは、set() メソッドにより中断リクエストをトリガーする asyncio.Event を渡します。どちらの場合も、セッションは中断後も有効です。