Cortex Codeエージェント SDK 参照 -- TypeScript¶

このトピックでは、すべての関数、型およびインターフェースを含む、TypeScript 用Cortex Codeエージェント SDK のすべての API リファレンスを示します。

インストール¶

npm install cortex-code-agent-sdk

Node.js 18以降が必要です。パッケージは ESM のみです。SDK はCortex Code CLI が個別にインストールされることを想定しています。PATH にない場合は、CORTEX_CODE_CLI_PATH=/path/to/cortex を設定するか、セッションオプションの cliPath を渡します。

関数¶

query()¶

Cortex Codeと対話するための主要な関数。メッセージが届くとメッセージをストリーミングする非同期ジェネレーターを作成します。

function query({
  prompt,
  options,
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: CortexCodeSessionOptions;
}): Query;

パラメーター


パラメーター	型	説明
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	単一のユーザープロンプト、またはストリーミング入力用の SDK ユーザーメッセージの非同期イテラブル
`options`	`CortexCodeSessionOptions \| undefined`	オプションの構成オブジェクト（オプションを参照）

戻り値

追加の制御メソッドを使用して AsyncGenerator<CortexCodeEvent> を拡張する Query オブジェクト。

例

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

for await (const message of query({
  prompt: "Fix the bug in utils.py",
  options: { cwd: "/path/to/project" },
})) {
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }
  if (message.type === "result") {
    console.log("Done:", message.subtype);
  }
}

createCortexCodeSession()¶

マルチターン会話のための永続的なセッションを作成します。

function createCortexCodeSession(
  options: CortexCodeSessionOptions
): Promise<CortexCodeSession>;

例

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

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  model: "claude-sonnet-4-6",
  permissionMode: "bypassPermissions",
  allowDangerouslySkipPermissions: true,
});

await session.send("What files are here?");
for await (const event of session.stream()) {
  if (event.type === "assistant") { /* handle */ }
  if (event.type === "result") break;
}

// Send another prompt (same context)
await session.send("Now refactor the main function");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

await session.close();

クエリオブジェクト¶

query() によって返されます。AsyncGenerator<CortexCodeEvent> を拡張します。


メソッド	説明
`interrupt(): Promise<void>`	基盤となるプロセスに SIGINT を送信する
`setPermissionMode(mode: PermissionMode): Promise<void>`	アクティブなクエリの後続のターンのために権限モードを変更する
`setModel(model: string): Promise<void>`	後続のターンのためにモデルを変更する
`initializationResult(): Promise<QueryInitializationResult>`	CLI から初期化ハンドシェイクメタデータを返す
`supportedCommands(): Promise<SlashCommand[]>`	CLI によってアドバタイズされている場合に、初期化応答からスラッシュコマンドメタデータを返す
`supportedModels(): Promise<ModelInfo[]>`	CLI によってアドバタイズされている場合に、初期化応答からモデルメタデータを返す
`supportedAgents(): Promise<AgentInfo[]>`	CLI によってアドバタイズされている場合に、初期化応答からカスタムエージェントメタデータを返す
`accountInfo(): Promise<AccountInfo>`	CLI によってアドバタイズされている場合に、初期化応答からアカウントメタデータを返す
`streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>`	追加の SDK ユーザーメッセージをアクティブなクエリにストリーミングする
`stopTask(taskId: string): Promise<void>`	ID によって実行中のバックグラウンドタスクをキャンセルする
`close(): void`	セッションを閉じてプロセスを終了する

CortexCodeSession インターフェース¶

createCortexCodeSession() によって返されます。マルチターンの会話をサポートし、 await using と併用する AsyncDisposable （Node.js 24+）を実装します。


プロパティ / メソッド	説明
`pid: number \| undefined`	基盤となる CLI プロセスの PID
`send(message: string \| SDKUserMessage): Promise<void>`	プレーンテキストまたは構造化された SDK ユーザーメッセージを送信する
`stream(): AsyncGenerator<CortexCodeEvent>`	エージェントからのストリームイベント
`initializationResult(): Promise<QueryInitializationResult>`	CLI から初期化ハンドシェイクメタデータを返す
`interrupt(): Promise<void>`	中断シグナルを送信する
`setPermissionMode(mode: PermissionMode): Promise<void>`	セッション内の後続のターンのために権限モードを変更する
`setModel(model: string): Promise<void>`	セッションの途中でモデルを変更する
`stopTask(taskId: string): Promise<void>`	ID によって実行中のバックグラウンドタスクをキャンセルする
`close(): Promise<void>`	セッションを終了してプロセスを終了する
`[Symbol.asyncDispose](): Promise<void>`	`close()` を呼び出します。`await using session = ...` 構文を有効にします。

オプション¶

query() または createCortexCodeSession() に渡された構成。


オプション	型	デフォルト	説明
`cwd`	`string`	現在のプロセスの作業ディレクトリ	セッションの作業ディレクトリ。省略された場合、 SDK は現在のプロセス作業ディレクトリを継承します。
`model`	`string`	CLI のデフォルト	使用するモデル。`"auto"` を使用して自動選択にするか、 `"claude-sonnet-4-6"` のような特定の識別子を使用します。Supported models をご参照ください。
`connection`	`string`	CLI のデフォルト	Snowflake CLI接続設定のSnowflake接続名、通常は `~/.snowflake/connections.toml` で、 `~/.snowflake/config.toml` も既存のセットアップについてサポートされています。省略された場合、CLIはTOMLファイルの `default_connection_name` を使用します。接続の構成をご参照ください。
`profile`	`string`	`undefined`	プロファイル名（ロード元 `~/.snowflake/cortex/profiles/` ）
`resume`	`string`	`undefined`	以前の会話を再開するためのセッション ID
`continue`	`boolean`	`false`	最新の会話を続けます。セッション ID を必要とせずに最後のセッションを再開します。
`forkSession`	`boolean`	`false`	そのまま継続する代わりに、再開されたセッションを新しいセッション ID にフォークします。`resume` と併用します。
`sessionId`	`string`	`undefined`	会話のための明示的なセッション ID。省略された場合、CLI は自動的に生成します。
`permissionMode`	`string`	`"default"`	`"default"` \| `"autoAcceptPlans"` \| `"plan"` \| `"bypassPermissions"` 。注意: `"bypassPermissions"` には `allowDangerouslySkipPermissions: true` が必要です。`"plan"` モードでは、 `AskUserQuestion` および `ExitPlanMode` を `canUseTool` を介してルーティングできます。 `ExitPlanMode` を拒否すると計画をアクティブに保ち、承認すると計画モードが終了し、後で通常の権限が再開します。
`allowDangerouslySkipPermissions`	`boolean`	`false`	`permissionMode: "bypassPermissions"` を使用する場合は安全フラグが必要です。このフラグだけでは権限をバイパスしません。permissionModeを介して明示的にリクエストされた場合にのみバイパスを許可します。
`allowedTools`	`string[]`	`undefined`	プロンプトなしで自動承認するためのツール
`disallowedTools`	`string[]`	`undefined`	常に拒否するツール
`canUseTool`	CanUseTool	`undefined`	各ツールの実行前に呼び出されるカスタム許可ハンドラー。canUseTool コールバックをご参照ください。
`permissionPromptToolName`	`string`	`undefined`	許可プロンプトに使用される MCP ツールの名前。`canUseTool` が提供されると、 SDK は自動的に `"stdio"` を使用します。
`maxTurns`	`number`	`undefined`	停止する前のエージェントのターンの最大数。最大数に達すると、セッションは `error_max_turns` 結果を出力します。
`effort`	`string`	`undefined`	モデルの思考エフォートレベル。`"minimal"` 、 `"low"`, 、 `"medium"` 、 `"high"` 、 `"max"` のいずれか。
`additionalDirectories`	`string[]`	`undefined`	セッションで利用できるようにする追加の作業ディレクトリ
`plugins`	`Array<string \| { type: "local"; path: string }>`	`undefined`	ロードするプラグインディレクトリ。パスを文字列または `{ type: "local", path: "..." }` オブジェクトとして受け入れます。
`env`	`Record<string, string \| undefined>`	`undefined`	生成されたプロセス環境にマージされた環境変数。キーを `undefined` に設定して継承された変数を削除します。
`abortController`	`AbortController`	`undefined`	コントローラーに対する `abort()` を呼び出して中断シグナルを送信します。セッションはさらにプロンプトが表示されるまで維持されます。CLI の ESC を押すのと同じです。
`systemPrompt`	`string \| SystemPromptPreset`	`undefined`	カスタムシステムプロンプト。文字列を渡してデフォルトを完全に置き換えるか、SystemPromptPreset を渡して拡張します。
`appendSystemPrompt`	`string`	`undefined`	デフォルトのシステムプロンプトに追加されたテキスト。これを使用して、組み込みのプロンプトを置き換えずに指示を追加します。
`hooks`	`Partial<Record<HookEvent, HookMatcher[]>>`	`undefined`	ツール実行とその他のエージェントイベントをインターセプトするためのフックコールバック。フックをご参照ください。
`settingSources`	`SettingSource[]`	`undefined`	ロードするソースの設定。`"user"` 、 `"project"` および/または `"local"` の配列。
`includePartialMessages`	`boolean`	`false`	トークンレベルのストリーミングイベントが含まれるようにする
`mcpServers`	`Record<string, Record<string, unknown>>`	`undefined`	外部 MCP サーバー構成。キーはサーバー名であり、値はサーバー構成です（例: `{ command: "node", args: ["server.js"] }`）。MCP servers をご参照ください。
`noMcp`	`boolean`	`false`	MCP サーバーを無効化
`outputFormat`	`{ type: "json_schema"; schema: object }`	`undefined`	構造化出力 -- JSON スキーマに基づいて最終的な応答を検証する
`cliPath`	`string`	`process.env.CORTEX_CODE_CLI_PATH ?? "cortex"`	カスタム CLI バイナリへのパス。省略された場合、SDKは最初に `CORTEX_CODE_CLI_PATH` をチェックし、それ以外の場合は、 `PATH` の `cortex` にフォールバックします。
`extraArgs`	`Record<string, string \| null>`	`undefined`	キーと値のペアとしての追加の CLI 引数

canUseTool コールバック¶

各ツールの実行前に呼び出されるカスタム許可ハンドラー。ツールの呼び出しが続行されるかどうかを制御するために、許可または拒否の結果を返します。

多くの通常のツール権限チェックでは、コールバック入力には { action, resource } などのフィールドが含まれます。これらのチェックには、許可/拒否の結果とオプションの拒否メッセージが使用されます。 updatedInput はツール固有のフィールドを含む AskUserQuestion や ExitPlanMode などの SDK ルーティング擬似ツールで使用されます。

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  context: ToolPermissionContext,
) => Promise<PermissionResult>;

type ToolPermissionContext = {
  signal: AbortSignal;
  blockedPath?: string;
  decisionReason?: string;
  toolUseID: string;
  agentID?: string;
};

type PermissionResult = PermissionResultAllow | PermissionResultDeny;

type PermissionResultAllow = {
  behavior: "allow";
  updatedInput?: Record<string, unknown>;
  toolUseID?: string;
};

type PermissionResultDeny = {
  behavior: "deny";
  message?: string;
  interrupt?: boolean;
  toolUseID?: string;
};

例

const session = await createCortexCodeSession({
  cwd: process.cwd(),
 canUseTool: async (toolName, input, context) => {
   if (toolName === "Write" && String(input.resource).endsWith(".env")) {
     return { behavior: "deny", message: "Destructive commands not allowed" };
   }
   return { behavior: "allow" };
  },
});

SystemPromptPreset¶

システムプロンプトを完全に置き換える代わりに、事前設定オブジェクトを使用して組み込みプロンプトを拡張します。

type SystemPrompt = string | SystemPromptPreset;

type SystemPromptPreset = {
  type: "preset";
  append?: string;
};

例

// Replace the system prompt entirely
const session1 = await createCortexCodeSession({
  cwd: process.cwd(),
  systemPrompt: "You are a code reviewer. Prioritize finding issues and suggesting fixes.",
});

// Extend the default prompt
const session2 = await createCortexCodeSession({
  cwd: process.cwd(),
  systemPrompt: {
    type: "preset",
    append: "Always write tests for any code you create.",
  },
});

フック¶

フックを使用すると、ツール実行などのエージェントイベントをインターセプトできます。各フックイベントは一致の配列にマッピングされ、各一致にはオプションのパターンと1つ以上のコールバックが含まれます。

type HookEvent =
  | "PreToolUse" | "PostToolUse" | "UserPromptSubmit"
  | "Stop" | "SubagentStop" | "PreCompact"
  | "Notification" | "PermissionRequest";

type HookMatcher = {
  matcher?: string;       // Match value pattern (optional)
  hooks: HookCallback[];
  timeout?: number;       // Timeout in seconds
};

type HookCallback = (
  input: HookInput,
  toolUseId: string | null,
  context: HookContext,
) => Promise<HookOutput>;

例

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  hooks: {
    PostToolUse: [
      {
        matcher: "Write",
        hooks: [
          async (input, toolUseId, context) => {
            console.log("File written:", input.tool_input?.file_path);
            return { continue: true };
          },
        ],
      },
    ],
  },
});

メッセージタイプ¶

query() および session.stream() によって生成されたイベント:

SDKAssistantMessage¶

エージェントが応答を生成するときに出力されます。1つ以上のコンテンツブロックが含まれます。

type SDKAssistantMessage = {
  type: "assistant";
  content: ContentBlock[];
  message: {
    role: "assistant";
    content: ContentBlock[];
    model: string;
  };
  session_id: string;
}

SDKResultMessage¶

エージェントがターンを終了したときに出力します。成功またはエラーについて subtype を確認します。

type SDKResultMessage =
  | { type: "result"; subtype: "success"; is_error: false; result: string; session_id: string; }
  | { type: "result"; subtype: "error_during_execution" | "error_max_turns" | "error_max_budget_usd";
      is_error: true; errors: string[]; session_id: string; }

SDKUserMessage¶

ユーザーメッセージが処理されたときにエコーバックされます。

type SDKUserMessage = {
  type: "user";
  message: { role: "user"; content: ContentBlock[]; };
  session_id: string;
}

SDKSystemMessage¶

セッションの初期化などのシステムイベント。

type SDKSystemMessage = {
  type: "system";
  subtype: string;  // e.g. "init"
  session_id: string;
}

コンテンツブロック¶


型	フィールド
`TextBlock`	`{ type: "text", text: string }`
`ThinkingBlock`	`{ type: "thinking", thinking: string }`
`ToolUseBlock`	`{ type: "tool_use", id: string, name: string, input: object }`
`ToolResultBlock`	`{ type: "tool_result", tool_use_id: string, content: string }`

ストリーミングイベント¶


型	説明
`SDKPartialAssistantMessage`	部分的なテキスト/思考ストリーミング（`includePartialMessages: true` が必要）
`StdErrEvent`	`{ type: "stderr", data: string }` -- CLI からのstderr
`ParseErrorEvent`	`{ type: "parse_error", raw: string, error: string }`

SDKPartialAssistantMessage は、部分的なテキストと思考ブロック用に出力されます。完了したツール呼び出しは引き続き AssistantMessage ブロックとして到達し、ツールの結果は UserMessage ブロックとして引き続き到達します。

構造化出力¶

JSON スキーマと一致する応答を返すようにエージェントに強制します。

const result = query({
  prompt: "Analyze the codebase and return a summary",
  options: {
    cwd: process.cwd(),
    outputFormat: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          languages: { type: "array", items: { type: "string" } },
          file_count: { type: "number" },
          summary: { type: "string" },
        },
        required: ["languages", "file_count", "summary"],
      },
    },
  },
});

for await (const msg of result) {
  if (msg.type === "result" && msg.subtype === "success") {
    // The final text content will be valid JSON matching the schema
  }
}

詳細については、構造化出力をご参照ください。

エラー処理¶

try {
  for await (const message of query({ prompt: "...", options: { cwd: "." } })) {
    if (message.type === "result" && message.is_error) {
      console.error("Agent error:", message.errors.join(", "));
    }
  }
} catch (err) {
  // Thrown if the CLI binary is not found, session fails to start, etc.
  console.error("SDK error:", err.message);
}

法的通知¶

Cortexコードの設定が `モデルとサービスのパススルー規約<https://www.snowflake.com/en/legal/optional-offerings/offering-specific-terms/ai-features/model-pass-through-terms/>`__ において提供されるモデルを使用する場合、そのモデルの使用にはそのページにあるモデルの規約も適用されます。

インプットとアウトプットのデータ分類は以下の表の通りです。


入力データの分類	出力データの分類	指定
Usage Data	顧客データ	カバーされているAI機能[1]_

詳細については、 Snowflake AI と ML をご参照ください。