Cortex Agent Versioning and Multi-Environment Deployment
Introduction
Organisations are moving rapidly toward agentic workflows, enabling business users to query data in natural language without requiring deep technical expertise. As these agents are now directly involved in critical business decisions, updating them requires strict engineering rigour. Managing agent versions, automated evaluation, structured approvals, and rapid rollbacks are non-negotiable. This article explores a practical approach to managing Snowflake Cortex Agent versioning and multi-environment deployment.
Most data teams already have a release process for their data. This article uses one such setup as an example: dbt transforms and loads the silver and gold tables, and builds the views and semantic views on top of them. These dbt models are built in a development environment, validated in test and promoted to production, often with a Git branch for each environment. Cortex Agents add one more layer to this process. An agent has its own configuration, made up of instructions, models, and tools, and this configuration also needs to move from one environment to the next. Before building the pipeline, it is critical to decide whether a single agent should serve all environments, or whether each environment should have its own agent.
One agent for all environments, or one agent per environment?
Snowflake’s versioning model is built around a single agent. Changes are made in the live version, committed, tested through an alias and, once approved, set as the default version for CoWork users. Rolling back means moving the alias and the default version back to the previous version.
When a single agent is a good fit
A single agent fits when the versions at each stage use the same tools and data. Changes are then limited to the agent configuration, such as instructions, sample questions or model, and promoting a version releases exactly what was tested.
Consider a FinOps assistant built by the platform team. It answers questions such as “Which warehouses used the most credits last month?” using a single semantic view over Snowflake’s ACCOUNT_USAGE views. Snowflake provides these views, and each account has only one copy of them. Because the underlying data and tools exist only once, only the agent configuration changes between releases. The team creates a new version, tests it using the staging alias, and then moves the production alias to it.
Separate databases per environment: comparing the two options
Many organisations keep separate databases for each environment, so the agent’s semantic views and search services also have Dev, Test and Prod copies.
A single agent can still serve all three, with a separate version for each environment. The alternative is to create one agent per environment, for example `SALES_AGENT` in each of `SALES_DEV`, `SALES_TEST` and `SALES_PROD`, all deployed from the same Git template. Here is how the two options compare across promotion, version history, the draft, the default version and access:
Both options work. A single agent across environments is technically possible, but on every point above, separate agents keep each environment’s history, draft, default version and access independent, in the same way the databases already are. Each agent still uses Snowflake’s alias pattern for testing, release and rollback.
Tool changes vs agent changes: when does an agent need a new version?
An agent refers to its tools, such as semantic views and search services, by their fully qualified names in tool_resources. If a semantic view or search service is recreated under the same name, for example when dbt rebuilds it, the agent picks up the new definition without needing to ALTER the agent. Users see the change immediately, so the agent should be re-evaluated after such changes. Agent evaluation is covered later in this article.
A new agent version is needed when the agent specification itself changes, for example when a tool is renamed, a tool is added or removed, a tool’s configuration changes (such as filters or the warehouse), or the instructions or model change. Named versions cannot be changed once committed, so each of these changes is committed as a new version.
Keeping grants intact
When dbt or a pipeline recreates an object with `CREATE OR REPLACE`, the object’s grants need attention. Adding `COPY GRANTS` keeps the explicit privileges that were granted on the original object, except OWNERSHIP. Future grants are not copied. Without `COPY GRANTS`, the explicit grants are lost, and roles that could use the object before may lose access to it. Agents and semantic views both support `COPY GRANTS`.
Version changes made with `ALTER AGENT`, such as adding a version, moving an alias or setting the default version, are different. They change the existing agent in place, so the agent and its grants remain.
From pull request to production: the release pipeline
With one agent per environment, every change follows the same path (Dev -> Test -> Prod) including small updates to instructions or sample questions. No environment should be skipped, for three reasons:
- Small changes can still change behaviour. A one-line edit to the instructions or a new sample question can change how the agent picks tools or phrases answers. Its effect is only known once the change has been tested.
- Environments stay in step. If a change goes straight to Prod, Dev and Test no longer match it. The next change is then built and tested against an outdated version, and the direct change has to be back-merged into the lower branches. If it is not, the next release from Dev overwrites it with the outdated version.
- Every release has the same record. When each change passes the same reviews, evaluations and approvals, it is always clear what was tested and approved before it reached users.
Change tiers: the same path, different checks
Not every change carries the same risk, so the checks can differ even though the release path does not. Grouping changes into tiers makes this explicit:
Each tier’s checks and approvals, such as code reviews, user testing and production sign-off, should follow your organisation’s existing release process. When a change spans several tiers, it follows the strictest one.
Pipeline steps
Here are the recommended steps for deploying data and agent changes. The same steps run in each environment, against that environment’s own objects.
1. Review (PR + tier check): A pull request is raised, and an automated check classifies the change into one of the tiers above, based on what the PR contains. The tier decides which reviews and approvals the change needs.
Get Jayashree Suresh’s stories in your inbox
Join Medium for free to get updates from this writer.
2. Plan & validate (detect changes): The pipeline detects what has changed: the dbt models, the agent specification, or both. This decides which of the next steps run. It then validates the changed files before anything is deployed, for example by compiling the dbt project and checking that the agent specification is valid.
3. Build data (dbt, if changed): If the dbt models changed, dbt builds the tables, views and semantic views. If only the agent changed, this step is skipped.
4. Deploy agent (new version): If the agent specification changed, a new agent version is created from the Git specification, using that environment’s object names.
5. Evaluate (score + compare): The new version is scored against the agreed question set and compared with the current version. For a data-only change, the current version is evaluated against the new data instead.
6. Promote (goes live): If the evaluation passes and the approvals for the tier are in place, the new version is made live by moving the production alias and the default version to it.
Deploying data and the agent
dbt builds the tables, views, semantic views and other objects the agent depends on. The agent is then deployed from its specification in Git as a new version.
Before a new version is created in an agent that is serving users, pin `DEFAULT_VERSION` to the approved version. Otherwise the new commit becomes the default straight away, before it has been evaluated.
A change that touches only data needs care. dbt rebuilds the objects, the agent version stays the same, and the current version is re-evaluated against the new data. Because the new data is already live when the evaluation runs, this evaluation is a check, not a gate: it can find a problem, but it cannot stop the change from reaching users.
Evaluate, promote and roll back
Cortex Agent Evaluations score an agent against a set of questions. Each run calls the agent again for every question and scores the response.
To make results comparable from one run to the next, evaluate a committed version, not the editable draft, and pin the metric versions used to score it.
Agree on a question set with the business team for each agent, with the expected answers. Then agree a minimum score for each agent. Agent responses vary between runs, so run the same questions several times first to learn the normal range of scores, and set the threshold based on that range rather than a single run. Naming the orchestration model, instead of using auto, keeps model changes from being mistaken for normal variation.
If the new version scores below the threshold, or noticeably below the current version, the pipeline stops and the change is not promoted; users stay on the current version, so nothing needs to be rolled back. For a data-only change, a failed check means the data change is fixed or reverted, because it is already live. If it passes and the approvals for the tier are in place, the `production` alias and the default version are moved to the new version, so CoWork users get it straight away, and the previous version is kept.
If a problem appears after promotion, the alias and default are pointed back to the previous version, which restores the agent configuration, but not the data or tools it uses.
It is recommended that any edits made in the Snowsight UI are copied back into Git through a pull request, so Git stays the source of truth.
Key takeaways
- When tools live in separate databases per environment, use one agent per environment; a single agent fits when tools and data exist only once.
- Use committed versions for production and pin agent and metric versions for comparable evaluations.
- Calibrate evaluation gates with repeated runs and business-specific acceptance criteria.
- Validate tool changes and preserve intended access when replacing objects.
- Follow the same Dev -> Test -> Prod path for every change, with checks matched to the change tier.
The architecture and release-process recommendations in this article reflect my own views, not an official Snowflake reference architecture. This includes when to use one agent or separate agents, the combined dbt-agent pipeline, change tiers, and thresholds and approvals. Adapt the approach to your team’s requirements.
