Referência do SDK do Cortex Code Agent – TypeScript¶

Este tópico apresenta a referência completa da API para o SDK do Cortex Code Agent para TypeScript, incluindo todas as funções, os tipos e as interfaces.

Instalação¶

npm install cortex-code-agent-sdk

Requer o Node.js 18 ou posterior. O pacote é somente ESM. O SDK espera que a Cortex Code CLI seja instalada separadamente. Se ela não estiver em seu PATH, defina CORTEX_CODE_CLI_PATH=/path/to/cortex ou passe cliPath nas opções de sessão.

Funções¶

query()¶

A função primária para interagir com o Cortex Code. Cria um gerador assíncrono que transmite as mensagens conforme elas chegam.

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

Parâmetros


Parâmetro	Tipo	Descrição
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	Um prompt de usuário único ou um iterável assíncrono de mensagens de usuário do SDK para entrada de streaming
`options`	`CortexCodeSessionOptions \| undefined`	Objeto de configuração opcional (consulte Opções)

Retornos

Um objeto Query que estende AsyncGenerator<CortexCodeEvent> com métodos de controle adicionais.

Exemplo

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()¶

Cria uma sessão persistente para conversas multiturno.

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

Exemplo

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();

Objeto de consulta¶

Retornado por query(). Estende AsyncGenerator<CortexCodeEvent>.


Método	Descrição
`interrupt(): Promise<void>`	Enviar SIGINT ao processo subjacente
`setPermissionMode(mode: PermissionMode): Promise<void>`	Alterar o modo de permissão para turnos posteriores na consulta ativa
`setModel(model: string): Promise<void>`	Alterar o modelo dos turnos subsequentes
`initializationResult(): Promise<QueryInitializationResult>`	Retornar os metadados de handshake de inicialização da CLI
`supportedCommands(): Promise<SlashCommand[]>`	Retornar os metadados do comando barra da resposta de inicialização, quando anunciados pela CLI
`supportedModels(): Promise<ModelInfo[]>`	Retornar os metadados do modelo da resposta de inicialização, quando anunciados pela CLI
`supportedAgents(): Promise<AgentInfo[]>`	Retornar os metadados do agente personalizado da resposta de inicialização, quando anunciados pela CLI
`accountInfo(): Promise<AccountInfo>`	Retornar os metadados da conta da resposta de inicialização, quando anunciados pela CLI
`streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>`	Transmitir mensagens adicionais de usuários do SDK para a consulta ativa
`stopTask(taskId: string): Promise<void>`	Cancelar uma tarefa em execução em segundo plano por ID
`close(): void`	Encerrar a sessão e terminar o processo

Interface CortexCodeSession¶

Retornado por createCortexCodeSession(). Oferece suporte a conversas multiturno e implementações AsyncDisposable para uso com await using (Node.js 24+).


Propriedade/método	Descrição
`pid: number \| undefined`	PID do processo da CLI subjacente
`send(message: string \| SDKUserMessage): Promise<void>`	Enviar uma mensagem de usuário do SDK estruturada ou em texto simples
`stream(): AsyncGenerator<CortexCodeEvent>`	Eventos de streaming do agente
`initializationResult(): Promise<QueryInitializationResult>`	Retornar os metadados de handshake de inicialização da CLI
`interrupt(): Promise<void>`	Enviar sinal de interrupção
`setPermissionMode(mode: PermissionMode): Promise<void>`	Alterar o modo de permissão para turnos posteriores na sessão
`setModel(model: string): Promise<void>`	Alterar o modelo no meio da sessão
`stopTask(taskId: string): Promise<void>`	Cancelar uma tarefa em execução em segundo plano por ID
`close(): Promise<void>`	Encerrar a sessão e terminar o processo
`[Symbol.asyncDispose](): Promise<void>`	Chama `close()`. Habilita a sintaxe `await using session = ...`.

Opções¶

Configuração passada para query() ou createCortexCodeSession().


Opção	Tipo	Padrão	Descrição
`cwd`	`string`	Diretório de trabalho do processo atual	Diretório de trabalho da sessão. Se omitido, o SDK herda o diretório de trabalho do processo atual.
`model`	`string`	Padrão da CLI	Modelo a ser usado. Use `"auto"` para seleção automática ou um identificador específico, como `"claude-sonnet-4-6"`. Consulte Modelos compatíveis.
`connection`	`string`	Padrão da CLI	Nome da conexão do Snowflake conforme as configurações de conexão na Snowflake CLI, normalmente `~/.snowflake/connections.toml`, com `~/.snowflake/config.toml` também compatível com as configurações existentes. Se omitido, a CLI usa `default_connection_name` do arquivo TOML. Consulte Configurando as conexões.
`profile`	`string`	`undefined`	Nome do perfil (carrega de `~/.snowflake/cortex/profiles/`)
`resume`	`string`	`undefined`	ID da sessão para retomar uma conversa anterior
`continue`	`boolean`	`false`	Continuar a conversa mais recente. Retoma a última sessão sem precisar do ID da sessão.
`forkSession`	`boolean`	`false`	Bifurcar uma sessão retomada para um novo ID de sessão em vez de continuar no local. Use com `resume`.
`sessionId`	`string`	`undefined`	ID de sessão explícito da conversa. Se omitido, a CLI gera um automaticamente.
`permissionMode`	`string`	`"default"`	`"default"` \| `"autoAcceptPlans"` \| `"plan"` \| `"bypassPermissions"`. Observação: `"bypassPermissions"` requer `allowDangerouslySkipPermissions: true`. No modo `"plan"`, é possível rotear `AskUserQuestion` e `ExitPlanMode` por `canUseTool`. Negar `ExitPlanMode` mantém o planejamento ativo e aprová-lo sai do modo de plano para que os turnos posteriores retomem as permissões normais.
`allowDangerouslySkipPermissions`	`boolean`	`false`	Sinalizador de segurança necessário ao usar `permissionMode: "bypassPermissions"`. Esse sinalizador sozinho não ignora as permissões; ele apenas permite o bypass quando solicitado explicitamente por permissionMode.
`allowedTools`	`string[]`	`undefined`	Ferramentas para aprovação automática sem prompt
`disallowedTools`	`string[]`	`undefined`	Ferramentas para negar sempre
`canUseTool`	CanUseTool	`undefined`	Manipulador de permissão personalizado chamado antes de cada execução de ferramenta. Consulte Retorno de chamada de canUseTool.
`permissionPromptToolName`	`string`	`undefined`	Nome da ferramenta MCP usada para prompts de permissão. Quando `canUseTool` é fornecido, o SDK usa automaticamente `"stdio"`.
`maxTurns`	`number`	`undefined`	Número máximo de turnos agênticos antes de parar. Quando atingido, a sessão emite um resultado `error_max_turns`.
`effort`	`string`	`undefined`	Nível de esforço de raciocínio do modelo. Um dos seguintes: `"minimal"`, `"low"`, `"medium"`, `"high"` ou `"max"`.
`additionalDirectories`	`string[]`	`undefined`	Diretórios de trabalho adicionais a serem disponibilizados para a sessão
`plugins`	`Array<string \| { type: "local"; path: string }>`	`undefined`	Diretórios de plug-ins a serem carregados. Aceita caminhos como cadeias de caracteres ou objetos `{ type: "local", path: "..." }`.
`env`	`Record<string, string \| undefined>`	`undefined`	Variáveis de ambiente mescladas no ambiente do processo gerado. Defina uma chave como `undefined` para remover uma variável herdada.
`abortController`	`AbortController`	`undefined`	Enviar um sinal de interrupção chamando `abort()` no controlador. A sessão continua ativa para receber outros prompts. Equivalente a pressionar ESC na CLI.
`systemPrompt`	`string \| SystemPromptPreset`	`undefined`	Prompt do sistema personalizado. Passe uma cadeia de caracteres para substituir completamente o padrão, ou SystemPromptPreset para estendê-lo.
`appendSystemPrompt`	`string`	`undefined`	Texto anexado ao prompt padrão do sistema. Use-o para adicionar instruções sem substituir o prompt interno.
`hooks`	`Partial<Record<HookEvent, HookMatcher[]>>`	`undefined`	Retornos de chamada de gancho para interceptar a execução de ferramentas e outros eventos do agente. Consulte Ganchos.
`settingSources`	`SettingSource[]`	`undefined`	Fontes de configuração a serem carregadas. Matriz de `"user"`, `"project"` e/ou `"local"`.
`includePartialMessages`	`boolean`	`false`	Incluir eventos de streaming no nível do token
`mcpServers`	`Record<string, Record<string, unknown>>`	`undefined`	Configurações do servidor MCP externo. As chaves são nomes de servidores, os valores são configurações de servidor (por exemplo, `{ command: "node", args: ["server.js"] }`). Consulte MCP servers.
`noMcp`	`boolean`	`false`	Desabilitar servidores MCP
`outputFormat`	`{ type: "json_schema"; schema: object }`	`undefined`	Saída estruturada: valida a resposta final em relação ao esquema JSON
`cliPath`	`string`	`process.env.CORTEX_CODE_CLI_PATH ?? "cortex"`	Caminho para o binário personalizado da CLI. Se omitido, o SDK primeiro verifica``CORTEX_CODE_CLI_PATH`` e, caso contrário, retorna para `cortex` em `PATH`.
`extraArgs`	`Record<string, string \| null>`	`undefined`	Argumentos de CLI adicionais como pares chave-valor

Retorno de chamada de canUseTool¶

Um manipulador de permissão personalizado chamado antes de cada execução de ferramenta. Retornam um resultado de permissão ou negação para controlar se a chamada da ferramenta deve continuar.

Para muitas verificações comuns de permissão de ferramentas, a entrada do retorno de chamada contém campos como { action, resource }. O resultado de permitir/negar e a mensagem de negação opcional são usados nestas verificações. updatedInput é usado para pseudoferramentas roteadas por SDK, como AskUserQuestion e ExitPlanMode, que contêm campos específicos da ferramenta.

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

Exemplo

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¶

Em vez de substituir totalmente o prompt do sistema, use um objeto predefinido para estender o prompt interno.

type SystemPrompt = string | SystemPromptPreset;

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

Exemplo

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

Ganchos¶

Os ganchos permitem interceptar eventos do agente, como a execução de ferramentas. Cada evento de gancho é mapeado para uma matriz de correspondências, e cada correspondente contém um padrão opcional e um ou mais retornos de chamada.

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

Exemplo

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

Tipos de mensagem¶

Eventos produzidos por query() e session.stream():

SDKAssistantMessage¶

Emitida quando o agente produz uma resposta. Contém um ou mais blocos de conteúdo.

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

SDKResultMessage¶

Emitida quando o agente termina um turno. Verifique subtype para sucesso ou erro.

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¶

Repetida quando uma mensagem de usuário é processada.

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

SDKSystemMessage¶

Eventos do sistema, como inicialização de sessão.

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

Blocos de conteúdo¶


Tipo	Campos
`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 }`

Eventos de streaming¶


Tipo	Descrição
`SDKPartialAssistantMessage`	Streaming de texto/raciocínio parcial (requer `includePartialMessages: true`)
`StdErrEvent`	`{ type: "stderr", data: string }`: stderr da CLI
`ParseErrorEvent`	`{ type: "parse_error", raw: string, error: string }`

SDKPartialAssistantMessage é emitido para texto parcial e blocos de raciocínio. Chamadas de ferramentas completas ainda chegam como blocos AssistantMessage, e resultados de ferramentas ainda chegam como blocos UserMessage.

Saída estruturada¶

Force o agente a retornar uma resposta correspondente a um esquema 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
  }
}

Para obter mais informações, consulte Saída estruturada.

Tratamento de erros¶

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

Avisos legais¶

Quando sua configuração do Cortex Code usa um modelo que consta em Model and Service Pass-Through Terms, seu uso desse modelo está sujeito aos respectivos termos nessa página.

A classificação dos dados de entradas e saídas é definido na tabela a seguir.


Classificação de dados de entrada	Classificação de dados de saída	Designação
Usage Data	Dados de cliente	Recursos de AI incluídos [1]

Para obter informações adicionais, consulte AI e ML Snowflake.