Gérer les révisions de compétences

Dans Agent Registry, une révision de compétence représente un instantané immuable et versionné d'un package de compétences. Lorsque vous mettez à jour le code ou les instructions d'une skill, vous créez une révision. Cette architecture découplée permet de contrôler les versions de vos skills.

Ce document explique comment créer et gérer des révisions de skills. Pour savoir comment mettre à jour la révision par défaut d'une compétence spécifique, consultez Mettre à jour les métadonnées ou la révision par défaut d'une compétence.

Avant de commencer

Avant de commencer, configurez Agent Registry et enregistrez une compétence autonome. Vous avez besoin de l'ID du projet pour effectuer ces tâches.

Pour utiliser les commandes Google Cloud CLI de ce document, assurez-vous d'avoir configuré votre environnement gcloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les révisions de compétences dans le Registre d'agents, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

D'autres rôles de l'Agent Registry peuvent également inclure les autorisations requises pour afficher, télécharger, créer, modifier et supprimer des révisions de compétences. Pour en savoir plus, consultez Rôles et autorisations du registre d'agents.

Créer une révision de compétence

La création d'une révision consiste à importer une nouvelle charge utile ZIP dans le conteneur de compétences existant. Lorsque vous créez une révision de compétence, elle devient automatiquement la version active de la compétence. Toutefois, vous pouvez modifier la révision par défaut d'une skill à tout moment. Seules les révisions actives peuvent être téléchargées.

Pour en savoir plus sur les tarifs et les coûts des fonctionnalités pour les compétences, consultez Tarifs du Registre d'agents.

La taille maximale du fichier ZIP d'une révision de skill est de 500 Ko.

Console

  1. Dans la console Google Cloud , accédez à la page Registre d'agents :

    Accéder au registre d'agents

  2. Sélectionnez l'onglet Compétences, puis cliquez sur le nom de votre compétence.
  3. Sur la page Détails de la compétence, localisez le tableau Historique des versions.
  4. Cliquez sur Ajouter une version.

  5. Dans le panneau Ajouter une version, choisissez l'une des options suivantes :

    • Fichier : importez le package ou le fichier ZIP contenant votre code ou le fichier d'instructions de prompt (SKILL.md). Vous pouvez cliquer sur Parcourir pour trouver votre fichier dans votre environnement local.

    • Bucket : fournissez un URI Cloud Storage (gs://...) contenant un bundle ZIP valide. Vous pouvez cliquer sur Parcourir pour trouver votre fichier dans vos buckets Cloud Storage.

  6. Cliquez sur Créer.

La page Détails de la skill affiche la révision de la skill dans le tableau Historique des versions.

gcloud

Vous pouvez créer une révision de skill en important un fichier ZIP local ou un package stocké dans Cloud Storage.

Remplacez les éléments suivants :

  • REVISION_ID : ID que vous souhaitez attribuer à la révision de skill.
  • SKILL_ID : ID de la compétence que vous utilisez pour la révision.
  • PROJECT_ID : ID du projet.

  • LOCATION : emplacement du registre.

  • Importer un fichier ZIP local : pour créer une révision de skill à l'aide d'une charge utile ZIP locale :

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --payload="LOCAL_ZIP_PATH"

    Remplacez LOCAL_ZIP_PATH par le chemin d'accès à l'archive de votre skill packagée sur votre ordinateur local.

  • Importer depuis un bucket Cloud Storage : pour créer une révision de skill à l'aide d'une archive ZIP hébergée dans un bucket Cloud Storage :

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    Remplacez les éléments suivants :

    • BUCKET_NAME : nom du bucket Cloud Storage contenant le bundle ZIP.
    • SKILL_PACKAGE : nom du package de compétences contenant la révision de la compétence.

REST

Pour créer une révision de compétence, envoyez une requête POST à la collection de révisions. Vous pouvez importer directement la charge utile ZIP ou indiquer un chemin Cloud Storage.

  • Importer un fichier ZIP local : spécifiez archiveUploadSource contenant les octets ZIP encodés en base64 dans le corps de la requête. Vous pouvez utiliser la commande base64 intégrée dans curl :

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "archiveUploadSource": {
          "archiveContent": "$(base64 -w0 local_skill.zip)"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • Importer depuis un bucket Cloud Storage : spécifiez gcsSource dans le corps de la requête en pointant vers le chemin d'accès à votre bucket :

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.
  • SKILL_ID : ID du conteneur de compétences.
  • REVISION_ID : ID que vous souhaitez attribuer à cette révision.
  • BUCKET_NAME : nom du bucket Cloud Storage contenant le fichier ZIP.
  • SKILL_PACKAGE : nom du package ZIP.

Lister et décrire les révisions

Vous pouvez afficher la liste de toutes les révisions d'une compétence et examiner leurs métadonnées. Si vous souhaitez mettre à jour la révision par défaut d'une compétence, consultez Mettre à jour les métadonnées ou la révision par défaut d'une compétence.

Pour lister et afficher les détails d'une révision, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Registre d'agents :

    Accéder au registre d'agents

  2. Sélectionnez l'onglet Compétences, puis cliquez sur le nom de votre compétence.
  3. Sur la page Détails de la compétence, localisez le tableau Historique des versions.
  4. Consultez les ID de version, la date de création, l'état de la révision et les actions disponibles.

gcloud

Pour lister toutes les révisions d'une compétence :

gcloud alpha agent-registry skills revisions list \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

Pour décrire les métadonnées d'une révision spécifique :

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST

Pour lister les révisions :

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

Pour obtenir les métadonnées d'une seule révision :

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Télécharger la charge utile de révision

Vous pouvez télécharger le fichier ZIP compilé d'une révision spécifique pour la vérification ou le débogage en local.

Pour télécharger la charge utile, les deux conditions suivantes doivent être remplies :

Pour télécharger le payload de révision d'une révision active, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Registre d'agents :

    Accéder au registre d'agents

  2. Sélectionnez l'onglet Compétences, puis cliquez sur le nom de votre compétence.
  3. Sur la page Détails de la compétence, localisez le tableau Historique des versions.
  4. Recherchez la révision que vous souhaitez télécharger.
  5. Dans la colonne "Actions", cliquez sur Télécharger. La charge utile ZIP est téléchargée sur votre ordinateur local.

gcloud

Pour télécharger la charge utile d'archive d'une révision, exécutez la commande describe avec l'option --alt=media et redirigez le résultat vers un fichier :

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

Envoyez une requête GET à l'URL de la ressource de la révision en ajoutant le paramètre de requête alt=media. Vous devez utiliser l'indicateur -L avec curl pour suivre les flux de redirection HTTP :

curl -L -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -o skill_payload.zip \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

Supprimer une révision spécifique

La suppression d'une révision spécifique supprime sa charge utile ZIP et l'historique des métadonnées d'Agent Registry.

La suppression de révisions individuelles est généralement réservée aux administrateurs. Vous ne pouvez pas supprimer une révision définie comme révision par défaut de la skill. Pour mettre à jour la révision par défaut d'une compétence, consultez Mettre à jour les métadonnées ou la révision par défaut d'une compétence.

Pour supprimer une révision spécifique, procédez comme suit :

Console

  1. Dans la console Google Cloud , accédez à la page Registre d'agents :

    Accéder au registre d'agents

  2. Sélectionnez l'onglet Compétences, puis cliquez sur le nom de votre compétence.
  3. Sur la page Détails de la compétence, localisez le tableau Historique des versions.
  4. Recherchez la révision que vous souhaitez supprimer.
  5. Dans la colonne "Actions", cliquez sur Supprimer, puis confirmez l'action.

gcloud 

gcloud alpha agent-registry skills revisions delete REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST 

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Étapes suivantes