Skip to content

CortexAgentManager

relationalai.agent.cortex.cortex_agent_manager
CortexAgentManager(
session: snowpark.Session, config: AgentConfig, host: Optional[str] = None
)

Deploy and manage Cortex AI agents powered by RAI semantic models.

Handles the full lifecycle of a Snowflake Cortex agent that powers a Snowflake Intelligence (SI) experience. Non-technical SI users interact with the agent through the SI UI; this class is for the deployer/admin who creates and maintains the agent behind it.

Parameters

  • session

    (snowflake.snowpark.Session) - Authenticated snowpark.Session with access to tools_schema.
  • config

    (AgentConfig) - Configuration specifying where and how to deploy the agent.
  • host

    (str, default: None) - Override for the Cortex REST API base URL. Accepts a bare hostname (e.g. amd01.east-us-2.azure.snowflakecomputing.com) or a full URL with scheme. When omitted, the host is derived from the Snowflake connection. Use this when the auto-detected host isn’t reachable (e.g. unusual regional/PrivateLink setups).

Examples

session = create_config().get_session(SnowflakeConnection)
manager = CortexAgentManager(
session=session,
config=AgentConfig(
agent_name="EXAMPLE_CORTEX",
tools_schema="EXAMPLE.CORTEX",
warehouse="DEMOWAREHOUSE",
model_deployment=ModelDeployment(schema="EXAMPLE.CUSTOMERS"),
),
)
def init_tools():
from myproject.model import core
return DefaultTool(model=core.model, description="Customers and orders")
manager.deploy(init_tools=init_tools, imports=discover_imports())

Methods

.preflight()

CortexAgentManager.preflight(init_tools: Optional[Callable] = None) -> PreflightReport

Probe Snowflake for required objects and grants without deploying.

Runs the same set of read-only checks that deploy() runs before attempting to create resources. Use this to surface every missing grant up front and hand a single fix-list to a Snowflake admin, instead of round-tripping one error at a time.

Parameters:

  • init_tools

    (Callable, default: None) - When provided, the preflight additionally builds the agent’s Tool via init_tools, warns when its model differs from the deployed model, and probes the per-call DISCOVER / VERBALIZE / EXPLAIN sizes against the envelope budget. Truncated sprocs surface as warnings.

Returns:

  • PreflightReport - A report whose errors list collects blocking issues and whose format(config=manager.config) renders a paste-ready diagnostic with a SQL fix block.
CortexAgentManager.print_setup_sql(
deployer_role: str = "<your_role>",
si_role: Optional[str] = None,
create_role: bool = False,
) -> str

Return a copy-pasteable SQL block granting the required privileges.

The block is parameterized with this manager’s tools_schema, agent_schema, warehouse and model deployment. Run the SI-user block after deploy(): it grants on the agent and on the procedures that exist then.

Parameters:

  • deployer_role

    (str, default: “<your_role>”) - Name of the deployer role. Defaults to a placeholder so callers can render a template.
  • si_role

    (str, default: None) - If given, also emit the SI-user GRANT block. Default: just the deployer block.
  • create_role

    (bool, default: False) - Prepend CREATE ROLE IF NOT EXISTS for each role.

Returns:

  • str - A SQL block ready to paste into a Snowflake worksheet.

.deploy()

CortexAgentManager.deploy(
init_tools: Callable,
imports: List[Tuple[str, str]],
base_agent_spec: Optional[CortexAgentApi.AgentSpec] = None,
extra_packages: Optional[List[str]] = None,
) -> CortexAgentApi.AgentSpec

Deploy the agent and all required Snowflake resources.

Creates a stage (if manage_stage=True), registers RAI tool stored procedures, and deploys the Cortex agent.

init_tools runs once locally to validate the tool. The tool’s model is then pointed at config.model_deployment, so afterwards that in-process model reads the deployment and no longer auto-deploys.

Parameters:

  • init_tools

    (Callable) - Callable taking no parameters and returning the agent’s Tool, usually a DefaultTool over the one model the agent serves. A custom Tool subclass implementing model() works too. Import your model definition code inside the function body, so the Model is created within the sproc’s active Snowpark session:

    def init_tools():
    from myproject.model import core
    return DefaultTool(
    model=core.model, description='...')
  • imports

    (list of tuple of (str, str)) - Project code to upload to Snowflake. Use discover_imports() for automatic recursive discovery. Format: list of (source_path, module_name) tuples.

  • base_agent_spec

    (relationalai.agent.cortex.api.agent.CortexAgentApi.AgentSpec, default: None) - Base agent spec to extend with RAI tools. Default: None (creates a new spec).

  • extra_packages

    (list of str, default: None) - Additional PyPI packages for the sproc environment. relationalai is included automatically.

Returns:

  • relationalai.agent.cortex.api.agent.CortexAgentApi.AgentSpec - The deployed agent specification.

Raises:

  • RAIException - If deployment fails at any stage. PreflightFailed if preflight finds a blocking issue, such as config.model_deployment being unable to serve the agent. With skip_preflight=True, that deployment check still runs before any procedure is registered, and raises its own code: ModelDeploymentNotFound, ModelDeploymentIncomplete, ModelDeploymentFailed or ModelDeploymentHasNoOplog.

.update()

CortexAgentManager.update(
init_tools: Callable,
imports: List[Tuple[str, str]],
extra_packages: Optional[List[str]] = None,
) -> CortexAgentApi.AgentSpec

Update the agent’s tools without recreating the agent.

Recreates stored procedures with updated tool definitions and updates the agent configuration in Cortex. The agent name and identity are preserved; existing SI conversations are unaffected. Like deploy(), it points the tool’s model at config.model_deployment.

Parameters:

  • init_tools

    (Callable) - Updated callable returning the agent’s Tool. Same contract as deploy().
  • imports

    (list of tuple of (str, str)) - Updated project code. Use discover_imports().
  • extra_packages

    (list of str, default: None) - Updated PyPI package list.

Returns:

  • relationalai.agent.cortex.api.agent.CortexAgentApi.AgentSpec - Updated agent specification.

Raises:

  • RAIException - If agent is not deployed (call deploy() first), or if config.model_deployment can’t serve the agent.

.chat()

CortexAgentManager.chat() -> CortexAgentChat

Get a programmatic chat interface for the deployed agent.

Returns a CortexAgentChat that maintains conversation state across multiple send() calls. This is primarily useful for testing and automation — SI users interact through the Snowflake Intelligence UI.

Returns:

  • CortexAgentChat - Chat interface instance.

Raises:

  • RAIException - If agent is not deployed (call deploy() first).

.status()

CortexAgentManager.status() -> DeploymentStatus

Check deployment status of all agent components.

Queries Snowflake and Cortex to verify existence of the agent, stage, and all stored procedures.

Returns:

  • DeploymentStatus - Use fully_deployed(), partially_deployed(), or clean() for quick checks.

.cleanup()

CortexAgentManager.cleanup(silent: bool = True) -> None

Remove all agent resources from Snowflake and Cortex.

Deletes the Cortex agent, all RAI tool stored procedures, and the stage (if manage_stage=True). SI conversation history is permanently lost.

Parameters:

  • silent

    (bool, default: True) - Ignore errors for non-existent resources. Default: True.

Returns:

  • None