SDK Agent Cortex Code¶

Conditions préalables¶

1. Installer Cortex Code CLI¶

Installez la CLI.

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

2. Installer le SDK¶

Installez le SDK depuis npm ou PyPI :

npm install cortex-code-agent-sdk

pip install cortex-code-agent-sdk

3. Configurer la connexion Snowflake.¶

Le SDK s’authentifie via les paramètres de connexion de la CLI Snowflake. Ajoutez une connexion à ~/.snowflake/connections.toml ou utilisez une configuration existante dans ~/.snowflake/config.toml (voir Configuration des connexions) :

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

Le SDK utilise la connexion par défaut de la CLI, sauf si vous en spécifiez une explicitement via l’option connection.

Si la CLI Cortex Code n’est pas sur votre PATH, pointez le SDK vers celle-ci en définissant CORTEX_CODE_CLI_PATH=/path/to/cortex ou en transmettant cliPath (TypeScript) ou cli_path (Python) dans les options SDK.

4. Exécuter votre premier agent¶

L’exemple suivant crée un agent qui explore votre projet et résume ce qu’il fait :

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

Pour un tutoriel plus complet, voir Démarrage rapide.

Outils intégrés¶

Votre agent peut lire des fichiers, exécuter des commandes, exécuter SQL et recherchent des bases de code sans configuration supplémentaire. Les outils disponibles peuvent varier selon l’environnement et les capacités d’exécution :

Sessions à plusieurs tours¶

Vous pouvez maintenir le contexte sur plusieurs échanges. L’agent conserve les connaissances relatives aux fichiers lus, aux analyses effectuées et à l’historique des conversations :

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

Vous pouvez également poursuivre une session précédente ou la dupliquer dans une nouvelle :

// 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")

Serveurs MCP¶

Vous pouvez vous connecter à des systèmes externes via le protocole MCP (Model Context Protocol) :

from cortex_code_agent_sdk import CortexCodeAgentOptions

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

Hooks¶

Vous pouvez exécuter du code personnalisé à des moments clés du cycle de vie de l’agent. Les événements de hook disponibles incluent PreToolUse, PostToolUse, Stop, UserPromptSubmit et plus. Les hooks sont pris en charge dans les SDKs Python et TypeScript. Voir la:doc:Référence du SDK Python </user-guide/cortex-code-agent-sdk/python-reference> ou la référence du SDK TypeScript pour plus de détails.

Sortie structurée¶

Vous pouvez forcer l’agent à renvoyer une réponse correspondant à un schéma JSON :

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

Pour plus d’informations, voir Sortie structurée.

Contrôle des versions¶

Vous pouvez contrôler le comportement de l’agent via les options de session :

Inférence interrégionale¶

La disponibilité des modèles varie selon la région. Un administrateur de compte peut activer l’inférence interrégionale pour accéder à des modèles non disponibles localement :

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';

Pour plus d’informations, voir Inférence interrégionale.