dbt_cortex_agent

dbt_cortex_agent 0.0.5 is a Snowflake-only dbt package and Python companion for defining, versioning, and evaluating Cortex Agents from dbt models. A materialized='cortex_agent' model body is the native Agent YAML specification. dbt owns the complete Agent lifecycle; Python is limited to local skill files, runtime smoke, and evaluation coordination.

Install one immutable version on two surfaces

Install the Python companion from PyPI:

pipx install 'dbt-cortex-agent[runtime]==0.0.5'

For a managed Python environment, use:

python -m pip install 'dbt-cortex-agent[runtime]==0.0.5'

dbt does not install packages from PyPI. Pin the dbt package separately to the public HTTPS v0.0.5 Git tag in packages.yml:

packages:
  - git: "https://github.com/Jeremy-Demlow/dbt-cortex-agent.git"
    revision: v0.0.5

PyPI version 0.0.5 and Git tag v0.0.5 identify the same immutable release across the CLI and dbt surfaces. Run dbt deps, then dbt-cortex-agent doctor --project-dir . --json; doctor verifies that the CLI, declared dbt dependency, and installed consumer dbt package versions align. A full immutable Git SHA is accepted only when actual installed package metadata under dbt_packages/dbt_cortex_agent reports the matching version; a source checkout's root dbt_project.yml is not installation evidence. The supported runtime is Python >=3.10,<4, dbt >=1.10,<2.0, and dbt-snowflake; see compatibility and installation.

The CLI also requires the Snowflake CLI (snow) on PATH; doctor checks both the dbt and snow executables. By default, dbt-cortex-agent init configures an existing dbt project by appending missing dependency and safety-variable entries. It does not create a dbt project or scaffold Agent models, semantic views, evaluation models, seeds, or skill files.

For the fixed synthetic tutorial, preview the package-owned Orders starter in an existing dbt project:

dbt-cortex-agent init --project-dir . --starter orders \
  --package-source https://github.com/Jeremy-Demlow/dbt-cortex-agent.git --json

The preview reports the exact seed, semantic-view, Agent, optional eval, dependency, and .dbtignore actions without writing. After review, add --apply. The command validates every destination before writing, keeps identical files unchanged, and fails closed if any generated file already has different content. It has no force mode and is not a generic project or Agent wizard.

Five-minute non-mutating quickstart

From a consumer dbt project with a full-body Agent model:

dbt-cortex-agent doctor --project-dir . --target sandbox --json
dbt-cortex-agent manifest validate --project-dir . --target sandbox --json
dbt compile --select orders_assistant

These commands do not mutate Snowflake. dbt compile renders and validates the full Agent body without invoking its materialization. Follow the quickstart to create the metadata and bootstrap explicit allowlists.

For Cortex Code-guided adoption, use the project-local dbt-cortex-agent-project skill. It discovers an existing dbt project, establishes objective/levers/data/proof, and guides an existing semantic view, the fixed Orders starter, or an existing Agent into dbt-owned metadata. It is script-free, shows manual 0.0.5 command parity, and stops separately before local writes, Snowflake mutation/runtime, paid evaluation, and baseline movement. The checked-in skill is not a claim of catalog publication or live Snowflake verification.

Controlled deploy

Deploy selected Agents and their declared skills through one package workflow:

dbt-cortex-agent agent deploy --project-dir . --target sandbox \
  --agent orders_assistant --connection sandbox --database ANALYTICS_DEV \
  --allow-target sandbox --allow-database ANALYTICS_DEV --apply

The model relation determines the physical Agent FQN. The model body is passed directly to the materialization, which validates explicit orchestration, checks staged skills, updates LIVE, commits immutable VERSION$N, and reconciles the configured alias. The package preflights and uploads selected skills before it invokes the dbt dependency closure. dbt remains the sole Agent DDL authority. No Makefile or copied adopter Python script is required.

A target-resolved manifest may contain Agents in multiple approved databases. The package carries each selected Agent's complete database.schema.object identity through skill and runtime operations and validates every Agent, stage, eval table, evaluation stage, and result database against repeatable allowlists.

one dbt target manifest
  +-- FINANCE.AGENTS.FINANCE_ANALYST
  +-- MARKETING.AGENTS.CAMPAIGN_ANALYST
  +-- AI_FOCUS.AGENTS.ENTERPRISE_ASSISTANT

selected resource FQN -> allowlist validation -> bounded operation

One package invocation consumes one dbt target and its fresh manifest. Parsing and coordinating several dbt targets belongs to adopter CI, where each target has a separately reviewed role, warehouse, and approval boundary. Read lifecycle and Snowflake setup before crossing this boundary.

CLI or dbt macros

Use dbt for Agent render and deployment. Use Python when local file upload, stable process exits/JSON, connector clients, or durable evaluation artifacts are required. Python owns no Agent lifecycle operation and provisions no stage.

Lifecycle and evaluation

The materialization validates and hashes the rendered spec plus staged skills, skips unchanged versions, modifies LIVE, commits an immutable version, and applies the requested alias. Promotion, rollback, grants, MCP attachment, and skill smoke remain explicit operations.

Evaluation is optional and targets the same Agent selected by the model relation. eval run is a client for that already deployed Agent, a materialized eval table, and an evaluation stage; --apply incurs Cortex spend. It never deploys or changes an Agent. It writes candidate JSON with plan identity, ordered ground-truth refs, policy, and pre/post DEFAULT provenance for threshold and accepted-baseline gates. See evaluations.

For a complete evaluation workflow, eval verify materializes and tests the selected eval model, executes native evaluation, consumes the exact candidate, and applies intrinsic thresholds or an established baseline. Preview is free; --apply is paid. Baseline acceptance remains a separate explicit command.

Documentation

• Start: installation, quickstart, Snowflake setup
• Configure: configuration model, Agent metadata, eval metadata, variables
• Operate: lifecycle, skills, evaluations, CI, releasing
• Reference: CLI, macros, compatibility, architecture, troubleshooting
• Change: changelog

Limitations and policies

• Snowflake and dbt Core with dbt-snowflake are the release authority; DuckDB is unsupported and Fusion is advisory.
• dbt build --select <agent_model> deploys model Agents; dbt compile is the non-mutating preview.
• Property YAML may use target, var, and env_var, but cannot call package macros.
• Skills and MCP connectors are excluded from built-in native Agent Evaluation and require separate smoke/integration proof.
• Live mutation, runtime smoke, and evaluation spend are never default operations.
• This independent, maintainer-led package is not sponsored, endorsed, supported, or maintained by Snowflake Inc.

Apache License 2.0. See LICENSE, contributing, security, support, and Code of Conduct.