Referenz: Cortex Code-Agent-SDK – TypeScript

Unter diesem Thema finden Sie die vollständige API-Referenz für das Cortex Code Agent-SDK für TypeScript, einschließlich aller Funktionen, Typen und Schnittstellen.

Installation

npm install cortex-code-agent-sdk

Erfordert Node.js 18 oder höher. Das Paket ist ausschließlich für ESM. Das SDK erwartet, dass die Cortex Code-CLI separat installiert wird. Wenn es nicht auf Ihrem PATH liegt, legen Sie CORTEX_CODE_CLI_PATH=/path/to/cortex fest oder übergeben Sie cliPath in den Sitzungsoptionen.

Funktionen

Abfrage()

Die Primärfunktion für die Interaktion mit Cortex Code. Erstellt einen asynchronen Generator, der Nachrichten bei Eintreffen streamt.

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

Parameter

Parameter

Typ

Beschreibung

prompt

string | AsyncIterable<SDKUserMessage>

Eine einzelne Benutzer-Eingabeaufforderung oder ein asynchrones iterierendes Objekt von SDK-Benutzernachrichten für Streaming-Eingaben.

options

CortexCodeSessionOptions | undefined

Optionales Konfigurationsobjekt (siehe Optionen)

Rückgabewerte

Ein Query-Objekt, das AsyncGenerator<CortexCodeEvent> mit zusätzlichen Kontrollmethoden erweitert.

Beispiel

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

Erstellt eine dauerhafte Sitzung für Konversationen mit mehreren Runden.

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

Beispiel

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

Abfrageobjekt

Rückgabewert von query(). Erweitert AsyncGenerator<CortexCodeEvent>.

Methode

Beschreibung

interrupt(): Promise<void>

Senden von SIGINT für den zugrunde liegenden Prozess

setPermissionMode(mode: PermissionMode): Promise<void>

Ändern des Berechtigungsmodus für spätere Ausführung in der aktiven Abfrage

setModel(model: string): Promise<void>

Ändern des Modells für nachfolgende Runden

initializationResult(): Promise<QueryInitializationResult>

Rückgabe von Initialisierungs-Handshake-Metadaten der CLI

supportedCommands(): Promise<SlashCommand[]>

Rückgabe von Slash-Command-Metadaten aus der Initialisierungsantwort, wenn von der CLI angekündigt.

supportedModels(): Promise<ModelInfo[]>

Rückgabe von Modellmetadaten aus der Initialisierungsantwort, wenn dies von der CLI angekündigt wird

supportedAgents(): Promise<AgentInfo[]>

Rückgabe von benutzerdefinierten Agenten-Metadaten aus der Initialisierungsantwort, wenn dies von der CLI angekündigt wird

accountInfo(): Promise<AccountInfo>

Rückgabe von Kontometadaten aus der Initialisierungsantwort, wenn dies von der CLI angekündigt wird

streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>

Streamen von zusätzlichen SDK-Benutzernachrichten in die aktive Abfrage

stopTask(taskId: string): Promise<void>

Abbrechen einer laufenden Hintergrundaufgabe durch ID

close(): void

Schließen der Sitzung und Beenden des Prozesses

CortexCodeSession-Schnittstelle

Rückgabewert von createCortexCodeSession(). Unterstützt Multi-Turn-Konversationen und implementiert``AsyncDisposable`` zur Verwendung mit await using (Node.js 24+).

Eigenschaft/Methode

Beschreibung

pid: number | undefined

PID des zugrunde liegendenCLI-Prozesses

send(message: string | SDKUserMessage): Promise<void>

Senden von Klartext- oder einer strukturierten SDK-Benutzermeldung

stream(): AsyncGenerator<CortexCodeEvent>

Streamen von Ereignissen vom Agenten

initializationResult(): Promise<QueryInitializationResult>

Rückgabe von Initialisierungs-Handshake-Metadaten der CLI

interrupt(): Promise<void>

Senden von Unterbrechungssignal

setPermissionMode(mode: PermissionMode): Promise<void>

Ändern des Berechtigungsmodus für spätere Runden in der Sitzung

setModel(model: string): Promise<void>

Ändern des Modells mitten in der Sitzung

stopTask(taskId: string): Promise<void>

Abbrechen einer laufenden Hintergrundaufgabe durch ID

close(): Promise<void>

Beenden der Sitzung und Abbrechen des Prozesses

[Symbol.asyncDispose](): Promise<void>

Ruft close() auf. Aktiviert await using session = ...-Syntax.

Optionen

Konfiguration, die an query() oder createCortexCodeSession() übergeben wird.

Option

Typ

Standard

Beschreibung

cwd

string

Aktuelles Arbeitsverzeichnis des Prozesses

Arbeitsverzeichnis für die Sitzung. Wenn weggelassen, erbt dieSDK das aktuelle Arbeitsverzeichnis des Prozesses.

model

string

CLI-Standard

Zu verwendendes Modell. Verwenden Sie "auto" für die automatische Auswahl oder einen bestimmten Bezeichner wie "claude-sonnet-4-6". Siehe Unterstützte Modelle.

connection

string

CLI-Standard

Snowflake-Verbindungsname von Snowflake CLI-Verbindungseinstellungen, normalerweise ~/.snowflake/connections.toml; wird mit ~/.snowflake/config.toml auch für bestehende Setups unterstützt. Beim Weglassen verwendet die CLI den default_connection_name aus der TOML-Datei. Siehe Konfigurieren von Verbindungen.

profile

string

undefined

Profilname (wird aus ~/.snowflake/cortex/profiles/ geladen)

resume

string

undefined

Sitzungs-ID, um eine frühere Konversation fortzusetzen

continue

boolean

false

Fortsetzen der letzten Konversation Setzt die letzte Sitzung fort, ohne dass eine Sitzungs-ID erforderlich ist.

forkSession

boolean

false

Integrieren Sie eine fortgesetzte Sitzung in eine neue Sitzungs-ID, anstatt sie an Ort und Stelle fortzuführen. Mi t``resume`` verwenden.

sessionId

string

undefined

Explizite Sitzungs-ID für die Konversation. Wenn weggelassen, generiert die CLI automatisch eine.

permissionMode

string

"default"

"default" | "autoAcceptPlans" | "plan" | "bypassPermissions". Hinweis:"bypassPermissions" erfordert``allowDangerouslySkipPermissions: true``. Im "plan"-Modus können AskUserQuestion und ExitPlanMode über canUseTool geroutet werden. Ablehnen von ExitPlanMode hält die Planung aktiv, und die Genehmigung beendet den Planmodus, sodass spätere Turns die normalen Berechtigungen wieder aufnehmen.

allowDangerouslySkipPermissions

boolean

false

Sicherheitsflag, erforderlich bei Verwendung von permissionMode: "bypassPermissions". Dieses Flag allein umgeht die Berechtigungen nicht. Es erlaubt die Umgehung nur, wenn dies explizit über permission_mode angefordert wird.

allowedTools

string[]

undefined

Tools zur automatischen Genehmigung ohne Eingabeaufforderung

disallowedTools

string[]

undefined

Tools, um immer abzulehnen

canUseTool

CanUseTool

undefined

Kundenspezifischer Berechtigungs-Handler, der vor jeder Ausführung des Tools aufgerufen wird. Siehe canUseTool-Callback.

permissionPromptToolName

string

undefined

MCP-Name des Tools, der für Berechtigungsaufforderungen verwendet wird. Wenn canUseTool bereitgestellt wird, verwendet das SDK automatisch``“stdio“``.

maxTurns

number

undefined

Maximale Anzahl von Agent-Runden, bevor der Agent angehalten wird. Wenn erreicht ist, gibt die Sitzung ein error_max_turns-Ergebnis aus.

effort

string

undefined

Denkaufwand-Ebene für das Modell. Eine der folgenden: "minimal", "low", "medium", "high" oder "max".

additionalDirectories

string[]

undefined

Zusätzliche Arbeitsverzeichnisse, die der Sitzung zur Verfügung gestellt werden sollen

plugins

Array<string | { type: "local"; path: string }>

undefined

Zu ladende Plugin-Verzeichnisse. Akzeptiert Pfade als Zeichenfolgen oder { type: "local", path: "..." }-Objekte.

env

Record<string, string | undefined>

undefined

Umgebungsvariablen wurden in die erzeugte Prozessumgebung zusammengeführt. Setzen Sie einen Schlüssel auf``undefined``, um eine vererbte Variable zu entfernen.

abortController

AbortController

undefined

Senden Sie ein Unterbrechungssignal, indem Sie abort() auf dem Controller aufrufen. Die Sitzung bleibt für weitere Eingabeaufforderungen bestehen. Entspricht dem Drücken vonESC in der CLI.

systemPrompt

string | SystemPromptPreset

undefined

Kundenspezifische System-Eingabeaufforderung. Übergeben Sie eine Zeichenfolge, um den Standard vollständig zu ersetzen, oder ein SystemPromptPreset, um ihn zu erweitern.

appendSystemPrompt

string

undefined

Text, der an die Standard-Systemeingabeaufforderung angehängt wurde. Verwenden Sie dies, um Anweisungen hinzuzufügen, ohne die integrierte Eingabeaufforderung zu ersetzen.

hooks

Partial<Record<HookEvent, HookMatcher[]>>

undefined

Hook-Callbacks zum Abfangen der Ausführung von Tools und anderer Agentenereignisse. Siehe Hooks.

settingSources

SettingSource[]

undefined

Einstellen der zu ladenden Quellen Array von "user" ,``“project“`` und/oder "local".

includePartialMessages

boolean

false

Schließt Streaming-Ereignisse auf Token-Ebene ein

mcpServers

Record<string, Record<string, unknown>>

undefined

Externe MCP-Serverkonfigurationen. Schlüssel sind Servernamen, Werte sind Serverkonfigurationen (z. B. { command: "node", args: ["server.js"] }). Siehe MCP-Server.

noMcp

boolean

false

Deaktiviert MCP-Server

outputFormat

{ type: "json_schema"; schema: object }

undefined

Strukturierte Ausgabe – validiert die endgültige Antwort gegen ein JSON-Schema

cliPath

string

process.env.CORTEX_CODE_CLI_PATH ?? "cortex"

Pfad zum kundenspezifischenCLI-Binärwert Beim Weglassen überprüft das SDK zuerst CORTEX_CODE_CLI_PATH und greift ansonsten auf cortex im PATH zurück.

extraArgs

Record<string, string | null>

undefined

Zusätzliche CLI-Argumente als Schlüssel-Wert-Paare

canUseTool-Callback

Kundenspezifischer Berechtigungs-Handler, der vor jeder Ausführung des Tools aufgerufen wird. Zurückgeben eines Zulassungs- oder Ablehnungsergebnisses, um zu steuern, ob der Tool-Aufruf fortgesetzt wird.

Bei vielen normalen Tool-Berechtigungsprüfungen enthält die Callback-Eingabe Felder wie { action, resource }. Für diese Prüfungen werden das Zulassen/Ablehnen-Ergebnis und die optionale Ablehnungsmeldung verwendet. updatedInput wird für SDK-Routing-Pseudo-Tools wie AskUserQuestion und``ExitPlanMode`` verwendet, die Tool-spezifische Felder enthalten.

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

Beispiel

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

Anstatt die Systemeingabeaufforderung vollständig zu ersetzen, verwenden Sie ein voreingestelltes Objekt, um die integrierte Eingabeaufforderung zu erweitern.

type SystemPrompt = string | SystemPromptPreset;

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

Beispiel

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

Hooks

Mit Hooks können Sie Agentenereignisse wie die Ausführung von Tools abfangen. Jedes Hook-Ereignis wird einem Array von Matching-Ereignissen zugeordnet, und jedes Matching-Ereignis enthält ein optionales Muster und einen oder mehrere Callbacks.

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

Beispiel

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

Nachrichtentyp

Ereignisse, die von query() und session.stream() zurückgegeben werden:

SDKAssistantMessage

Wird ausgegeben, wenn der Agent eine Antwort erzeugt. Enthält einen oder mehrere Inhaltsblöcke.

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

SDKResultMessage

Wird ausgegeben, wenn der Agent einen Turn beendet hat. Überprüfen Sie subtype auf Erfolg oder Fehler.

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

Wird als Echo zurückgegeben, wenn eine Benutzermeldung verarbeitet wird.

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

SDKSystemMessage

Systemereignisse, wie z. B. die Initialisierung der Sitzung.

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

Inhaltsblöcke

Typ

Felder

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 }

Streaming-Ereignisse

Typ

Beschreibung

SDKPartialAssistantMessage

Partielles Text-/Denkstreaming (erfordert includePartialMessages: true)

StdErrEvent

{ type: "stderr", data: string } – Stderr der CLI

ParseErrorEvent

{ type: "parse_error", raw: string, error: string }

SDKPartialAssistantMessage wird für Teiltext- und Denkblöcke ausgegeben. Vollständige Tool-Aufrufe kommen weiterhin als AssistantMessage-Blöcke an, und Tool-Ergebnisse kommen weiterhin als UserMessage-Blöcke an.

Strukturierte Ausgabe

Zwingt den Agenten, eine Antwort zurückzugeben, die mit einem JSON-Schema übereinstimmt:

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

Weitere Informationen dazu finden Sie unter Strukturierte Ausgabe.

Fehlerbehandlung

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