Cortex Code-Agent-SDK¶

Voraussetzungen¶

1. Installieren der Cortex Code-CLI¶

Installieren der CLI:

curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh

2. SDK installieren¶

Installieren Sie das SDK von npm oder PyPI:

npm install cortex-code-agent-sdk

pip install cortex-code-agent-sdk

3. Konfigurieren Sie Ihre Snowflake-Verbindung¶

Das SDK authentifiziert sich über Ihre Snowflake-CLI-Verbindungseinstellungen. Fügen Sie eine Verbindung zu ~/.snowflake/connections.toml hinzu oder verwenden Sie ein bestehendes Setup in ~/.snowflake/config.toml (siehe Konfigurieren von Verbindungen):

[my-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "externalbrowser"

Das SDK verwendet die Standardverbindung von CLI, es sei denn, Sie geben eine Verbindung explizit über die connection-Option an.

Wenn das Cortex Code-CLI nicht auf Ihrem PATH ist, verweisen Sie das SDK durch Festlegen von CORTEX_CODE_CLI_PATH=/path/to/cortex darauf, oder indem Sie cliPath (TypeScript) oder cli_path (Python) in den SDK-Optionen übergeben

4. Führen Sie Ihren ersten Agenten aus¶

Im folgenden Beispiel wird ein Agent erstellt, der Ihr Projekt untersucht und zusammenfasst, was es tut:

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

for await (const message of query({
  prompt: "What does this codebase do? Give me a one-paragraph summary.",
  options: { cwd: process.cwd() },
})) {
  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("\nDone:", message.subtype);
  }
}

import asyncio
from cortex_code_agent_sdk import query, AssistantMessage, ResultMessage, CortexCodeAgentOptions

async def main():
    async for message in query(
        prompt="What does this codebase do? Give me a one-paragraph summary.",
        options=CortexCodeAgentOptions(cwd="."),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text, end="")
        elif isinstance(message, ResultMessage):
            print(f"\nDone: {message.subtype}")

asyncio.run(main())

Ein ausführlicheres Tutorial finden Sie unter Schnellstart.

Integrierte -Tools¶

Ihr Agent kann ohne zusätzliche Konfiguration Dateien lesen, Befehle ausführen, SQL ausführen und Codebasen durchsuchen. Die verfügbaren Tools können je nach Umgebung und Laufzeitfunktionen variieren:

Sitzungen mit mehreren Runden¶

Sie können den Kontext über mehrere Datenbörsen hinweg pflegen. Der Agent behält das Wissen über gelesene Dateien, durchgeführte Analysen und den Verlauf der Konversation:

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

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

await session.send("Read the authentication module");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

// Second turn - "it" refers to the auth module from context
await session.send("Now find all places that call it");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

await session.close();

from cortex_code_agent_sdk import CortexCodeSDKClient, CortexCodeAgentOptions

async with CortexCodeSDKClient(CortexCodeAgentOptions()) as client:
    await client.query("Read the authentication module")
    async for msg in client.receive_response():
        pass  # process messages

    # Second turn - "it" refers to the auth module from context
    await client.query("Now find all places that call it")
    async for msg in client.receive_response():
        pass  # process messages

Sie können auch eine bestehende Sitzung fortsetzen oder in eine neue Sitzung aufspalten:

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

// Or fork a resumed session into a new session ID
const forked = await createCortexCodeSession({
  cwd: process.cwd(),
  resume: "previous-session-id",
  forkSession: true,
});

# Continue the most recent conversation
async with CortexCodeSDKClient(
    CortexCodeAgentOptions(continue_conversation=True)
) as client:
    await client.query("What were we working on?")

# Or fork a resumed session into a new session ID
async with CortexCodeSDKClient(
    CortexCodeAgentOptions(resume="previous-session-id", fork_session=True)
) as client:
    await client.query("Let's try a different approach")

MCP-Server¶

Sie können über das Modell-Kontextprotokoll eine Verbindung zu externen Systemen herstellen:

from cortex_code_agent_sdk import CortexCodeAgentOptions

options = CortexCodeAgentOptions(
    mcp_servers={
        "my-tools": {
            "command": "node",
            "args": ["my-mcp-server.js"],
        },
    },
)

Hooks¶

Sie können an Schlüsselpunkten im Lebenszyklus des Agenten benutzerdefinierten Code ausführen. Zu den verfügbaren Hook-Ereignissen gehören: PreToolUse, PostToolUse, Stop, UserPromptSubmit und mehr. Hooks werden sowohl im Python- als auch dem TypeScript-SDKs unterstützt. Siehe Python-SDK-Referenz oder TypeScript-SDK-Referenz für weitere Details.

Strukturierte Ausgabe¶

Sie können den Agenten zwingen, eine Antwort zurückzugeben, die mit einem JSON-Schema übereinstimmt

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

Weitere Informationen dazu finden Sie unter Strukturierte Ausgabe.

Sitzungskontrolle¶

Sie können das Verhalten des Agenten über Sitzungsoptionen steuern:

Regionenübergreifende Inferenz¶

Die Verfügbarkeit der Modelle variiert je nach Region. Ein Kontoadministrator kann die regionsübergreifende Inferenz aktivieren, um auf Modelle zuzugreifen, die lokal nicht verfügbar sind:

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';

Weitere Informationen dazu finden Sie unter Regionenübergreifende Inferenz.