Create a Snowflake agent with semantic views

Create a Snowflake Cortex agent that answers natural-language questions about your deployed RelationalAI outputs through a Snowflake semantic view, then test the agent in Snowflake CoWork.

Prerequisites: A deployed RelationalAI model with the output tables or views you want to query materialized in Snowflake.
A Snowflake account where Cortex Agents and CoWork are available.

Request Snowflake privileges

Use one role to create the semantic view and agent and to test the agent in CoWork. If your role doesn’t already have the required privileges, replace the angle-bracket placeholders in the following template and ask a Snowflake administrator to run it:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE <AGENT_ROLE>;

GRANT USAGE ON DATABASE <MODEL_DB> TO ROLE <AGENT_ROLE>;
GRANT USAGE ON SCHEMA <MODEL_DB>.<MODEL_SCHEMA> TO ROLE <AGENT_ROLE>;
GRANT SELECT ON TABLE <MODEL_DB>.<MODEL_SCHEMA>.<OUTPUT_TABLE> TO ROLE <AGENT_ROLE>;

GRANT USAGE ON DATABASE <AGENT_DB> TO ROLE <AGENT_ROLE>;
GRANT USAGE ON SCHEMA <AGENT_DB>.<AGENT_SCHEMA> TO ROLE <AGENT_ROLE>;
GRANT CREATE SEMANTIC VIEW ON SCHEMA <AGENT_DB>.<AGENT_SCHEMA> TO ROLE <AGENT_ROLE>;
GRANT CREATE AGENT ON SCHEMA <AGENT_DB>.<AGENT_SCHEMA> TO ROLE <AGENT_ROLE>;
GRANT USAGE ON WAREHOUSE <AGENT_WAREHOUSE> TO ROLE <AGENT_ROLE>;

<AGENT_ROLE> is the role you use in Snowsight and CoWork, granted SNOWFLAKE.CORTEX_AGENT_USER so it can use Cortex Agents.
<MODEL_DB>.<MODEL_SCHEMA>.<OUTPUT_TABLE> is a deployed RelationalAI output table that the semantic view will query.
<AGENT_DB>.<AGENT_SCHEMA> is the schema where you will create the semantic view and agent, and <AGENT_WAREHOUSE> is the warehouse the agent uses to run semantic view queries.

Every deployed output the semantic view queries requires its own GRANT SELECT statement, and view outputs use GRANT SELECT ON VIEW instead of GRANT SELECT ON TABLE.
You can run SHOW GRANTS TO ROLE <AGENT_ROLE> to confirm that the role has all required privileges before continuing.
Other users who test the agent in CoWork with a different role also need runtime USAGE and tool privileges. See Snowflake’s Cortex Agents access control and authentication guide.

Create a semantic view

A semantic view gives Cortex Analyst business names for your deployed model outputs, defines how those outputs relate, and specifies the metrics to calculate.

Before creating the view, write and run one SQL query against your deployed outputs that answers a representative question, such as a count or total grouped by a category. Save both the query and its results. You will use them as context for Autopilot and to verify the semantic view and agent later. If you don’t yet know which outputs or columns answer your question, query your model with SQL first.

Use this table to choose how to create the semantic view:

What to use	When to use it
Semantic View Autopilot	Use when you want Snowsight to draft tables, relationships, dimensions, and metrics from your outputs and baseline SQL.
SQL DDL	Use when you want to write and version-control a `CREATE SEMANTIC VIEW` statement in SQL.
Snowflake YAML specification	Use when you prefer to define the Snowflake semantic view in YAML and create it with `SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML`.

Use Semantic View Autopilot

Use Autopilot for the shortest path to a first semantic view. Review its suggestions before creating the view. Generated descriptions and relationships are a starting point, not a substitute for validating your model’s business meaning.

Open Autopilot in Snowsight.

In Snowsight, select Workspaces > Add new > Semantic View.
Name the view and add context.

Choose the database and schema where you want to save the view, then enter a name and description for the subject area it covers. Paste your baseline question and SQL as context for the terms, joins, and measures the agent needs.
Select the deployed outputs.

Select only the output tables or views and columns needed for this subject area and baseline SQL, rather than every output in your model. For a first semantic view, Snowflake recommends fewer than 10 tables or views, though this isn’t a hard limit, and no more than 50 columns for performance.
Review and create the view.

Review the logical tables, keys, relationships, metric definitions, and generated descriptions against your baseline SQL. Check what each row represents, which columns identify it, and whether each metric uses the intended aggregation. Correct any suggestion that doesn’t match your model, then create the view.

Create the view with SQL DDL

Use SQL DDL when you want to define and maintain the semantic view in SQL. Replace every angle-bracket placeholder, including the brackets, with your own names and expressions before running the statement:

CREATE SEMANTIC VIEW <AGENT_DB>.<AGENT_SCHEMA>.<SEMANTIC_VIEW_NAME>
  TABLES (
    primary_output AS <MODEL_DB>.<MODEL_SCHEMA>.<OUTPUT_TABLE>
      PRIMARY KEY (<PRIMARY_KEY_COLUMN>)
      COMMENT = '<What one row in this output represents>',
    related_output AS <MODEL_DB>.<MODEL_SCHEMA>.<RELATED_OUTPUT>
      PRIMARY KEY (<RELATED_KEY_COLUMN>)
      COMMENT = '<What one row in the related output represents>'
  )
  RELATIONSHIPS (
    primary_to_related AS
      primary_output (<FOREIGN_KEY_COLUMN>) REFERENCES related_output
  )
  DIMENSIONS (
    related_output.<DIMENSION_NAME> AS <CATEGORY_COLUMN>
      COMMENT = '<Business meaning of this category>'
  )
  METRICS (
    primary_output.<METRIC_NAME> AS <AGGREGATE_EXPRESSION>
      COMMENT = '<What this metric measures, including units>'
  )
  COMMENT = '<What questions this semantic view answers>';

primary_output and related_output are logical table aliases used inside the semantic view, mapped to your deployed <OUTPUT_TABLE> and <RELATED_OUTPUT> tables or views.
RELATIONSHIPS links <FOREIGN_KEY_COLUMN> on primary_output to the PRIMARY KEY column <RELATED_KEY_COLUMN> on related_output, matching the join in your baseline SQL.
DIMENSIONS exposes columns used to group or filter results, and METRICS defines aggregate expressions such as COUNT or SUM calculated for those groups.

A semantic view over a single output table or view doesn’t need related_output in TABLES or a RELATIONSHIPS clause, and its dimensions use the primary_output prefix.
Each metric aggregation must match what one row in primary_output represents, and DIMENSIONS must include any filter columns from your baseline SQL.
CREATE SEMANTIC VIEW fails if <SEMANTIC_VIEW_NAME> already exists. You can choose a new name or update the existing view with a carefully reviewed CREATE OR ALTER SEMANTIC VIEW statement after checking its grants and dependencies.

Verify the semantic view

After you create the semantic view, run a semantic query to confirm that it answers your baseline question. Replace the placeholders with the database, schema, semantic view name, and logical table, dimension, and metric names defined in your view. If you used Autopilot, use its generated names:

SELECT *
FROM SEMANTIC_VIEW(
    <AGENT_DB>.<AGENT_SCHEMA>.<SEMANTIC_VIEW_NAME>
    DIMENSIONS related_output.<DIMENSION_NAME>
    METRICS primary_output.<METRIC_NAME>
);

Include all dimensions, metrics, and filters from your baseline SQL. Compare the returned groups and metric values with your saved baseline results over the same source data. They should match. If they don’t, check the definitions using the troubleshooting steps.

This confirms that the semantic view can answer your question. It doesn’t yet verify that the agent uses it.

Create a Cortex agent

Create a Cortex agent with a Cortex Analyst tool that queries your semantic view. Replace every angle-bracket placeholder, including the brackets, with your own names and verified question before running the statements:

CREATE AGENT <AGENT_DB>.<AGENT_SCHEMA>.<AGENT_NAME>
  COMMENT = 'Answers questions about deployed model outputs'
  PROFILE = '{"display_name": "<AGENT_DISPLAY_NAME>"}'
  FROM SPECIFICATION
  $$
  models:
    orchestration: auto

  instructions:
    response: "Answer from the semantic view results. Label the metrics and state any filters applied."
    orchestration: "Use the <TOOL_NAME> tool for questions about the deployed model outputs."
    sample_questions:
      - question: "<YOUR_QUESTION>"

  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "<TOOL_NAME>"
        description: "Queries deployed model outputs through a semantic view."

  tool_resources:
    <TOOL_NAME>:
      semantic_view: "<AGENT_DB>.<AGENT_SCHEMA>.<SEMANTIC_VIEW_NAME>"
      execution_environment:
        type: "warehouse"
        warehouse: "<AGENT_WAREHOUSE>"
  $$;

-- Verify that the agent exists and references your semantic view
DESCRIBE AGENT <AGENT_DB>.<AGENT_SCHEMA>.<AGENT_NAME>;

PROFILE sets <AGENT_DISPLAY_NAME>, the name shown when selecting the agent in Snowflake CoWork.
tools defines a cortex_analyst_text_to_sql tool named <TOOL_NAME>, and instructions tells the agent when to call that tool and how to format responses.
tool_resources connects <TOOL_NAME> to <AGENT_DB>.<AGENT_SCHEMA>.<SEMANTIC_VIEW_NAME> and runs its generated SQL on <AGENT_WAREHOUSE>.

The key under tool_resources must match <TOOL_NAME> under tools exactly.
The DESCRIBE AGENT output lists <TOOL_NAME> and your semantic view once CREATE AGENT succeeds. If creation fails, check your YAML indentation and the CREATE AGENT grant before retrying.

Test the agent in Snowflake CoWork

Use the same role that created the agent for your first test, or a role with the runtime grants described in Request Snowflake privileges.

Open the agent in CoWork.

Open Snowflake CoWork and select the display name you configured for the agent.
Ask your verified question.

Ask the same question you used to verify the semantic view, including the same categories, metrics, and filters.
Compare the result.

Confirm that the agent calls your Cortex Analyst tool and returns the expected groups, metrics, and filters. Compare the returned values and generated SQL with your saved baseline SQL results. If they differ, use Troubleshoot semantic view and agent issues before relying on the answer.

Troubleshoot semantic view and agent issues

Match the symptom you see to the layer that needs attention:

Symptom	What to check and fix
The `SEMANTIC_VIEW` verification query fails	Confirm that the view points to existing output tables or views and columns, that your active role has `SELECT` on them, and that the view defines the queried dimensions and metrics. Update the view and rerun Verify the semantic view.
The `SEMANTIC_VIEW` query runs, but its numbers don’t match your baseline SQL	Check the grouping, filters, and metric aggregations first. If the view joins outputs, confirm that `RELATIONSHIPS` matches your baseline join and that each referenced `PRIMARY KEY` is unique so joins don’t duplicate rows and inflate counts or sums.
The agent answers from general knowledge or can’t query the data	Confirm that `<TOOL_NAME>` matches under both `tools` and `tool_resources`, that `semantic_view` is fully qualified, and that your active role has `USAGE` on the agent, semantic view, and `<AGENT_WAREHOUSE>`. See Snowflake’s Cortex Agents access control and authentication guide.
Your baseline SQL itself returns unexpected, empty, or stale data	Verify the deployed model outputs before changing the semantic view or agent. See Troubleshoot a deployed model.

Where to go next

Continue with the task that matches what you need to do next: