Cortex Agent SDK¶

The Cortex Agent SDK helps you build applications that reason over your governed Snowflake data and take action with tools. Use it from Python or TypeScript to stream responses, preserve multi-turn conversations, run long tasks in the background, and manage reusable agent objects.

You can also embed Cortex Code when your application needs an agentic coding loop that can inspect files, run commands, use tools, and make changes in a workspace.

What you can build¶

Get started¶

You need a Snowflake account with Cortex Agents available and a supported credential. The SDK derives the API URL from the account value and uses Snowflake’s canonical hyphenated host form when the account identifier contains an underscore (_). Pass a full base URL only when you need a regional, PrivateLink, pre-production, or proxy endpoint. The Python SDK requires Python 3.10 or later. The TypeScript SDK requires Node.js 22.22 or later.

Choose your language to install the SDK and send an agent turn.

npm install "@snowflake/cortex-agent-sdk@>=0.0.2"

import {
  CortexAgentClient,
  type AgentResponse,
  type Conversation,
  type Turn,
} from "@snowflake/cortex-agent-sdk";

const client: CortexAgentClient = new CortexAgentClient({
  account: process.env.SNOWFLAKE_ACCOUNT!,
  auth: process.env.SNOWFLAKE_PAT!,
});

const conversation: Conversation = await client.conversations.create({
  thread: { origin_application: "my-app" },
  agent: {
    type: "inline",
    spec: { models: { orchestration: "claude-sonnet-4-5" } },
  },
});

const turn: Turn = await conversation.send("Explain Snowflake micro-partitions in three sentences.");
console.log(`Conversation ID: ${conversation.id}`);

const answer: AgentResponse = await turn.result();
console.log(answer.text);

pip install "snowflake-cortex-agent-sdk>=0.0.2"

from cortex_agent_sdk import AgentResponse, Conversation, CortexAgentClient, Turn

client: CortexAgentClient = CortexAgentClient(account="my_account", auth="<token>")
conversation: Conversation = client.conversations.create(
    origin_application="cortex_agent_sdk",
    agent={"type": "inline", "spec": {}},
)
turn: Turn = conversation.send("What can Cortex Agent do?")
answer: AgentResponse = turn.result()
print(answer.text)

For a complete setup and multi-turn example, see the quickstart.

Authenticate¶

The SDK supports programmatic access tokens, OAuth access tokens, key pair JSON Web Tokens (JWTs), Snowflake session tokens, and custom authenticators. Keep credentials outside your source code. The SDK asks the authenticator for headers before every request attempt, and can run a refresh callback once by default when Snowflake returns a recognized expired-token or expired-session response.

For authentication examples, header formats, session-token guidance, and refresh behavior, see Authenticate Cortex Agent SDK requests.

Choose a coding interface¶

Choose the interface based on where you want the agent loop and tools to run.

For examples and supported options, see Cortex Code and Conversations.

Next steps¶

• Quickstart: Build a durable, multi-turn agent application.
• Authenticate Cortex Agent SDK requests: Configure PAT, OAuth, key-pair JWT, Snowflake session token, and custom authentication.
• Conversations: Maintain conversation state across turns.
• Direct Agent API: Use low-level run, thread, and agent-object resources.
• Use the asynchronous Python client: Run concurrent agent operations from Python.
• SDK reference: Configure responses, errors, retries, and request options.