| name | routing-agent |
| description | Create Snowflake Intelligence agent for OpenRouteService routing functions. Use when: setting up ORS demo, creating route planning agent, integrating directions/isochrones/optimization with Cortex. Do NOT use for: deploying fleet intelligence demos, route deviation analysis, or changing ORS configuration. Triggers: openrouteservice demo, routing agent, ORS agent, routing intelligence. |
| depends_on | ["build-routing-solution"] |
| metadata | {"author":"Snowflake SIT-IS","version":"1.0.0","category":"intelligence-agent"} |
OpenRouteService Intelligence Demo
Create a Snowflake Intelligence agent that provides AI-powered route planning using OpenRouteService functions with natural language geocoding.
Configuration
| Parameter | Default | Description |
|---|
DATABASE | FLEET_INTELLIGENCE | Target database for all objects |
SCHEMA | ROUTING_AGENT | Schema for agent procedures and agent definition |
WAREHOUSE | ROUTING_ANALYTICS | Warehouse for geocoding and routing queries |
AGENT_NAME | ROUTING_AGENT | Name of the Cortex Agent to create |
Prerequisites
- OpenRouteService Native App installed with functions:
DIRECTIONS, ISOCHRONES, ISOCHRONES_CLIPPED, OPTIMIZATION
- Cortex AI access (claude-sonnet-4-5 for geocoding)
- Overture Maps Places share acquired (
OVERTURE_MAPS__PLACES from Snowflake Marketplace listing GZT0Z4CM1E9KR) — used by TOOL_POI_IN_ISOCHRONE
- A role with privileges listed in the Required Privileges section below
Required Privileges
| Privilege | Scope | Reason |
|---|
| CREATE DATABASE | Account | Creates FLEET_INTELLIGENCE database |
| CREATE WAREHOUSE | Account | Creates ROUTING_ANALYTICS warehouse |
| USAGE ON DATABASE FLEET_INTELLIGENCE | Database | Uses the setup database |
| CREATE SCHEMA | Database (FLEET_INTELLIGENCE) | Creates ROUTING_AGENT schema |
| CREATE PROCEDURE | Schema (FLEET_INTELLIGENCE.ROUTING_AGENT) | Creates TOOL_DIRECTIONS, TOOL_ISOCHRONE, TOOL_POI_IN_ISOCHRONE, TOOL_ROUTE_OPTIMIZATION |
| CREATE CORTEX AGENT | Schema (FLEET_INTELLIGENCE.ROUTING_AGENT) | Creates ROUTING_AGENT |
| USAGE ON DATABASE OPENROUTESERVICE_APP | Database | Calls ORS DIRECTIONS, ISOCHRONES, ISOCHRONES_CLIPPED, OPTIMIZATION functions |
| IMPORT SHARE | Account | Acquires OVERTURE_MAPS__PLACES from Marketplace (one-time) |
| USAGE ON DATABASE OVERTURE_MAPS__PLACES | Database | Reads Overture POI data for TOOL_POI_IN_ISOCHRONE |
| SNOWFLAKE.CORTEX_USER | Database role | Enables AI_COMPLETE calls for geocoding |
Note: ACCOUNTADMIN is NOT required. Create a custom role with the above privileges, or use any role that has them.
Error Logging
Follow the Error Logging convention in AGENTS.md. Log file prefix: routing-agent.
Execution Rules
- One statement per
snowflake_sql_execute tool call.
- Always use fully qualified object names.
- Never use
SET session variables.
- Verify row counts after each CTAS.
- All CREATE statements must include a COMMENT tracking tag.
Quick Start
No seed data or pre-computed tables required. The routing agent consists of stored procedures and a Cortex Agent definition. Run snow sql -f .cortex/skills/routing-agent/references/deploy-agent.sql -c <connection> to create all objects.
Workflow
All stored procedure and agent SQL definitions are in references/agent-definitions.md.
Step 1: Set Query Tag for Tracking
Set session query tag for attribution tracking.
ALTER SESSION SET query_tag = '{"origin":"sf_sit-is-fleet","name":"oss-deploy-snowflake-intelligence-routing-agent","version":{"major":1, "minor":0},"attributes":{"is_quickstart":1, "source":"sql"}}';
Step 2: Verify ORS Functions and Services
2a. Check functions exist:
SHOW USER FUNCTIONS IN SCHEMA OPENROUTESERVICE_APP.CORE;
Verify: DIRECTIONS(VARCHAR, VARIANT), ISOCHRONES(VARCHAR, FLOAT, FLOAT, NUMBER), OPTIMIZATION(VARIANT, VARIANT). If missing, install the OpenRouteService Native App.
2b. Check services are running (CRITICAL):
SHOW SERVICES IN SCHEMA OPENROUTESERVICE_APP.CORE;
Required services (all must be RUNNING): ORS_SERVICE, VROOM_SERVICE, ROUTING_GATEWAY_SERVICE, DOWNLOADER. If any is SUSPENDED, resume with CALL OPENROUTESERVICE_APP.CORE.RESUME_ALL_SERVICES(); and verify with SELECT OPENROUTESERVICE_APP.CORE.CHECK_HEALTH();.
Step 3: Create Database, Schema, and Warehouse
Create dedicated objects for the routing agent.
CREATE DATABASE IF NOT EXISTS FLEET_INTELLIGENCE
COMMENT = '{"origin":"sf_sit-is-fleet", "name":"oss-deploy-snowflake-intelligence-routing-agent", "version":{"major":1, "minor":0}, "attributes":{"is_quickstart":1, "source":"sql"}}';
CREATE SCHEMA IF NOT EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT
COMMENT = '{"origin":"sf_sit-is-fleet", "name":"oss-deploy-snowflake-intelligence-routing-agent", "version":{"major":1, "minor":0}, "attributes":{"is_quickstart":1, "source":"sql"}}';
CREATE WAREHOUSE IF NOT EXISTS ROUTING_ANALYTICS
WAREHOUSE_SIZE = 'XSMALL' AUTO_SUSPEND = 60 AUTO_RESUME = TRUE
COMMENT = '{"origin":"sf_sit-is-fleet", "name":"oss-deploy-snowflake-intelligence-routing-agent", "version":{"major":1, "minor":0}, "attributes":{"is_quickstart":1, "source":"sql"}}';
Step 4: Deploy All Procedures and Agent
Goal: Create all 3 tool procedures (TOOL_DIRECTIONS, TOOL_ISOCHRONE, TOOL_ROUTE_OPTIMIZATION) and the Cortex Agent in a single step.
snow sql -f .cortex/skills/routing-agent/references/deploy-agent.sql -c <connection>
This creates:
- TOOL_DIRECTIONS: Wraps ORS DIRECTIONS with AI geocoding (claude-sonnet-4-5) for natural language location input
- TOOL_ISOCHRONE: Wraps ORS ISOCHRONES with AI geocoding for reachability analysis
- TOOL_POI_IN_ISOCHRONE: Joins an isochrone polygon with Overture Maps POIs (cafes, restaurants, shops, etc.) via
ST_WITHIN
- TOOL_ROUTE_OPTIMIZATION: Python procedure wrapping ORS OPTIMIZATION for multi-stop delivery routing
- ROUTING_AGENT: Cortex Agent with tool bindings to all 4 procedures
Reference: For annotated explanations of each procedure, see references/agent-definitions.md.
Step 5: Register Agent with Snowflake Intelligence (Optional)
Note: This step requires Snowflake Intelligence to be configured on the account. The agent is fully functional via direct INVOKE_AGENT calls without SI registration.
-
Check if Snowflake Intelligence is available:
SHOW SNOWFLAKE INTELLIGENCE;
If this returns an error or no results, skip the rest of this step.
-
Register the agent:
ALTER SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT
ADD AGENT FLEET_INTELLIGENCE.ROUTING_AGENT.ROUTING_AGENT;
Step 6: Test the Agent
Test queries must use locations within the ORS-configured region. To determine the region:
DESCRIBE SERVICE OPENROUTESERVICE_APP.CORE.ORS_SERVICE;
Parse the spec to find the configured region name from /home/ors/files/<REGION_NAME>.osm.pbf.
Before testing, verify all services are RUNNING (see Step 2b).
Sample queries by region:
| Region | Directions | Isochrone | Optimization | POIs in isochrone |
|---|
| San Francisco | "Driving directions from Union Square to Fisherman's Wharf" | "Areas reachable within 15 min by car from Union Square" | "Optimize deliveries to Ferry Building, Pier 39, Ghirardelli Square — 2 vehicles from Union Square" | "What cafes can I reach within a 15 minute ebike ride from Civic Center, San Francisco" |
| New York | "Driving directions from Times Square to Central Park" | "Areas reachable within 15 min by car from Grand Central" | "Optimize deliveries to Empire State, Rockefeller Center, Times Square — 2 vehicles from Grand Central" | "Pharmacies within 10 minutes walk of Grand Central" |
| London | "Driving directions from Tower Bridge to Buckingham Palace" | "Areas reachable within 15 min by car from King's Cross" | "Optimize deliveries to British Museum, Tower of London, Westminster Abbey — 2 vehicles from Trafalgar Square" | "Restaurants within 20 minutes walk of King's Cross" |
| Berlin | "Driving directions from Brandenburg Gate to Alexanderplatz" | "Areas reachable within 15 min by car from Hauptbahnhof" | "Optimize deliveries to Reichstag, Checkpoint Charlie, East Side Gallery — 2 vehicles from Alexanderplatz" | "Bars within 15 minutes cycle from Alexanderplatz" |
Use central city locations as depots.
Step 7: Open Snowflake Intelligence UI
Get org/account names, then open the UI:
SELECT CURRENT_ORGANIZATION_NAME() AS org_name, CURRENT_ACCOUNT_NAME() AS account_name;
Open: https://ai.snowflake.com/<org_name>/<account_name>/#/ai
Examples
Example 1: Deploy routing agent for San Francisco
User says: "Create a routing agent"
Actions:
- Verify ORS functions and services (Step 2)
- Create database/schema (Step 3)
- Create TOOL_DIRECTIONS, TOOL_ISOCHRONE, TOOL_ROUTE_OPTIMIZATION procedures (Steps 4-6)
- Create Cortex Agent (Step 7)
- Test with: "Driving directions from Union Square to Fisherman's Wharf"
Result: Routing agent accessible via Snowflake Intelligence UI
Example 2: Test agent with different region
User says: "Test the routing agent with London locations"
Actions:
- Verify ORS is configured for London (
DESCRIBE SERVICE check)
- Test: "Driving directions from Tower Bridge to Buckingham Palace"
- Test: "Areas reachable within 15 min by car from King's Cross"
Result: Agent returns London-specific routing results (no redeployment needed -- agent is region-agnostic)
Stopping Points
- Step 2: Verify ORS functions exist before proceeding
- Step 3: Verify database, schema, and warehouse exist
- Step 4: Verify deploy-agent.sql completes without errors
- Step 6: Confirm all 3 tools work correctly
Output
- 1 database:
FLEET_INTELLIGENCE
- 1 schema:
FLEET_INTELLIGENCE.ROUTING_AGENT
- 1 warehouse:
ROUTING_ANALYTICS
- 4 stored procedures with AI geocoding and error handling
- 1 Cortex Agent registered in Snowflake Intelligence
- Agent accessible via Snowsight UI and REST API
Troubleshooting
| Issue | Solution |
|---|
| Agent not visible in UI | Run ALTER SNOWFLAKE INTELLIGENCE ... ADD AGENT |
| Geocoding fails | Check Cortex AI access and model availability |
| Empty directions | Verify ORS map data covers the requested region |
| Routing functions fail | Check service status with SHOW SERVICES IN SCHEMA OPENROUTESERVICE_APP.CORE; and resume suspended services |
Tool returns Parameter 'profile' has incorrect value of 'unknown' | The requested profile is not loaded in this ORS install. The default build-routing-solution install loads driving-car, driving-hgv, cycling-electric only. Other ORS profile names (e.g. cycling-regular, cycling-mountain, foot-walking) are valid identifiers but require a different p_profiles value when calling build-routing-solution. See .cortex/skills/build-routing-solution/openrouteservice_app/app/modules/03_region_management.sql (the all_profiles list) for the full set of selectable profile names. |
| Agent says "OpenRouteService is currently unreachable" for POI questions (e.g. "what cafes can I reach") | This is the agent confabulating because it had no POI search tool. Re-run deploy-agent.sql to install TOOL_POI_IN_ISOCHRONE and ensure OVERTURE_MAPS__PLACES is acquired from Marketplace. |
TOOL_POI_IN_ISOCHRONE returns count=0 | Try a broader category (e.g. restaurant instead of specialty bistro) or a longer travel range. Confirm SELECT COUNT(*) FROM OVERTURE_MAPS__PLACES.CARTO.PLACE returns rows. |
Cleanup
To remove all objects created by this skill:
DROP CORTEX AGENT IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT.ROUTING_AGENT;
DROP PROCEDURE IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT.TOOL_ROUTE_OPTIMIZATION(VARCHAR, VARCHAR, NUMBER, VARCHAR);
DROP PROCEDURE IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT.TOOL_POI_IN_ISOCHRONE(VARCHAR, NUMBER, VARCHAR, VARCHAR, NUMBER);
DROP PROCEDURE IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT.TOOL_ISOCHRONE(VARCHAR, NUMBER);
DROP PROCEDURE IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT.TOOL_DIRECTIONS(VARCHAR, VARCHAR);
DROP SCHEMA IF EXISTS FLEET_INTELLIGENCE.ROUTING_AGENT;
DROP WAREHOUSE IF EXISTS ROUTING_ANALYTICS;
Tip: Use the cleanup skill to auto-discover all tagged objects via COMMENT tracking.
