Snowflake Cortex Agents Setup - Elementum Documentation

Overview

This guide walks you through the complete process of integrating Snowflake Cortex Agents into your Elementum Apps. By connecting Cortex Agents, you enable AI-powered automation that runs directly on your Snowflake data warehouse, maintaining data security while leveraging advanced AI capabilities. Cortex Agents are configured at the App level through the Intelligence settings, allowing each App to discover and use external agents available through its CloudLink connection. What You’ll Accomplish:

Configure an App’s Intelligence settings to discover Cortex Agents
Connect external Snowflake Cortex Agents to Elementum
Integrate external agents into App automations
Understand the technical architecture and APIs

Time Required: 10-20 minutes, depending on your existing Snowflake configuration

Prerequisites

Before beginning this setup, ensure you have the following in place:

Elementum Requirements

App Access

Access to the App where you want to integrate Cortex Agents

Snowflake AI Provider

A configured Snowflake AI Provider with key-pair authentication CloudLink

Authentication Requirement: Snowflake Cortex Agents require a Snowflake AI Provider configured with key-pair authentication. Password-based CloudLinks cannot access Cortex features.

Snowflake Requirements

Your Snowflake environment must have:

Snowflake Edition: Enterprise or higher
Cortex AI Features: Enabled on your account
Cortex Agents: At least one Cortex Agent configured in your Snowflake account
Permissions: Service account with USAGE privileges on:
- Cortex functions
- Agent resources
- Target database and schema

Verify Your Snowflake AI Provider

Before proceeding, verify you have a Snowflake AI Provider configured:

Navigate to Organization Settings

Go to Organization Settings → Providers

Check Snowflake Provider

Verify a Snowflake provider is configuredEnsure it uses a CloudLink with Key-Pair Authentication

Test Provider

Verify the provider is active and can connect to Snowflake

Need Help with Providers? See the Snowflake Cortex Setup Guide for detailed instructions on configuring Snowflake AI Providers with key-pair authentication.

Step 1: Prepare Snowflake Cortex Agents

Before connecting to Elementum, ensure your Cortex Agents are properly configured in Snowflake.

Verify Cortex Agents in Snowflake

Using Snowflake UI
Using SQL

Log into your Snowflake account
Navigate to AI & ML → Cortex Agents
Verify your agents are listed and active
Note the database and schema where agents are located

-- List available Cortex Agents
SHOW CORTEX AGENTS IN DATABASE your_database;

-- View agent details
DESCRIBE CORTEX AGENT your_database.your_schema.agent_name;

Required Permissions

Ensure your service account has the necessary permissions:

-- Grant usage on database and schema
GRANT USAGE ON DATABASE your_database TO ROLE elementum_role;
GRANT USAGE ON SCHEMA your_database.your_schema TO ROLE elementum_role;

-- Grant usage on Cortex features
GRANT USAGE ON CORTEX TO ROLE elementum_role;

-- Grant execute on specific agents
GRANT USAGE ON CORTEX AGENT your_database.your_schema.agent_name 
  TO ROLE elementum_role;

Principle of Least Privilege: Grant only the minimum permissions necessary for the agents and data your Elementum automations will access.

Step 2: Configure Intelligence in Your App

Now you’re ready to discover and configure Snowflake Cortex Agents through your App’s Intelligence settings.

Access Intelligence Settings

Navigate to Your App

Go to the App where you want to integrate Cortex Agents

Open App Admin

Click on App Admin in the navigation

Select Intelligence

Click on Intelligence in the App Admin menu

Add External Agent

Add Agent

Click the “Add Agent” button at the top of the Intelligence page

Select External

In the agent type selection, choose “External”This indicates you’re connecting to an agent hosted outside Elementum

Select Snowflake AI Provider

Choose your configured Snowflake AI Provider from the dropdownProvider Selection:

Only Snowflake providers with key-pair authentication appear
The provider must have access to Cortex features
Multiple providers can be available if you have different Snowflake environments

Discover Agents

The system uses the selected provider to discover available Cortex AgentsWhat happens:

Elementum connects to Snowflake using the provider’s CloudLink credentials
Queries the Snowflake Cortex REST API for available agents
Lists all agents accessible through the provider’s service account

Select Cortex Agent

From the discovered agents list, select the Cortex Agent you want to useYou’ll see:

Agent name
Agent description
Database and schema location
Available capabilities

Configure Agent Settings

Agent Name: Optionally customize the display name in ElementumDescription: Add notes about how this agent will be used in your AppConfiguration: Review agent input/output schemas

Save Configuration

Click “Save” to connect the external agentThe agent will now appear in your App’s Intelligence configuration

What Happens During Discovery

When you add an external agent, Elementum:

Selects Provider: Uses the selected Snowflake AI Provider’s connection
Authenticates: Authenticates with Snowflake using the provider’s CloudLink credentials
Discovers Agents: Queries the Cortex REST API for available agents
Retrieves Metadata: Gets agent capabilities, schemas, and configuration
Registers Agent: Makes the agent available for use in App automations
Monitors Status: Tracks agent availability through the provider connection

Step 3: Understanding Cortex REST APIs

Elementum leverages three primary Snowflake Cortex APIs for agent integration:

Agent Discovery API

Discovers available agents accessible through your CloudLink. Snowflake Documentation: Cortex Agents REST API What Elementum Retrieves:

Agent names and identifiers
Agent capabilities and descriptions
Input/output schemas
Required permissions
Configuration metadata

Agent Run API

Executes agent tasks and retrieves results. Snowflake Documentation: Cortex Agents Run Used For:

Invoking agents from automations
Passing input parameters
Receiving agent responses
Monitoring execution status
Handling errors and timeouts

Threads API

Manages conversational threads for stateful agent interactions. Snowflake Documentation: Cortex Agents Threads REST API Capabilities:

Create conversation threads
Maintain context across interactions
Retrieve conversation history
Resume interrupted conversations
Manage thread lifecycle

API Authentication: All API calls use the credentials from the selected Snowflake AI Provider’s CloudLink connection, ensuring secure and auditable access to Cortex resources.

Step 4: Integrate Agents into Automations

With your Cortex Agent configured in Intelligence, you can now use it in App automations.

Using External Agents in Automation Actions

Navigate to Automation Configuration

In your App, go to the automation where you want to use the external agent

Add Agent Action

Add a new automation action or edit an existing oneSelect “Agent Action” as the action type

Select Your External Agent

In the agent configuration:Agent: Choose the external Cortex Agent you configured in IntelligenceThe agent will be labeled as “External” or “Managed”

Configure Parameters

Input Mapping: Map automation data to agent input parameters

Use field values from the current record
Reference previous automation action outputs
Include static values or formulas

Output Handling: Configure how to handle agent responses

Map agent outputs to record fields
Store results for later automation actions
Set error handling behavior

Set Execution Options

Timeout: Set maximum execution time (default: 60 seconds)Retry Policy: Configure retry behavior for failuresError Handling: Define what happens if the agent fails

Continue automation with default values
Halt automation and alert user
Escalate to human review

Test Integration

Use the automation test mode to verify agent integrationMonitor execution logs for agent calls and responses

Example: Data Analysis Automation

Scenario: Automatically analyze sales data when a monthly report is requested

Workflow: Monthly Sales Analysis
Trigger: Report requested
Automations:
  1. Gather Data:
     - Collect sales records for the month
     - Aggregate by region and product
  
  2. External Agent - Analysis:
     Type: External Agent (Cortex)
     Agent: Sales Analysis Agent
     Inputs:
       - sales_data: {aggregated_data}
       - analysis_type: "trend_analysis"
       - time_period: "monthly"
     Outputs:
       - trends: record.analysis_results
       - insights: record.key_insights
       - forecast: record.forecast_data
  
  3. Generate Report:
     - Create formatted report with insights
     - Include visualizations from forecast
  
  4. Distribute:
     - Email report to stakeholders
     - Post summary to Teams channel

Using Agents in Multiple Automations

External agents configured in Intelligence can be used across multiple automations within the same App:

Automation Example: Anomaly Detection

Trigger: New transaction record createdConditions: Transaction amount > $10,000Actions:

Call External Agent
- Agent: Fraud Detection Agent (Cortex)
- Input: Transaction details and customer history
- Output: Risk score and explanation
Conditional Logic
- If risk_score > 75: Flag for review and notify security team
- If risk_score 50-75: Request additional verification
- If risk_score < 50: Auto-approve transaction
Log Results
- Record analysis in audit log
- Update transaction status based on outcome

Step 5: Monitor and Maintain

Monitoring Agent Performance

Automation Logs

View agent execution logs in automation historyMonitor:

Invocation frequency
Response times
Success/failure rates
Error messages

Intelligence Dashboard

Track agent usage in Intelligence settingsView:

Active agent connections
Last successful execution
Configuration changes
CloudLink status

Provider Connection Health

Since external agents depend on the Snowflake AI Provider:

Monitor Provider Status: Ensure the provider and its CloudLink remain active
Check Connectivity: Regularly test Snowflake connectivity through the provider
Review Permissions: Verify service account permissions haven’t changed
Update Credentials: Rotate provider CloudLink keys according to your security policy

Snowflake Monitoring: Use Snowflake’s query history and warehouse monitoring to track Cortex Agent compute costs and performance. This complements Elementum’s automation logs.

Maintenance Tasks

Regular Maintenance
Updating Agents
Scaling Considerations

Weekly:

Review automation logs for agent errors
Monitor agent performance metrics
Check for timeout or failure patterns

Monthly:

Review agent usage and optimization opportunities
Audit permissions and access patterns
Test agent functionality after Snowflake updates

Quarterly:

Rotate provider CloudLink credentials
Review and optimize automation integrations
Evaluate new Cortex Agent capabilities

Configuration Best Practices

Security Best Practices

Access Control

Minimal Permissions: Grant only necessary privilegesRole Separation: Use dedicated roles for agent accessAudit Logging: Enable comprehensive audit trailsRegular Reviews: Quarterly access audits

Credential Management

Rotation Schedule: Rotate keys every 90 daysSecure Storage: CloudLink manages credential encryptionNo Sharing: Unique credentials per environmentRevocation Process: Document emergency revocation steps

Performance Optimization

Warehouse Sizing
- Use appropriately sized warehouses for agent complexity
- Consider multi-cluster warehouses for concurrent agent calls
- Enable auto-suspend to minimize costs
Provider Management
- Provider connections are reused across multiple agent invocations
- Monitor provider connection performance metrics
- Configure appropriate timeout values
Timeout Configuration
- Set realistic timeouts based on agent complexity
- Implement progressive timeout strategies
- Consider async patterns for very long-running operations
Caching Strategies
- Cache agent responses for identical inputs
- Implement time-based cache invalidation
- Use Snowflake result caching when appropriate

Error Handling Patterns

Retry Logic

Transient Failures: Implement exponential backoff for temporary issues

Attempt 1: Immediate
Attempt 2: Wait 2 seconds
Attempt 3: Wait 4 seconds
Attempt 4: Wait 8 seconds
Max Attempts: 4

Permanent Failures: Don’t retry for authentication or permission errorsCircuit Breaker: Stop attempting after consecutive failures reach threshold

Fallback Strategies

Default Values: Use sensible defaults when agent unavailableAlternative Agents: Configure backup agents for critical operationsHuman Escalation: Route to human review when automated analysis failsGraceful Degradation: Continue automation with reduced functionality

Troubleshooting

Discovery Issues

No Agents Discovered

Error: “No agents found” when adding external agentPossible Causes:

Snowflake AI Provider not configured or inactive
Provider’s CloudLink has wrong permissions
No Cortex Agents configured in Snowflake
Service account lacks USAGE privileges

Solutions:

Verify Snowflake AI Provider is configured in Organization Settings → Providers
Check that provider uses a CloudLink with key-pair authentication
Run SHOW CORTEX AGENTS in Snowflake to verify agents exist
Verify service account has USAGE privileges on Cortex
Check database and schema permissions
Test provider connection in Provider settings

Provider Authentication Failed

Error: “Unable to authenticate with Snowflake”Possible Causes:

Provider CloudLink not configured with key-pair authentication
Expired or invalid credentials
Network connectivity issues
Snowflake account unavailable

Solutions:

Verify provider uses CloudLink with key-pair authentication (not password)
Test provider connection in Organization Settings → Providers
Check for expired credentials and refresh provider if needed
Verify network connectivity to Snowflake
Confirm Snowflake account is active and accessible
Review provider configuration and CloudLink settings

Permission Denied Errors

Error: “Access denied to Cortex resources”Possible Causes:

Missing USAGE grant on Cortex
Insufficient privileges on agent
Role not properly assigned
Database or schema access missing

Solutions:

-- Verify current role and grants
SHOW GRANTS TO ROLE elementum_role;

-- Grant necessary permissions
GRANT USAGE ON DATABASE your_database TO ROLE elementum_role;
GRANT USAGE ON SCHEMA your_database.your_schema TO ROLE elementum_role;
GRANT USAGE ON CORTEX TO ROLE elementum_role;
GRANT USAGE ON CORTEX AGENT your_database.your_schema.agent_name 
  TO ROLE elementum_role;

Runtime Issues

Agent Timeout

Error: “Agent execution exceeded timeout”Possible Causes:

Agent task too complex for timeout setting
Insufficient Snowflake warehouse resources
Network latency issues
Agent accessing large datasets

Solutions:

Increase timeout value in automation configuration
Scale up Snowflake warehouse for agent workload
Optimize agent queries and data access
Consider splitting complex tasks into multiple automation actions
Use async invocation for long-running operations

Agent Returns Unexpected Results

Error: Agent output doesn’t match expected formatPossible Causes:

Input parameters incorrect or malformed
Agent configuration changed in Snowflake
Schema version mismatch
Data quality issues in source data

Solutions:

Validate input parameters match agent expectations
Test agent directly in Snowflake with same inputs
Check for recent agent updates or schema changes
Review agent logs in Snowflake for execution details
Verify data quality and completeness

High Latency

Error: Agent responses taking too longPossible Causes:

Undersized Snowflake warehouse
Network latency between Elementum and Snowflake
Agent querying large datasets inefficiently
Cold warehouse startup time

Solutions:

Use larger warehouse for agent operations
Keep warehouse running during peak usage (disable auto-suspend temporarily)
Optimize agent queries and data access patterns
Consider warehouse dedicated to agent workloads
Implement result caching for repeated queries

Multi-App Configurations

Using Agents Across Multiple Apps

Each App configures its own external agents through Intelligence:

Configure Per App

Each App that needs Cortex Agents must configure them individuallyEven if multiple Apps connect to the same Snowflake agents

Provider Selection

Apps can use:

The same Snowflake AI Provider (shared access)
Different providers (isolated access or different Snowflake environments)

Independent Configuration

Each App can:

Select different providers pointing to different Snowflake accounts
Use different agents from the same provider
Configure the same agent differently
Have unique timeout and error handling settings

Monitor Separately

Track agent usage and performance per App in each App’s Intelligence dashboard

Multi-Environment Setup

For organizations with multiple environments (dev, staging, production):

Environment-Specific Providers

Configure separate Snowflake AI Providers for each environmentEach provider uses a CloudLink with environment-specific service accounts

Configure Agents Per Environment

In each environment’s App, configure external agents through IntelligenceSelect the appropriate provider (dev/staging/prod) to discover agents

Test Thoroughly

Test in dev environment before promoting to productionValidate in staging with production-like data

Promotion Process

When promoting configurations:

Test agent connectivity in target environment
Verify provider configuration is correct for the environment
Validate automation configurations
Monitor closely after deployment

Example Use Cases

Use Case 1: Automated Data Quality Checks

Scenario: Automatically validate data quality when new datasets are loaded Implementation:

Create Cortex Agent in Snowflake for data profiling and quality analysis
In your Data Management App, configure the agent through Intelligence
Set up automation trigger on data load completion
Agent analyzes dataset and returns quality metrics
Automation creates alerts or blocks further processing based on results

Benefits:

Immediate data quality feedback
Prevents downstream issues from bad data
Reduces manual validation effort
Maintains audit trail of quality checks

Use Case 2: Intelligent Customer Support

Scenario: L1 support agent with direct access to customer data warehouse Implementation:

Create Cortex Agent trained on support knowledge base and customer data
Configure agent in Support App through Intelligence
Integrate agent into support automation
Customer inquiry triggers agent to analyze history and suggest resolution
Agent creates ticket with context and recommended actions

Benefits:

Faster response times for customers
Consistent support quality
Reduces escalations to L2 support
Data stays secure in Snowflake environment

Use Case 3: Financial Reporting Automation

Scenario: Generate executive reports with natural language insights Implementation:

Create Cortex Agent for financial analysis and narrative generation
Configure agent in Finance App through Intelligence
Schedule monthly report generation automation
Agent analyzes trends, generates insights, and creates narrative
Report distributed automatically with executive summary

Benefits:

Consistent reporting schedule
Natural language insights for non-technical stakeholders
Reduces analyst workload
Real-time access to latest data

Next Steps

Agent Orchestration Center

View and manage all agents across your organization

Agent Architecture

Understand the technical architecture and A2A protocol

Automation System

Learn how to build sophisticated automations with agents

Snowflake Cortex Docs

Reference Snowflake’s official Cortex Agents documentation

By integrating Snowflake Cortex Agents through your App’s Intelligence configuration, you create a powerful automation ecosystem that combines the flexibility of AI with the security of keeping your data in your own warehouse. This architecture ensures compliance, performance, and scalability for enterprise deployments.

Overview

Capabilities

Agent Management

Agent Integrations

​Overview

​Prerequisites

​Elementum Requirements

App Access

Snowflake AI Provider

​Snowflake Requirements

​Verify Your Snowflake AI Provider

​Step 1: Prepare Snowflake Cortex Agents

​Verify Cortex Agents in Snowflake

​Required Permissions

​Step 2: Configure Intelligence in Your App

​Access Intelligence Settings

​Add External Agent

​What Happens During Discovery

​Step 3: Understanding Cortex REST APIs

​Agent Discovery API

​Agent Run API

​Threads API

​Step 4: Integrate Agents into Automations

​Using External Agents in Automation Actions

​Example: Data Analysis Automation

​Using Agents in Multiple Automations

​Step 5: Monitor and Maintain

​Monitoring Agent Performance

Automation Logs

Intelligence Dashboard

​Provider Connection Health

​Maintenance Tasks

​Configuration Best Practices

​Security Best Practices

Access Control

Credential Management

​Performance Optimization

​Error Handling Patterns

​Troubleshooting

​Discovery Issues

​Runtime Issues

​Multi-App Configurations

​Using Agents Across Multiple Apps

​Multi-Environment Setup

​Example Use Cases

​Use Case 1: Automated Data Quality Checks

​Use Case 2: Intelligent Customer Support

​Use Case 3: Financial Reporting Automation

​Next Steps

Agent Orchestration Center

Agent Architecture

Automation System

Snowflake Cortex Docs

Overview

Prerequisites

Elementum Requirements

Snowflake Requirements

Verify Your Snowflake AI Provider

Step 1: Prepare Snowflake Cortex Agents

Verify Cortex Agents in Snowflake

Required Permissions

Step 2: Configure Intelligence in Your App

Access Intelligence Settings

Add External Agent

What Happens During Discovery

Step 3: Understanding Cortex REST APIs

Agent Discovery API

Agent Run API

Threads API

Step 4: Integrate Agents into Automations

Using External Agents in Automation Actions

Example: Data Analysis Automation

Using Agents in Multiple Automations

Step 5: Monitor and Maintain

Monitoring Agent Performance

Provider Connection Health

Maintenance Tasks

Configuration Best Practices

Security Best Practices

Performance Optimization

Error Handling Patterns

Troubleshooting

Discovery Issues

Runtime Issues

Multi-App Configurations

Using Agents Across Multiple Apps

Multi-Environment Setup

Example Use Cases

Use Case 1: Automated Data Quality Checks

Use Case 2: Intelligent Customer Support

Use Case 3: Financial Reporting Automation

Next Steps