Gestire le revisioni delle skill

In Agent Registry, le revisioni delle skill ti consentono di controllare la versione delle tue skill autonome come snapshot immutabili senza interrompere gli agenti attivi. Ogni skill ha una revisione predefinita e può contenere più revisioni delle skill con controllo delle versioni. Quando aggiorni le istruzioni o gli script facoltativi di una skill, puoi creare, elencare, ispezionare, scaricare ed eliminare le revisioni della skill in Agent Registry. Per informazioni sull'aggiornamento della revisione predefinita di una skill, consulta Aggiorna i metadati o la revisione predefinita della skill.

Prima di iniziare

  1. Configura Agent Registry.

  2. Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.

  3. Registra una skill autonoma.

  4. Per utilizzare i comandi di Google Cloud CLI in questo documento, configura l'ambiente gcloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire le revisioni delle skill in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto di governance in cui è abilitato Agent Registry:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Altri ruoli di Agent Registry potrebbero includere anche le autorizzazioni necessarie per visualizzare, scaricare, creare, aggiornare ed eliminare le revisioni delle competenze. Per saperne di più, consulta Ruoli e autorizzazioni di Agent Registry.

Crea una revisione della skill

La creazione di una nuova revisione carica un nuovo payload ZIP nel container di skill esistente. Se la convalida ha esito positivo, la revisione entra nello stato Attiva. Per pubblicare la nuova revisione come revisione predefinita per la skill, aggiorna la revisione predefinita della skill in modo che punti alla nuova revisione attiva. Solo le revisioni in stato Attivo possono essere scaricate.

Per informazioni sui prezzi e sui costi delle funzionalità per le skill, consulta Prezzi di Agent Registry.

La dimensione massima del file ZIP di una revisione della skill è di 500 KB.

Console

  1. Nella console Google Cloud , vai alla pagina Agent Registry:

    Vai ad Agent Registry

  2. Seleziona la scheda Skill e fai clic sul nome della tua skill.
  3. Nella pagina Dettagli skill, individua la tabella Cronologia delle versioni.
  4. Fai clic su Aggiungi versione.

  5. Nel riquadro Aggiungi versione, scegli una delle seguenti opzioni:

    • File: carica il pacchetto o il file ZIP contenente il file di istruzioni SKILL.md e gli script facoltativi. Puoi fare clic su Sfoglia per trovare il file nel tuo ambiente locale.

    • Bucket: fornisci un URI Cloud Storage gs://... contenente un bundle ZIP valido. Puoi fare clic su Sfoglia per trovare il file nei bucket Cloud Storage.

  6. Fai clic su Crea.

La pagina Dettagli skill mostra la revisione della skill nella tabella Cronologia delle versioni.

gcloud

Puoi creare una revisione della skill caricando un file ZIP locale o importando un pacchetto archiviato in Cloud Storage.

Sostituisci quanto segue:

  • REVISION_ID: l'ID che vuoi assegnare alla revisione della skill.
  • SKILL_ID: l'ID della skill che stai utilizzando per la revisione. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto

  • LOCATION: la località del registry.

  • Carica un file ZIP locale: per creare una revisione della skill utilizzando un payload ZIP locale, esegui il comando 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"

    Sostituisci LOCAL_ZIP_PATH con il percorso dell'archivio delle skill pacchettizzate sulla tua macchina locale.

  • Importa da un bucket Cloud Storage: per creare una revisione della skill utilizzando un file ZIP ospitato in un bucket Cloud Storage, esegui il comando 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"

    Sostituisci quanto segue:

    • BUCKET_NAME: il nome del bucket Cloud Storage che contiene il bundle ZIP.
    • SKILL_PACKAGE: il nome del pacchetto di competenze contenente la revisione delle competenze.

REST

Per creare una revisione della skill, invia una richiesta POST alla raccolta delle revisioni. Puoi caricare direttamente il payload ZIP o puntare a un percorso di Cloud Storage.

  • Carica un file ZIP locale: specifica archiveUploadSource contenente i byte ZIP codificati in base64 nel corpo della richiesta. Puoi utilizzare il comando base64 incorporato in 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"

  • Importa da un bucket Cloud Storage: specifica gcsSource nel corpo della richiesta che rimanda al percorso del 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • REVISION_ID: l'ID che vuoi assegnare a questa revisione.
  • BUCKET_NAME: il nome del bucket Cloud Storage contenente il file ZIP.
  • SKILL_PACKAGE: il nome del pacchetto ZIP.

Elenca e descrivi le revisioni

Puoi visualizzare l'elenco di tutte le revisioni di una skill e ispezionarne i metadati. Se vuoi aggiornare la revisione predefinita di una skill, consulta Aggiorna i metadati o la revisione predefinita della skill.

Per elencare e visualizzare i dettagli di una revisione, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Agent Registry:

    Vai ad Agent Registry

  2. Seleziona la scheda Skill e fai clic sul nome della tua skill.
  3. Nella pagina Dettagli skill, individua la tabella Cronologia delle versioni.
  4. Esamina gli ID versione, l'ora di creazione, lo stato della revisione e le azioni disponibili.

gcloud

Per elencare tutte le revisioni di una skill, esegui il comando gcloud alpha agent-registry skills revisions list:

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

Per descrivere i metadati di una revisione specifica, esegui il comando gcloud alpha agent-registry skills revisions describe:

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

Sostituisci quanto segue:

  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • REVISION_ID: l'ID della revisione della skill.

REST

Per elencare le revisioni:

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"

Per ottenere i metadati per una singola revisione:

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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • REVISION_ID: l'ID della revisione della skill.

Scarica il payload della revisione

Puoi scaricare il payload del file ZIP di una revisione specifica per la verifica o il debug locale.

Per scaricare il payload, devono essere soddisfatte entrambe le seguenti condizioni:

Per scaricare il payload di una revisione attiva, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Agent Registry:

    Vai ad Agent Registry

  2. Seleziona la scheda Skill e fai clic sul nome della tua skill.
  3. Nella pagina Dettagli skill, individua la tabella Cronologia delle versioni.
  4. Trova la revisione che vuoi scaricare.
  5. Nella colonna Azioni, fai clic su Scarica. Il payload ZIP viene scaricato sulla tua macchina locale.

gcloud

Per scaricare il payload dell'archivio di una revisione, esegui il comando gcloud alpha agent-registry skills revisions download e specifica il percorso di destinazione:

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

Sostituisci quanto segue:

  • REVISION_ID: l'ID della revisione della skill da scaricare.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.

REST

Invia una richiesta GET all'URL della risorsa della revisione aggiungendo il parametro di query alt=media. Devi utilizzare il flag -L con curl per seguire gli stream di reindirizzamento 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • REVISION_ID: l'ID della revisione della skill da scaricare.

Elimina una revisione specifica

L'eliminazione di una revisione specifica rimuove il payload ZIP e la cronologia dei metadati da Agent Registry.

L'eliminazione di singole revisioni è in genere limitata agli amministratori. Se elimini la revisione impostata come predefinita per la skill, Agent Registry cancella il puntatore defaultRevision e passa una skill Attiva allo stato Disattivata. Per mantenere attiva la skill, aggiorna la revisione predefinita della skill in modo che rimandi a un'altra revisione attiva prima di eliminare la revisione predefinita precedente.

Per eliminare una revisione specifica, segui questi passaggi:

Console

  1. Nella console Google Cloud , vai alla pagina Agent Registry:

    Vai ad Agent Registry

  2. Seleziona la scheda Skill e fai clic sul nome della tua skill.
  3. Nella pagina Dettagli skill, individua la tabella Cronologia delle versioni.
  4. Trova la revisione che vuoi eliminare.
  5. Nella colonna Azioni, fai clic su Elimina e conferma l'azione.

gcloud

Per eliminare una revisione, esegui il comando gcloud alpha agent-registry skills revisions delete:

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

Sostituisci quanto segue:

  • REVISION_ID: l'ID della revisione della skill da eliminare.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.

REST

Per eliminare una revisione, invia una richiesta 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID del container di competenze. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • REVISION_ID: l'ID della revisione della skill da eliminare.

Passaggi successivi