Setup & the Environment Model

Confirm the ground rules and lock in the environment before you build anything. One codebase targets dev, staging, and prod, and Phase 0 pins down the names everything else references.

Prerequisites

Confirm the ground rules before Phase 0. If anything is missing, resolve it first.

One codebase, three environments

The template is environment-driven. env.yml defines dev, staging, and prod; Snowflake resolves it at run time and injects values that profiles.yml reads with env_var(). You never hardcode a target; you pick an environment and the same code runs against it.

Per-developer schemas in dev mean each engineer's agents, semantic views, and evaluations are isolated, so nobody overwrites anyone else while iterating.

# How the target resolves at run time
EXECUTE DBT PROJECT ... ENVIRONMENT = 'dev'
   → env.yml picks 'dev', evaluates {{ select CURRENT_USER() }}
   → injects DBT_DATABASE / DBT_SCHEMA / DBT_WAREHOUSE / DBT_ROLE
   → profiles.yml reads env_var() → target.database / schema / ...
   → everything dbt builds lands in that target; the agent macro
     substitutes the same values into the agent spec

Business Questions to a Semantic View

Capture the questions the agent must answer, then model the data to support them. The semantic view is the accuracy engine, so this is where the build really begins.

TABLES → RELATIONSHIPS → FACTS → DIMENSIONS → METRICS → COMMENT
      → AI_SQL_GENERATION → AI_QUESTION_CATEGORIZATION → AI_VERIFIED_QUERIES

dbt build --select sv_<name>

The Agent: Orchestration, Response, Tools

Phases 2, 3, and 4 all author the same inline spec, kept in separate layers. The agent object is created once, at the end of Phase 4.

dbt run-operation deploy_<agent>

# Zero-downtime edit to a live agent later:
dbt run-operation deploy_<agent> --args '{alter: true}'

Evaluation: The Verdict

Turn the confirmed questions and answers into a measurable evaluation run. Trust stops being a gut feeling and becomes a score you can track, compare, and hold the line on.

dbt seed
dbt run --select eval_dataset
dbt run-operation run_evaluation --args '{agent_name: <agent>, run_name: <run>, config_file: <config>.yml}'

-- status any time
CALL EXECUTE_AI_EVALUATION('STATUS', {'run_name': '<run>'}, NULL);

-- scores after completion
SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA(
  '<db>', '<schema>', '<AGENT>', 'CORTEX AGENT', '<run>'));

Ship & Automate

With a verdict in hand, promote the same code to production, ship the agent where users work, and let CI/CD and scheduled tasks keep it fresh.

Closing Arguments: ship & automate

With a verdict in hand (target ≥95% answer correctness), promote, ship, and automate: same code, prod target.

-- schedule daily builds + evaluation as Snowflake Tasks
CREATE OR REPLACE TASK daily_cortex_build
  WAREHOUSE = ANALYTICS_WH
  SCHEDULE = 'USING CRON 0 6 * * * America/Denver'
AS EXECUTE DBT PROJECT DEV_DB.CORTEX_AGENTS.CORTEX_LIFECYCLE ARGS='build --target prod';
ALTER TASK daily_cortex_build RESUME;

The CLI path (snow ≥ 3.21)

Inside a Snowsight Workspace you run dbt directly and pick the environment in the run panel. On the CLI, deploy once then execute, with two rules learned the hard way:

# deploy the project object (--default-env sets the compile/run env)
snow dbt deploy cortex_lifecycle --source . \
  --default-env dev --external-access-integration dbt_ext_access --force

# build with an environment. --env MUST come BEFORE the project name;
# use the fully-qualified name so EXECUTE DBT has a database context.
snow dbt execute --env dev DB.SCHEMA.cortex_lifecycle build

# deploy the agent -- the wrapper macro carries the spec, no --args
snow dbt execute --env prod DB.SCHEMA.cortex_lifecycle run-operation deploy_<agent>

Objections (troubleshooting)