Gestire le revisioni delle skill

In Agent Registry, una revisione della skill rappresenta uno snapshot con controllo delle versioni e immutabile di un pacchetto di skill. Quando aggiorni il codice o le istruzioni di una skill, crei una nuova revisione. Questa architettura disaccoppiata consente il controllo delle versioni delle tue skill.

Questo documento spiega come creare e gestire le revisioni delle skill. Per informazioni sull'aggiornamento della revisione predefinita di una skill specifica, consulta Aggiornare i metadati della skill o la revisione predefinita.

Prima di iniziare

Prima di iniziare, configura Agent Registry e registra una skill autonoma. Per eseguire queste attività, devi avere l'ID progetto.

Per utilizzare i comandi Google Cloud CLI in questo documento, assicurati di aver configurato 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 il ruolo IAM Utente di Agent Registry (roles/agentregistry.user) nel progetto. 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.

Creare una revisione della skill

La creazione di una nuova revisione carica un nuovo payload ZIP nel container di skill esistente. Quando crei una revisione della skill, questa diventa automaticamente la versione attiva della skill. Tuttavia, puoi aggiornare la revisione predefinita di una skill in qualsiasi momento. È possibile scaricare solo le revisioni attive che sono scaricate.

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

Console

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

    Vai ad Agent Registry

  2. Seleziona la scheda Skill e fai clic sul nome della 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 codice o il file di istruzioni del prompt (SKILL.md). Puoi fare clic su Sfoglia per trovare il file nel tuo ambiente locale.

    • Bucket:fornisci un URI Cloud Storage (gs://...) contenente un pacchetto 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 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.
  • PROJECT_ID: l'ID progetto.

  • LOCATION: la località del registro.

  • Caricare un file ZIP locale: per creare una revisione della skill utilizzando un payload ZIP locale:

    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 della skill in pacchetto sul computer locale.

  • Importare da un bucket Cloud Storage: per creare una revisione della skill utilizzando un archivio ZIP ospitato in 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"

    Sostituisci quanto segue:

    • BUCKET_NAME: il nome del bucket Cloud Storage che contiene il pacchetto ZIP.
    • SKILL_PACKAGE: il nome del pacchetto di skill contenente la revisione della skill.

REST

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

  • Caricare un file ZIP locale: specifica archiveUploadSource contenente i byte ZIP con codifica base64 nel corpo della richiesta. Puoi utilizzare il comando base64 inline 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"

  • Importare da un bucket Cloud Storage: specifica gcsSource nel corpo della richiesta che punta 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 registro.
  • SKILL_ID: l'ID del container di 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.

Elencare e descrivere le revisioni

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

Per elencare e visualizzare i dettagli di una revisione:

Console

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

    Vai ad Agent Registry

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

gcloud

Per elencare tutte le revisioni di una skill:

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

Per descrivere i metadati di una revisione specifica:

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

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 di 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"

Scaricare il payload della revisione

Puoi scaricare il payload del file ZIP compilato 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 della revisione di una revisione attiva:

Console

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

    Vai ad Agent Registry

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

gcloud

Per scaricare il payload dell'archivio di una revisione, esegui il comando describe con il flag --alt=media e reindirizza l'output a un file:

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

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"

Eliminare una revisione specifica

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

L'eliminazione delle singole revisioni è in genere limitata agli amministratori. Non puoi eliminare una revisione impostata come revisione predefinita della skill. Per aggiornare la revisione predefinita di una skill, consulta Aggiornare i metadati della skill o la revisione predefinita.

Per eliminare una revisione specifica:

Console

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

    Vai ad Agent Registry

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

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"

Passaggi successivi