Cortex Code Agent SDK¶

Prerequisites¶

1. Install the Cortex Code CLI¶

Install the CLI:

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

2. Install the SDK¶

Install the SDK from npm or PyPI:

npm install cortex-code-agent-sdk

pip install cortex-code-agent-sdk

3. Configure your Snowflake connection¶

The SDK authenticates through your Snowflake CLI connection settings. Add a connection to ~/.snowflake/connections.toml or use an existing setup in ~/.snowflake/config.toml (see Configuring connections):

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

The SDK uses the CLI’s default connection unless you specify one explicitly through the connection option.

If the Cortex Code CLI is not on your PATH, point the SDK at it by setting CORTEX_CODE_CLI_PATH=/path/to/cortex or by passing cliPath (TypeScript) or cli_path (Python) in the SDK options.

4. Run your first agent¶

The following example creates an agent that explores your project and summarizes what it does:

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

For a more complete tutorial, see Quickstart.

Built-in tools¶

Your agent can read files, run commands, execute SQL, and search codebases without additional configuration. Available tools can vary by environment and runtime capabilities:

Multi-turn sessions¶

You can maintain context across multiple exchanges. The agent retains knowledge of files read, analysis performed, and conversation history:

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

You can also continue a previous session or fork it into a new one:

// 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 servers¶

You can connect to external systems through the Model Context Protocol:

from cortex_code_agent_sdk import CortexCodeAgentOptions

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

Hooks¶

You can run custom code at key points in the agent lifecycle. Available hook events include PreToolUse, PostToolUse, Stop, UserPromptSubmit, and more. Hooks are supported in both the Python and TypeScript SDKs. See the Python SDK reference or the TypeScript SDK reference for details.

Structured output¶

You can force the agent to return a response matching a JSON Schema:

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

For more information, see Structured output.

Session control¶

You can control agent behavior through session options:

Cross-region inference¶

Model availability varies by region. An account administrator can enable cross-region inference to access models not available locally:

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';

For more information, see Cross-region inference.