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 Aggiorna i metadati o la revisione predefinita di una skill.

Prima di iniziare

Prima di iniziare, configura Agent Registry e registra una skill autonoma. Per eseguire queste attività, devi disporre dell'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 i seguenti ruoli IAM sul 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.

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

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 di una 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.

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 è 500 KB.

Console

  1. Nella console Google Cloud , vai alla pagina Registro degli agenti:

    Vai a 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 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 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 dell'abilità.
  • SKILL_ID: l'ID della competenza che utilizzi per la revisione.
  • PROJECT_ID: l'ID progetto.

  • LOCATION: la posizione del registro.

  • Carica 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 pacchettizzata sulla tua macchina locale.

  • Importa 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 bundle 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 delle revisioni. Puoi caricare il payload ZIP direttamente o indicare un percorso Cloud Storage.

  • Carica un file ZIP locale: specifica archiveUploadSource contenente i byte ZIP con codifica 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 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 posizione del registro.
  • SKILL_ID: l'ID del contenitore di skill.
  • REVISION_ID: l'ID che vuoi assegnare a questa revisione.
  • BUCKET_NAME: il nome del bucket Cloud Storage che contiene il file ZIP.
  • SKILL_PACKAGE: il nome del pacchetto ZIP.

Elenca e descrivi le revisioni

Puoi visualizzare l'elenco di tutte le revisioni di un'abilità ed esaminarne 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 Registro degli agenti:

    Vai a 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, la data e l'ora di creazione, lo stato della revisione e le azioni disponibili.

gcloud

Per elencare tutte le revisioni di un'abilità:

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"

Scarica 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 console Google Cloud , vai alla pagina Registro degli agenti:

    Vai a 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 delle azioni, fai clic su Scarica. Il payload ZIP viene scaricato nella tua macchina 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 i flussi 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 relativo 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 dell'abilità. Per aggiornare la revisione predefinita di una skill, consulta Aggiorna i metadati o la revisione predefinita della skill.

Per eliminare una revisione specifica:

Console

  1. Nella console Google Cloud , vai alla pagina Registro degli agenti:

    Vai a 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 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