Controle de versão do Cortex Agent¶

Como funciona o controle de versão do agente¶

O ciclo de vida da versão de um agente segue um modelo baseado em confirmação:

1. Quando você cria um agente, ele cria automaticamente uma VERSION$1 confirmada e uma versão LIVE com a mesma especificação.

2. Você cria ou modifica a versão ativa do agente durante o desenvolvimento.

3. Quando o agente estiver pronto para implantação, você confirma a versão ativa. O Snowflake cria uma versão nomeada com um identificador atribuído pelo sistema no formato VERSION$N (por exemplo, VERSION$2, VERSION$3).

4. Você atribui um alias ou define a versão nomeada como padrão.

5. As solicitações de interação buscam a versão nomeada, por nome, alias ou atalho, para um comportamento estável e repetível.

Após uma confirmação, a versão ativa não será recriada automaticamente. Você cria explicitamente uma nova versão ativa quando está pronto para retomar o desenvolvimento.

Você também pode criar versões nomeadas diretamente de uma área de preparação ou um repositório Git sem passar pela versão ativa. Isso oferece suporte a fluxos de trabalho em que as alterações são mescladas offline e depois importadas como uma nova versão.

Versões ativas¶

A versão ativa é o estado mutável e editável de um agente. Você a utiliza durante o desenvolvimento para iterar na configuração, nas instruções, nas ferramentas e nas habilidades do agente. Cada agente pode ter no máximo uma versão ativa de cada vez.

Você cria uma versão ativa de uma das seguintes maneiras:

• Na criação do agente: ao criar um novo agente, uma versão ativa é criada automaticamente.

• A partir da última versão confirmada: restaure a versão ativa a partir da versão nomeada mais recente para continuar o desenvolvimento de um estado conhecido.

• Na UI do |sf-web-interface|: a UI pode emitir a criação de uma nova versão ativa.

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

Você pode atribuir um alias à versão ativa no momento da criação:

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

A versão ativa foi projetada para desenvolvimento interativo. A Snowflake recomenda confirmar a versão ativa antes de usá-la em produção para garantir que você tenha um ponto de referência imutável.

Versões nomeadas¶

Uma versão nomeada é um instantâneo imutável da configuração do agente no momento da confirmação. Depois de criada, uma versão nomeada não pode ser modificada. Você só pode atualizar seus metadados (comentário ou alias) ou descartá-las completamente. Essa imutabilidade torna as versões nomeadas a base para implantações estáveis e reproduzíveis.

O Snowflake atribui a cada versão nomeada um identificador do sistema no formato VERSION$N, em que N aumenta a cada confirmação:

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

Isso cria VERSION$2 (ou o próximo número disponível). Você também pode criar versões nomeadas diretamente de uma área de preparação ou um repositório 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';

Para visualizar todas as versões em um agente:

SHOW VERSIONS IN AGENT my_agent;

Para remover uma versão nomeada que você não precisa mais:

ALTER AGENT my_agent DROP VERSION VERSION$1;

Aliases¶

Alias é um rótulo legível por humanos que você atribui a uma versão. Os aliases facilitam a referência a versões nas chamadas de API e as operações de preparação, sem saber o número da versão atribuída pelo sistema. Os padrões de alias comuns incluem production, staging, canary e rollback.

Você atribui um alias a uma versão nomeada ou à versão ativa:

-- 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;

Depois que ele for atribuído, você poderá usá-lo em qualquer lugar em que um identificador de versão seja aceito: chamadas de API, URIs de áreas de preparação e comandos SQL.

Comportamento do alias:

• Cada alias deve ser exclusivo em um agente.

• Os aliases diferenciam maiúsculas de minúsculas se forem criados com identificadores entre aspas duplas; caso contrário, serão armazenados em letras maiúsculas.

• Você pode reatribuir um alias de uma versão para outra para redirecionar o tráfego sem alterar o código de chamada.

Por exemplo, para promover uma nova versão à produção, reatribua o alias production:

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

Todas as chamadas de API que buscam o alias production agora fazem o roteamento para VERSION$4 sem nenhuma alteração no aplicativo de chamada.

Atalhos de versão¶

O Snowflake oferece atalhos internos para referenciar versões sem saber o nome exato ou alias da versão. Você pode usar os atalhos no ponto de extremidade da API e nas URIs das áreas de preparação:

Os atalhos são úteis para scripts de automação e pipelines de CI/CD, em que não se sabe o número exato da versão. Por exemplo, você sempre pode executar a última versão confirmada com o atalho LAST ou buscar a versão que o proprietário do agente designou como padrão.

Versão padrão¶

A menos que você a defina explicitamente, a versão DEFAULT é a última versão confirmada. Você também pode designar uma versão como padrão para o agente. A versão padrão é aquela que o agente usa quando nenhuma versão é especificada em uma chamada de API:

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

Você também pode definir o padrão como um atalho do sistema, por exemplo, FIRST ou LAST:

ALTER AGENT my_agent
  SET DEFAULT_VERSION = LAST;

A definição de uma versão padrão permite controlar qual versão processa o tráfego sem exigir que os autores da chamada especifiquem uma versão em cada solicitação. Ao promover uma nova versão, atualize o padrão para redirecionar todas as chamadas de API sem controle de versão.

Controle de versão e CI/CD¶

O controle de versão do agente integra-se aos fluxos de trabalho de CI/CD, oferecendo suporte à criação de versões de fontes externas, áreas de preparação e repositórios Git, e fornecendo aliases e atalhos para roteamento do ambiente.

Um fluxo de trabalho de CI /CD comum nos agentes segue este padrão:

1. Desenvolver: edite a versão ativa do agente na UI do Snowsight ou por meio de SQL. Faça um teste interativo.

2. Confirmar: quando o agente estiver pronto, confirme a versão ativa para criar uma versão nomeada imutável.

3. Testar: roteie o tráfego de teste para a nova versão nomeada usando o ID do sistema ou um alias staging.

4. Promover: reatribua o alias production para a nova versão assim que o teste for aprovado.

5. Reversão: se surgirem problemas, reatribua o alias production para a versão nomeada anterior.

Para as equipes que gerenciam as configurações do agente no Git, o fluxo de trabalho muda para um modelo de importação:

1. Desenvolver: edite os arquivos de configuração do agente em um repositório Git.

2. Mesclar: revise e mescle as alterações por meio do seu processo padrão de solicitação de pull.

3. Importar: crie uma versão nomeada da área de preparação conectada ao Git, ignorando completamente a versão ativa.

4. Implantar: atribua o alias production para a versão importada.

-- 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';

Você também pode criar um novo agente diretamente de uma área de preparação como parte de um fluxo de trabalho de infraestrutura como código:

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

Operações de preparação¶

Cada versão do agente tem um caminho de área de preparação interno com controle de versão que você pode acessar por meio do esquema de URI snow://agent/. Isso permite que você inspecione os arquivos que compõem uma versão, incluindo a especificação, as definições de habilidades e os scripts de suporte do agente.

O formato do URI é:

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

O segmento <version> aceita um ID de versão do sistema (VERSION$N), um alias definido pelo usuário ou a palavra-chave 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/;

As operações de preparação são somente leitura e úteis para auditoria, depuração e comparação de versões.

Executar uma versão específica¶

Você pode enviar uma solicitação para uma versão específica de um agente usando o ponto de extremidade da API com controle de versão:

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

O parâmetro de caminho {version} aceita qualquer um dos seguintes valores:

Por padrão, a API transmite respostas como eventos enviados pelo servidor (SSE). Para receber uma resposta JSON única, defina stream como false no corpo da solicitação.

Limitações¶

As seguintes limitações se aplicam ao controle de versão do Cortex Agent:

• Uma versão ativa: Cada agente pode ter no máximo uma versão ativa de cada vez.

• Versão ativa não criada automaticamente: depois que você confirma a versão ativa, uma nova versão ativa não será criada automaticamente. Você deverá criar uma explicitamente.

• As versões nomeadas são imutáveis: não é possível modificar a configuração de uma versão nomeada. Você só pode atualizar metadados (comentário, alias) ou descartá-la.

• Descartar somente nomeadas: você pode descartar versões nomeadas, mas não a versão ativa.

• Exclusividade do alias: Cada alias deve ser exclusivo em um agente. A atribuição de um alias que já existe em outra versão resulta em erro.

• Diferenciação entre maiúsculas e minúsculas: os aliases diferenciam maiúsculas de minúsculas quando criados com identificadores entre aspas duplas; caso contrário, serão armazenados em letras maiúsculas.