Cortex Code Agent SDK¶

The Cortex Code Agent SDK lets you build agentic AI applications using Python and TypeScript. Your agents can read files, run commands, search codebases, execute SQL, and edit code, using the same tools and agent loop that power Cortex Code.

The SDK includes built-in tools for file operations, shell commands, and code editing, so your agent can start working immediately without you implementing tool execution.

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

for await (const message of query({
  prompt: "Explore the SALES.PUBLIC schema and give me a one-paragraph summary of the tables it contains.",
  options: { cwd: process.cwd() },
})) {
  if (message.type === "assistant") {
    for (const block of message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
}

import asyncio
from cortex_code_agent_sdk import query, AssistantMessage, CortexCodeAgentOptions

async def main():
    async for message in query(
        prompt="Explore the SALES.PUBLIC schema and give me a one-paragraph summary of the tables it contains.",
        options=CortexCodeAgentOptions(cwd="."),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text, end="")

asyncio.run(main())

Get started¶

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 connects to Snowflake, explores a schema, and profiles a table using the built-in SQL tool and your default connection:

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

for await (const message of query({
  prompt:
    "Explore the SALES.PUBLIC schema and summarize its tables, then profile the ORDERS table: " +
    "report its row count, its columns and types, and the NULL rate of each column.",
  options: {
    cwd: process.cwd(),
    allowedTools: ["SQL"], // auto-approve the SQL tool so the agent can query without prompting
  },
})) {
  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=(
            "Explore the SALES.PUBLIC schema and summarize its tables, then profile the ORDERS table: "
            "report its row count, its columns and types, and the NULL rate of each column."
        ),
        options=CortexCodeAgentOptions(
            cwd=".",
            allowed_tools=["SQL"],  # auto-approve the SQL tool so the agent can query without prompting
        ),
    ):
        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.

Capabilities¶

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 the tables it queried, analysis performed, and conversation history:

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

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  allowedTools: ["SQL"],
});

await session.send("List the tables in the SALES.PUBLIC schema with their row counts.");
for await (const event of session.stream()) {
  if (event.type === "result") break;
}

// Second turn - the agent still has the table list and row counts from context
await session.send("Now write a query that joins the two largest tables.");
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(allowed_tools=["SQL"])) as client:
    await client.query("List the tables in the SALES.PUBLIC schema with their row counts.")
    async for msg in client.receive_response():
        pass  # process messages

    # Second turn - the agent still has the table list and row counts from context
    await client.query("Now write a query that joins the two largest tables.")
    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: "Profile the ORDERS table in the SALES.PUBLIC schema",
  options: {
    cwd: ".",
    allowedTools: ["SQL"],
    outputFormat: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          table: { type: "string" },
          row_count: { type: "number" },
          columns: {
            type: "array",
            items: {
              type: "object",
              properties: {
                name: { type: "string" },
                type: { type: "string" },
                null_rate: { type: "number" },
              },
              required: ["name", "type", "null_rate"],
            },
          },
        },
        required: ["table", "row_count", "columns"],
      },
    },
  },
});

For more information, see Structured output.

Session control¶

You can control agent behavior through session options:

Supported models¶

Set the model using the model option. Snowflake recommends "auto" for automatic selection of the highest quality available model.

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.

Next steps¶

• Quickstart: Build an agent that finds and fixes bugs
• Build a data copilot: Build a data engineering copilot app that uses the SDK’s SQL tool against Snowflake
• TypeScript SDK reference: Full TypeScript API reference and examples
• Python SDK reference: Full Python API reference and examples
• Multi-turn sessions and streaming input: Maintain context across multiple exchanges
• MCP servers: Connect external MCP servers
• System prompts: Customize agent behavior with system prompts
• Handle approvals and user input: Control which tools the agent can use
• Structured output: Return validated JSON from agent workflows
• Streaming output: Stream responses in real-time
• Hooks: Run custom code at key points in the agent lifecycle