Cortex Code Agent SDK 参考 – TypeScript¶

本主题提供了适用于 TypeScript 的 Cortex Code Agent 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`	可选配置对象（请参阅选项）

一个 Query 对象，它通过额外的控制方法扩展 AsyncGenerator<CortexCodeEvent>。

示例

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"`。请参阅支持的模型。
`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`	用于拦截工具执行及其他代理事件的 Hook 回调。请参阅 Hook。
`settingSources`	`SettingSource[]`	`undefined`	要加载的设置来源。`"user"`、`"project"` 和/或 `"local"` 的数组。
`includePartialMessages`	`boolean`	`false`	包含令牌级别的流式传输事件
`mcpServers`	`Record<string, Record<string, unknown>>`	`undefined`	外部 MCP 服务器配置。键为服务器名称，值为服务器配置（例如 `{ command: "node", args: ["server.js"] }`）。请参阅 MCP 服务器。
`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 用于 SDK 路由的伪工具（例如 AskUserQuestion 和 ExitPlanMode），这些工具包含特定于工具的字段。

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.",
  },
});

Hook¶

Hook 允许您拦截代理事件，例如工具执行。每个 Hook 事件映射到一个匹配器数组，每个匹配器包含一个可选的模式，以及一次或多次回调。

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¶

当代理产生响应时发出。包含一个或多个内容块。

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 Code 配置使用模型和服务直通条款中提供的模型，则您对该模型的使用将进一步受该页面上该模型的条款的约束。

输入和输出的 Data Classification 如下表所示。


输入 Data Classification	输出 Data Classification	名称
Usage Data	客户数据	涵盖的 AI 功能 [1]

有关更多信息，请参阅 Snowflake AI 和 ML。