CortexAgentApi

relationalai.agent.cortex

CortexAgentApi(client: httpx.Client)

Client for interacting with the Snowflake Cortex Agents REST API.

Provides methods for creating, updating, describing, listing, deleting, and running Cortex agents. Requires both the USE AI FUNCTIONS account privilege and the snowflake.cortex_user database role. All requests timeout after 15 minutes.

Parameters

• client

  (httpx.Client) - Configured httpx.Client with authentication headers.

Methods

.create()

CortexAgentApi.create(
    database: str, schema: str, request: AgentSpec, create_mode: str = "orReplace"
) -> None

Create an agent.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

• request

  (AgentSpec) - Agent specification.

• create_mode

  (str, default: “orReplace”) - One of "orReplace", "errorIfExists", or "ifNotExists". Default: "orReplace".

Returns:

• None

.update()

CortexAgentApi.update(database: str, schema: str, name: str, request: AgentSpec) -> None

Update an existing agent’s configuration.

Modifies the properties of an existing agent. Fields not included in the request are left unchanged.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

• name

  (str) - Agent name to update.

• request

  (AgentSpec) - Updated agent specification.

Returns:

• None

Raises:

• httpx.HTTPStatusError - If the request fails.

.describe()

CortexAgentApi.describe(database: str, schema: str, name: str) -> DescribeAgentResponse

Retrieve comprehensive details about a specific agent.

Returns complete agent metadata including configuration, ownership, and creation information.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

• name

  (str) - Agent name.

Returns:

• DescribeAgentResponse - Full agent details.

Raises:

• httpx.HTTPStatusError - If the request fails or agent doesn’t exist.

.list()

CortexAgentApi.list(database: str, schema: str) -> ListAgentsResponse

List all agents in a schema.

Returns summary information for all agents in the specified database and schema.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

Returns:

• ListAgentsResponse - Agent summaries.

Raises:

• httpx.HTTPStatusError - If the request fails.

.delete()

CortexAgentApi.delete(database: str, schema: str, name: str, silent=True)

Delete an agent.

Permanently removes an agent from the database. The behavior when the agent doesn’t exist depends on the silent parameter.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

• name

  (str) - Agent name to delete.

• silent

  (bool, default: True) - If True, suppress errors when agent doesn’t exist. Default: True.

Returns:

• httpx.Response - The HTTP response object.

Raises:

• httpx.HTTPStatusError - If silent=False and the request fails.

.run()

CortexAgentApi.run(
    database: str,
    schema: str,
    name: str,
    thread_id: int,
    parent_message_id: int,
    prompt: str,
) -> Tuple[dict, int]

Execute an agent with a user prompt in a conversation thread.

Sends a message to the agent and streams back the response. Processes server-sent events to extract the agent’s response and updated message ID.

Parameters:

• database

  (str) - Database name.

• schema

  (str) - Schema name.

• name

  (str) - Agent name to run.

• thread_id

  (int) - Conversation thread identifier.

• parent_message_id

  (int) - ID of the previous message in the thread.

• prompt

  (str) - User’s message/prompt for the agent.

Returns:

• tuple of (dict, int) - (response_dict, new_parent_message_id) where response_dict contains the agent’s response with "content" and "role" fields, and new_parent_message_id is the message ID for the next interaction.

Raises:

• APIResponseError - If the agent returns an error.
• httpx.HTTPStatusError - If the HTTP request fails.
• AssertionError - If the response doesn’t contain expected content.