Cortex Agent 版本控制¶

Cortex Agent 版本控制支持生命周期管理模型，让您可以通过不同的版本来开发、测试和部署代理。每个代理都有一个 **实时版本**（用于开发的可变工作副本），并且可拥有任意数量的 **命名版本**（用于稳定部署的不可变快照）。通过提交实时版本，您可以创建一个命名版本，从而捕获代理在特定时间点的配置。随后，您可以通过名称、别名或快捷方式，将 API 请求路由到任意版本。

此模型实现了开发工作流程与生产工作流程的分离。您可以在实时版本上进行迭代，在准备就绪后将其提交，并为该提交版本分配别名（例如 production），然后将流量路由到该别名。如果需要回滚，只需将别名指向之前的某个命名版本即可。

代理版本控制的工作原理¶

代理的版本生命周期遵循基于提交的模型：

创建代理时，系统会自动创建一个已提交的 VERSION$1 版本以及一个具有相同规格的 LIVE 版本。
在开发阶段，您可以创建或修改代理的实时版本。
当代理准备好部署时，您可以提交该实时版本。Snowflake 会创建一个带有系统分配标识符的命名版本，格式为 VERSION$N``（例如 ``VERSION$2、VERSION$3）。
您可以为其分配别名，或将该命名版本设为默认版本。
交互请求通过名称、别名或快捷方式指向命名版本，以确保行为稳定且可重复。

提交后，系统不会自动重新创建实时版本。当您准备好恢复开发时，您需要显式创建一个新的实时版本。

您还可以直接从暂存区或 Git 存储库创建命名版本，而无需经过实时版本。这支持在离线状态下合并更改然后作为新版本导入的工作流程。

实时版本¶

实时版本是代理的可变、可编辑状态。您可以在开发阶段使用它对代理的配置、指令、工具和技能进行迭代。每个代理一次最多只能有一个实时版本。

您可以通过以下方式之一创建实时版本：

通过创建代理创建：创建新代理时，系统会自动创建一个实时版本。
通过上次提交的版本创建：从最近的命名版本恢复实时版本，以便从已知状态继续开发。
通过 |sf-web-interface| UI 创建：UI 可以发起创建新实时版本的请求。

-- Create a live version from the last committed version
ALTER AGENT my_agent ADD LIVE VERSION FROM LAST
  COMMENT = 'Resuming development from v3';

您可以在创建时选择为实时版本分配一个别名：

-- Create a live version with an alias
ALTER AGENT my_agent ADD LIVE VERSION dev FROM LAST;

实时版本专为交互式开发而设计。Snowflake 建议在生产环境中使用之前先提交实时版本，以确保拥有一个不可变的参考点。

命名版本¶

命名版本是提交时代理配置的不可变快照。命名版本一旦创建便无法修改，您只能更新其元数据（注释或别名）或将其彻底删除。这种不可变性使命名版本成为稳定、可复现部署的基础。

Snowflake 为每个命名版本分配一个格式为 VERSION$N 的系统标识符，其中 N 随每次提交递增：

-- Commit the live version to create a named version
ALTER AGENT my_agent COMMIT
  COMMENT = 'Production release for Q1';

这将创建 ``VERSION$2``（或下一个可用编号）。您还可以直接从暂存区或 Git 存储库创建命名版本：

-- Create a named version from a stage
ALTER AGENT my_agent ADD VERSION FROM @my_stage/agents/my_agent
  COMMENT = 'Imported from feature branch';

要查看代理的所有版本，请执行以下操作：

SHOW VERSIONS IN AGENT my_agent;

要删除不再需要的命名版本，请执行以下操作：

ALTER AGENT my_agent DROP VERSION VERSION$1;

备注

您只能删除命名版本。您无法删除实时版本。

别名¶

别名是您分配给版本的易于理解的标签。通过别名，您无需了解系统分配的版本号，即可更轻松地在 API 调用和暂存区操作中引用版本。常见的别名模式包括 production、staging、canary 和 rollback。

您可以为命名版本或实时版本分配别名：

-- Assign an alias to a named version
ALTER AGENT my_agent
  MODIFY VERSION VERSION$3 SET ALIAS = production;

-- Assign an alias to the live version
ALTER AGENT my_agent
  MODIFY LIVE VERSION SET ALIAS = dev;

分配别名后，您可以在任何接受版本标识符的地方使用该别名 – 包括 API 调用、暂存区 URIs 和 SQL 命令。

别名行为：

每个别名在同一个代理中必须是唯一的。
如果使用加双引号的标识符创建别名，则区分大小写；否则，别名将以大写形式存储。
您可以将别名从一个版本重新分配给另一个版本，以便在不更改调用代码的情况下重定向流量。

例如，要将新版本发布到生产环境，请重新分配 production 别名：

-- Point the production alias to the latest version
ALTER AGENT my_agent
  MODIFY VERSION VERSION$4 SET ALIAS = production;

所有指向 production 别名的 API 调用现在都会自动路由到 VERSION$4，无需对调用方应用程序进行任何改动。

版本快捷方式¶

Snowflake 提供了内置快捷方式，让您无需知道确切的版本名称或别名即可引用版本。您可以在 API 端点和暂存区 URIs 中使用这些快捷方式：


快捷键	描述
`LIVE`	当前的实时版本
`FIRST`	第一个提交的命名版本
`LAST`	最近提交的命名版本
`DEFAULT`	设置为代理默认值的版本

快捷方式对于自动化脚本和 CI/CD 管道非常有用，因为这些场景下通常无法提前知道确切的版本号。例如，您始终可以使用 LAST 快捷方式运行最新提交的版本，或者指向代理所有者指定的默认版本。

默认版本¶

除非您另行显式设置，否则 DEFAULT 版本即为最新提交的版本。您还可以将特定版本指定为代理的默认版本。默认版本是指在 API 调用中未指定版本时，代理默认使用的版本：

-- Set the default version
ALTER AGENT my_agent
  SET DEFAULT_VERSION = 'VERSION$3';

您还可以将默认值设置为系统快捷方式，例如 FIRST 或 LAST：

ALTER AGENT my_agent
  SET DEFAULT_VERSION = LAST;

通过设置默认版本，您可以控制哪个版本负责处理流量，而无需调用方在每个请求中都指定版本。当您发布新版本时，更新默认设置即可重定向所有未指定版本的 API 调用。

版本控制与 CI/CD¶

代理版本控制通过支持从外部源（暂存区和 Git 存储库）创建版本，并提供用于环境路由的别名和快捷方式，从而与 CI/CD 工作流程集成。

代理的典型 CI/CD 工作流程遵循以下模式：

开发：在 Snowsight UI 中或通过 SQL 编辑代理的实时版本。进行交互式测试。
提交：当代理准备就绪后，提交实时版本以创建一个不可变的命名版本。
测试：使用系统 ID 或 staging 别名将测试流量路由到新的命名版本。
提升：测试通过后，将 production 别名重新分配给新版本。
回滚：如果出现问题，请将 production 别名重新指向之前的命名版本。

对于在 Git 中管理代理配置的团队，工作流程将转变为导入模式：

开发：在 Git 存储库中编辑代理配置文件。
合并：通过标准的拉取请求流程评审并合并变更。
导入：从与 Git 连接的暂存区直接创建命名版本，完全绕过实时版本。
部署：为导入的版本分配 production 别名。

-- Import a version from a Git-connected stage after a merge
ALTER AGENT my_agent ADD VERSION FROM @my_repo/tags/v2.1/agents/my_agent
  COMMENT = 'Automated deploy from CI pipeline';

作为“基础设施即代码”工作流程的一部分，您还可以直接从暂存区创建新代理：

CREATE AGENT my_agent
  COMMENT = 'Deployed by CI pipeline'
  FROM @my_stage/agents/my_agent;

暂存区操作¶

每个代理版本都有一个内部版本化暂存区路径，您可以通过 snow://agent/ URI 方案进行访问。这让您可以检查构成特定版本的文件，包括代理规范、技能定义和辅助脚本。

URI 格式为：

snow://agent/<agent_name>/versions/<version>/[<file_name>]

<version> 分段接受系统版本 ID (VERSION$N)、用户定义的别名或关键字 live。

-- List all files in the production version
LIST snow://agent/my_agent/versions/production/;

-- Download the agent spec from a specific version
GET snow://agent/my_agent/versions/VERSION$2/agent.yaml file:///tmp/;

暂存区操作为只读，适用于审计、调试和版本比较。

运行特定版本¶

您可以使用版本化的 API 端点向代理的特定版本发送请求：

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}/versions/{version}:run

{version} 路径参数可以接受以下任一内容：


标识符类型	示例
系统版本名称	`VERSION$2`
用户定义的别名	`production`
快捷键	`FIRST`、`LAST`、`DEFAULT`、`LIVE`

默认情况下，API 会以服务器发送事件 (SSE) 的形式流式传输响应。要接收单个 JSON 响应，请在请求正文中将 stream 设置为 false。

限制¶

以下限制适用于 Cortex Agent 版本控制：

单一实时版本：每个代理一次最多只能有一个实时版本。
实时版本不会自动创建：在提交实时版本后，系统不会自动创建新的实时版本。您必须显式创建一个。
命名版本不可变：您无法修改命名版本的配置。您只能更新元数据（注释、别名）或将其删除。
仅限删除命名版本：您可以删除命名版本，但无法删除实时版本。
别名唯一性：每个别名在同一个代理中必须是唯一的。将已分配给其他版本的别名重复分配会导致错误。
区分大小写：使用加双引号的标识符创建别名时区分大小写；否则，别名将以大写形式存储。