Gérer les révisions de compétences

Dans le registre d'agents, les révisions de compétences vous permettent de contrôler les versions de vos compétences autonomes en tant qu'instantanés immuables sans perturber les agents actifs. Chaque compétence possède une révision par défaut et peut contenir plusieurs révisions de compétence avec gestion des versions. Lorsque vous mettez à jour les instructions ou les scripts facultatifs d'une compétence, vous pouvez créer, lister, inspecter, télécharger et supprimer des révisions de compétences dans Agent Registry. Pour en savoir plus sur la mise à jour de 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.

Avant de commencer

  1. Configurer le registre d'agents.

  2. Obtenez l'ID du projet pour le projet de gouvernance dans lequel Agent Registry est activé.

  3. Enregistrer une compétence autonome

  4. Pour utiliser les commandes de la Google Cloud CLI dans ce document, configurez 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 de gouvernance où le registre d'agents est activé :

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 Agent Registry peuvent également inclure les autorisations requises pour afficher, télécharger, créer, mettre à jour et supprimer des révisions de compétences. Pour en savoir plus, consultez Rôles et autorisations Agent Registry.

Créer une révision de compétence

La création d'une révision importe une nouvelle charge utile ZIP dans le conteneur de compétences existant. Une fois la validation réussie, la révision passe à l'état Actif. Pour diffuser la nouvelle révision en tant que révision par défaut de la compétence, mettez à jour la révision par défaut de la compétence pour qu'elle pointe vers la nouvelle révision active. Seules les révisions à l'état Actif peuvent être téléchargées.

Pour en savoir plus sur les tarifs et les coûts des fonctionnalités des compétences, consultez Tarifs d'Agent Registry.

La taille maximale du fichier ZIP d'une révision de compétence 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, accédez au 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 fichier d'instructions SKILL.md et les scripts facultatifs. Vous pouvez cliquer sur Parcourir pour rechercher 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 compétence affiche la révision de la compétence dans le tableau Historique des versions.

gcloud

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

Remplacez les éléments suivants :

  • REVISION_ID : ID que vous souhaitez attribuer à la révision de la compétence.
  • SKILL_ID : ID de la compétence que vous utilisez pour la révision. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • PROJECT_ID : ID du projet.

  • LOCATION : emplacement du registre.

  • Importer un fichier ZIP local : pour créer une révision de compétence à l'aide d'une charge utile ZIP locale, exécutez la commande gcloud alpha agent-registry skills revisions create :

    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 compétence empaquetée sur votre ordinateur local.

  • Importer depuis un bucket Cloud Storage : pour créer une révision de compétence à l'aide d'une archive ZIP hébergée dans un bucket Cloud Storage, exécutez la commande gcloud alpha agent-registry skills revisions create :

    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 la charge utile ZIP directement ou pointer vers un chemin d'accès 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 pointant vers le chemin d'accès de 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. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • 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 inspecter 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, accédez au tableau Historique des versions.
  4. Examinez les ID de version, l'heure de création, l'état de la révision et les actions disponibles.

gcloud

Pour lister toutes les révisions d'une compétence, exécutez la commande gcloud alpha agent-registry skills revisions list :

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, exécutez la commande gcloud alpha agent-registry skills revisions describe :

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

Remplacez les éléments suivants :

  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.
  • REVISION_ID : ID de la révision de la compétence.

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.
  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • REVISION_ID : ID de la révision de la compétence.

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

Vous pouvez télécharger la charge utile du fichier ZIP 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 la charge utile 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, accédez au 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 gcloud alpha agent-registry skills revisions download et spécifiez le chemin de destination :

gcloud alpha agent-registry skills revisions download REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --destination="./skill_payload.zip"

Remplacez les éléments suivants :

  • REVISION_ID : ID de la révision de la compétence à télécharger.
  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.

REST

Envoyez une requête GET à l'URL de ressource de la révision en ajoutant le paramètre de requête alt=media. Vous devez utiliser l'option -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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.
  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • REVISION_ID : ID de la révision de la compétence à télécharger.

Supprimer une révision spécifique

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

La suppression de révisions individuelles est généralement réservée aux administrateurs. Si vous supprimez la révision définie comme révision par défaut de la compétence, Agent Registry efface le pointeur defaultRevision et fait passer une compétence active à l'état désactivé. Pour que la compétence reste active, mettez à jour la révision par défaut de la compétence afin qu'elle pointe vers une autre révision active avant de supprimer la révision par défaut précédente.

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, accédez au 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

Pour supprimer une révision, exécutez la commande gcloud alpha agent-registry skills revisions delete :

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

Remplacez les éléments suivants :

  • REVISION_ID : ID de la révision de compétence à supprimer.
  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.

REST

Pour supprimer une révision, envoyez une requête DELETE :

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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement du registre.
  • SKILL_ID : ID du conteneur de compétences. Pour les compétences enregistrées manuellement, incluez le préfixe private-, par exemple private-my-skill.
  • REVISION_ID : ID de la révision de compétence à supprimer.

Étapes suivantes