Gestion des versions Cortex Agent¶

Comment fonctionne la gestion des versions d’agent¶

Le cycle de vie d’une version d’agent suit un modèle basé sur les validations :

1. Lorsque vous créez un agent, il crée automatiquement une VERSION$1 validée et une version LIVE avec les mêmes spécifications.

2. Vous créez ou modifiez la version en production de l’agent au cours du développement.

3. Lorsque l’agent est prêt pour le déploiement, vous validez la version en production. Snowflake crée une version nommée avec un identificateur attribué par le système au format VERSION$N (par exemple, VERSION$2, VERSION$3).

4. Vous attribuez un alias ou définissez la version nommée par défaut.

5. Les demandes d’interaction ciblent la version nommée, soit par nom, soit par alias, soit par raccourci, pour un comportement stable et reproductible.

Après une validation, la version en production n’est pas automatiquement recréée. Vous créez explicitement une nouvelle version en production lorsque vous êtes prêt à reprendre le développement.

Vous pouvez également créer des versions nommées directement à partir d’une zone de préparation ou d’un référentiel Git sans passer par la version en production. Cette méthode prend en charge les workflows où les modifications sont fusionnées hors ligne, puis importées sous forme de nouvelle version.

Versions en production¶

La version en production correspond à l’état modifiable et évolutif d’un agent. Vous l’utilisez pendant le développement pour effectuer des itérations sur la configuration, les instructions, les outils et les compétences de l’agent. Chaque agent peut avoir au maximum une version en production à la fois.

Pour créer une version en production, utilisez l’une des méthodes suivantes :

• Depuis la création de l’agent : Lorsque vous créez un nouvel agent, une version en production est automatiquement créée.

• Depuis la dernière version validée : Restaurez la version en production à partir de la version nommée la plus récente pour poursuivre le développement à partir d’un état connu.

• Depuis l’UI |sf-web-interface| : L’UI peut générer la création d’une nouvelle version en production.

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

Vous pouvez éventuellement attribuer un alias à la version en production au moment de la création :

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

La version en production est conçue pour le développement interactif. Snowflake recommande de valider la version en production avant de l’utiliser en production afin de disposer d’un point de référence immuable.

Versions nommées¶

Une version nommée est un instantané immuable de la configuration de l’agent au moment de la validation. Une fois créée, une version nommée ne peut pas être modifiée. Vous pouvez uniquement mettre à jour ses métadonnées (commentaire ou alias), ou la supprimer complètement. Cette immuabilité fait des versions nommées le fondement de déploiements stables et reproductibles.

Snowflake attribue à chaque version nommée un identifiant système au format VERSION$N, où N augmente à chaque validation :

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

Ainsi se crée une VERSION$2 (ou le prochain nombre disponible). Vous pouvez également créer des versions nommées directement à partir d’une zone de préparation ou d’un référentiel 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';

Pour afficher toutes les versions d’un agent :

SHOW VERSIONS IN AGENT my_agent;

Pour supprimer une version nommée dont vous n’avez plus besoin :

ALTER AGENT my_agent DROP VERSION VERSION$1;

Alias¶

Un alias est un identificateur lisible par l’homme que vous attribuez à une version. Les alias permettent de faire référence plus facilement aux versions dans les appels API et les opérations de zone de préparation sans connaître le numéro de version attribué par le système. Les modèles d’alias courants incluent production, staging, canary et rollback.

Vous attribuez un alias à une version nommée ou à la version en production :

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

Une fois attribué, vous pouvez utiliser l’alias partout où un identificateur de version est accepté : dans les appels API, les URIs de zone de préparation et les commandes SQL.

Comportement d’alias :

• Chaque alias doit être unique au sein d’un agent.

• Les alias sont sensibles à la casse s’ils sont créés avec des identificateurs entre guillemets doubles ; sinon, ils sont stockés en majuscules.

• Vous pouvez réattribuer un alias d’une version à l’autre pour rediriger le trafic sans modifier le code d’appel.

Par exemple, pour mettre en production une nouvelle version, réattribuez l’alias production :

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

Tous les appels API destinés à l’alias production sont désormais redirigés vers VERSION$4 sans aucune modification de l’application appelante.

Raccourcis de version¶

Snowflake fournit des raccourcis intégrés pour référencer des versions sans connaître le nom ou l’alias exact de la version. Vous pouvez utiliser ces raccourcis dans les points de terminaison API et les URIs de zones de préparation :

Les raccourcis sont utiles pour les scripts d’automatisation et les pipelines CI/CD où le numéro de version exact n’est pas connu à l’avance. Par exemple, vous pouvez toujours exécuter la dernière version validée avec le raccourci LAST ou cibler la version que le propriétaire de l’agent a désignée comme la version par défaut.

Version par défaut¶

À moins que vous ne la définissiez explicitement, la version DEFAULT est la dernière version validée. Vous pouvez également désigner une version par défaut pour l’agent. La version par défaut est la version que l’agent utilise lorsqu’aucune version n’est spécifiée dans un appel API :

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

Vous pouvez également définir la valeur par défaut sur un raccourci système tel que FIRST ou LAST :

ALTER AGENT my_agent
  SET DEFAULT_VERSION = LAST;

La définition d’une version par défaut vous permet de contrôler quelle version sert le trafic sans que les appelants aient à spécifier une version à chaque requête. Lorsque vous mettez en production une nouvelle version, mettez à jour la version par défaut afin de rediriger tous les appels API sans version.

Gestion des versions et CI/CD¶

La gestion des versions de l’agent s’intègre aux workflows CI/CD en prenant en charge la création de versions à partir de sources externes (zones de préparation et référentiels Git) et en proposant des alias et des raccourcis pour le routage des environnements.

Un workflow CI /CD typique pour les agents suit ce schéma :

1. Développer : Modifiez la version en production de l’agent dans l’UI Snowsight ou via SQL. Testez de manière interactive.

2. Valider : Lorsque l’agent est prêt, validez la version en production pour créer une version nommée immuable.

3. Test : Acheminez le trafic de test vers la nouvelle version nommée en utilisant son ID système ou un alias staging.

4. Promouvoir : Réattribuez l’alias production à la nouvelle version une fois le test réussi.

5. Roll back (Retour en arrière) : Si des problèmes surviennent, réattribuez l’alias production de la version nommée précédente.

Pour les équipes qui gèrent les configurations d’agents dans Git, le workflow passe à un modèle d’importation :

1. Développer : Modifiez les fichiers de configuration de l’agent dans un référentiel Git.

2. Fusionner : Examinez et fusionnez les modifications via votre processus standard de demande d’extraction.

3. Importer : Créez une version nommée à partir de la zone de préparation connectée à Git, en contournant complètement la version en production.

4. Déployer : Attribuez l’alias production de la version importée.

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

Vous pouvez également créer un nouvel agent directement à partir d’une zone de préparation dans le cadre d’un workflow d’infrastructure en tant que code :

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

Opérations de zone de préparation¶

Chaque version d’agent dispose d’un chemin de zone de préparation interne versionné auquel vous pouvez accéder via le schéma de l’URI snow://agent/. Cela vous permet d’inspecter les fichiers qui composent une version, y compris la spécification de l’agent, les définitions de fonctionnalités et les scripts de prise en charge.

Le format de l’URI est :

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

Le segment <version> accepte une ID de version système (VERSION$N), un alias défini par l’utilisateur ou le mot-clé 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/;

Les opérations de zone de préparation sont en lecture seule et utiles pour l’audit, le débogage et la comparaison des versions.

Exécuter une version spécifique¶

Vous pouvez envoyer une demande à une version spécifique d’un agent à l’aide du point de terminaison.API versionné :

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

Le paramètre de chemin {version} accepte l’une des valeurs suivantes :

Par défaut, l’API transmet les réponses sous forme d’événements envoyés par le serveur (SSE). Pour recevoir une seule réponse JSON, définissez stream sur false dans le corps de la requête.

Limitations¶

Les limites suivantes s’appliquent à la gestion des versions de Cortex Agent :

• Une version en production : Chaque agent peut avoir au maximum une version en production à la fois.

• Version en production non créée automatiquement : Une fois que vous avez validé la version en production, une nouvelle version en production n’est pas créée automatiquement. Vous devez en créer une explicitement.

• Les versions nommées sont immuables : Vous ne pouvez pas modifier la configuration d’une version nommée. Vous pouvez uniquement mettre à jour les métadonnées (commentaire, alias) ou les supprimer.

• Supprimer des versions nommées uniquement : Vous pouvez supprimer des versions nommées, mais pas la version en production.

• Unicité des alias : Chaque alias doit être unique au sein d’un agent. L’attribution d’un alias déjà existant dans une autre version entraîne une erreur.

• Sensibilité à la casse : Les alias sont sensibles à la casse lorsqu’ils sont créés avec des identificateurs entre guillemets doubles ; sinon, ils sont stockés en majuscules.