CortexAgentManager
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
(sessionsnowflake.snowpark.Session) - Authenticatedsnowpark.Sessionwith access totools_schema.
(configAgentConfig) - Configuration specifying where and how to deploy the agent.
(hoststr, 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) -> PreflightReportProbe 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_toolsCallable, default:None) - When provided, the preflight additionally builds the agent’sToolviainit_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 whoseerrorslist collects blocking issues and whoseformat(config=manager.config)renders a paste-ready diagnostic with a SQL fix block.
Referenced By:
.print_setup_sql()
CortexAgentManager.print_setup_sql( deployer_role: str = "<your_role>", si_role: Optional[str] = None, create_role: bool = False,) -> strReturn 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_rolestr, default:“<your_role>”) - Name of the deployer role. Defaults to a placeholder so callers can render a template.
(si_rolestr, default:None) - If given, also emit the SI-user GRANT block. Default: just the deployer block.
(create_rolebool, default:False) - PrependCREATE ROLE IF NOT EXISTSfor each role.
Returns:
str- A SQL block ready to paste into a Snowflake worksheet.
Referenced By:
.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.AgentSpecDeploy 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_toolsCallable) - Callable taking no parameters and returning the agent’sTool, usually aDefaultToolover the one model the agent serves. A customToolsubclass implementingmodel()works too. Import your model definition code inside the function body, so theModelis created within the sproc’s active Snowpark session:def init_tools():from myproject.model import corereturn DefaultTool(model=core.model, description='...') -
(importslist of tuple of (str, str)) - Project code to upload to Snowflake. Usediscover_imports()for automatic recursive discovery. Format: list of(source_path, module_name)tuples. -
(base_agent_specrelationalai.agent.cortex.api.agent.CortexAgentApi.AgentSpec, default:None) - Base agent spec to extend with RAI tools. Default:None(creates a new spec). -
(extra_packageslist of str, default:None) - Additional PyPI packages for the sproc environment.relationalaiis included automatically.
Returns:
relationalai.agent.cortex.api.agent.CortexAgentApi.AgentSpec- The deployed agent specification.
Raises:
RAIException- If deployment fails at any stage.PreflightFailedif preflight finds a blocking issue, such asconfig.model_deploymentbeing unable to serve the agent. Withskip_preflight=True, that deployment check still runs before any procedure is registered, and raises its own code:ModelDeploymentNotFound,ModelDeploymentIncomplete,ModelDeploymentFailedorModelDeploymentHasNoOplog.
.update()
CortexAgentManager.update( init_tools: Callable, imports: List[Tuple[str, str]], extra_packages: Optional[List[str]] = None,) -> CortexAgentApi.AgentSpecUpdate 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_toolsCallable) - Updated callable returning the agent’sTool. Same contract asdeploy().
(importslist of tuple of (str, str)) - Updated project code. Usediscover_imports().
(extra_packageslist 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 (calldeploy()first), or ifconfig.model_deploymentcan’t serve the agent.
.chat()
CortexAgentManager.chat() -> CortexAgentChatGet 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 (calldeploy()first).
.status()
CortexAgentManager.status() -> DeploymentStatusCheck deployment status of all agent components.
Queries Snowflake and Cortex to verify existence of the agent, stage, and all stored procedures.
Returns:
DeploymentStatus- Usefully_deployed(),partially_deployed(), orclean()for quick checks.
.cleanup()
CortexAgentManager.cleanup(silent: bool = True) -> NoneRemove 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:
(silentbool, default:True) - Ignore errors for non-existent resources. Default:True.
Returns:
-
None