Gestire le competenze

Il registro degli agenti ti consente di ispezionare, aggiornare e gestire le skill autonome in modo da poter controllare quali versioni e stati del ciclo di vita delle skill sono disponibili per i tuoi agenti. Dopo aver registrato una skill autonoma, puoi visualizzarne i dettagli, aggiornarne la descrizione o la revisione predefinita, modificarne lo stato del ciclo di vita o eliminarla da Agent Registry. Puoi anche elencare e visualizzare le skill gestite da Google, che sono disponibili non appena configuri Agent Registry.

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 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, aggiornare ed eliminare le skill. Per saperne di più, consulta Ruoli e autorizzazioni di Agent Registry.

Elenca e visualizza le skill

Puoi sfogliare tutte le skill registrate o cercare funzionalità specifiche:

Console

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

    Vai ad Agent Registry

  2. Seleziona la scheda Competenze.
  3. Esamina l'elenco delle skill. Puoi filtrare la visualizzazione utilizzando i menu Località o Stato.
  4. Fai clic sul nome di una skill per aprire la relativa pagina Dettagli skill, che mostra il nome, la descrizione, la versione attiva, l'identificatore della skill, l'ultimo aggiornamento, i metadati personalizzati e la cronologia delle revisioni.

gcloud

Per elencare tutte le competenze in una località, utilizza il comando gcloud alpha agent-registry skills list:

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

Per visualizzare i dettagli di una competenza specifica, utilizza il comando gcloud alpha agent-registry skills describe:

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

Sostituisci quanto segue:

  • SKILL_ID: l'ID della skill che vuoi esaminare. 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 recuperare l'elenco di tutte le competenze, invia una richiesta GET:

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

Per recuperare un singolo container di skill, invia una richiesta GET:

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

Sostituisci quanto segue:

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

Aggiorna i metadati della skill o la revisione predefinita

Puoi modificare il nome visualizzato o la descrizione di una skill oppure modificare manualmente il puntatore della revisione predefinita per eseguire il deployment di una versione diversa. Per creare nuove revisioni delle skill, consulta Gestisci le revisioni delle skill.

Per aggiornare i metadati della skill o la revisione predefinita di una determinata skill, segui questi passaggi:

Console

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

    Vai ad Agent Registry

  2. Seleziona la scheda Competenze.
  3. Esamina l'elenco delle skill. Puoi filtrare la visualizzazione utilizzando i menu Località o Stato.
  4. Fai clic sul nome di una skill per aprire la relativa pagina Dettagli skill, che mostra il nome, la descrizione, la versione attiva, l'identificatore della skill, l'ultimo aggiornamento, i metadati personalizzati e la cronologia delle revisioni.

  5. Scegli tra le seguenti opzioni:

    • Aggiorna i metadati della skill:

      1. Fai clic su Modifica.
      2. Nel riquadro Modifica skill, aggiorna il nome visualizzato o la descrizione della skill.
      3. Fai clic su Salva.

    • Aggiorna la revisione predefinita:

      1. Individua la tabella Cronologia delle versioni.
      2. Trova la revisione che vuoi impostare come attiva.
      3. Nella colonna Azioni, fai clic su Attiva versione.

gcloud

  • Per aggiornare i metadati di una skill, utilizza il comando gcloud alpha agent-registry skills update:

    gcloud alpha agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION"

  • Per aggiornare la revisione di pubblicazione predefinita di una skill, utilizza il comando gcloud alpha agent-registry skills update e specifica il nome della risorsa della revisione di destinazione:

    gcloud alpha agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Sostituisci quanto segue:

  • SKILL_ID: l'ID della skill che vuoi aggiornare. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • DISPLAY_NAME: il nome visualizzato aggiornato.
  • DESCRIPTION: la descrizione aggiornata.
  • REVISION_ID: l'ID della revisione della skill che vuoi impostare come predefinita.

REST

Invia una richiesta PATCH specificando i campi che vuoi aggiornare:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

Sostituisci quanto segue:

  • DISPLAY_NAME: il nome visualizzato aggiornato della skill.
  • DESCRIPTION: la descrizione aggiornata della competenza.
  • PROJECT_ID: l'ID progetto
  • LOCATION: la località del registry.
  • SKILL_ID: l'ID della skill che vuoi aggiornare. Per le competenze registrate manualmente, includi il prefisso private-, ad esempio private-my-skill.
  • REVISION_ID: l'ID della revisione della skill che vuoi attivare.

Gestisci gli stati del ciclo di vita delle skill

Per controllare il modo in cui una skill viene risolta in fase di runtime, puoi modificare lo stato target della skill:

  • Attiva: la skill viene pubblicata ed è completamente risolvibile. Per impostare una skill su Attiva, il campo defaultRevision deve puntare a una revisione della skill attiva.
  • Disattivata: lo stato iniziale predefinito quando viene creata una skill. La skill non viene pubblicata in fase di runtime, la risoluzione della skill non va a buon fine immediatamente e i download del payload vengono bloccati. Una skill viene impostata sullo stato Disabilitata anche se il relativo puntatore defaultRevision viene cancellato o se la revisione predefinita viene eliminata. A differenza dello stato Ritirata, puoi attivare una skill disattivata impostando un valore defaultRevision valido e aggiornando lo stato di destinazione su Attiva.
  • Ritirata: la skill rimane caricabile e scaricabile, ma indica che verrà dismessa.
  • Ritirata: la skill è disattivata definitivamente, non viene più pubblicata e non può essere ripristinata allo stato Attiva o a qualsiasi altro stato. Una skill può essere ritirata solo dopo essere stata ritirata. Concedi un tempo sufficiente per la migrazione prima di ritirare la skill. Poiché questo stato è terminale, utilizzalo con cautela.

Per modificare lo stato del ciclo di vita di una skill:

Console

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

    Vai ad Agent Registry

  2. Seleziona la scheda Competenze.
  3. Esamina l'elenco delle skill. Puoi filtrare la visualizzazione utilizzando i menu Località o Stato.
  4. Fai clic sul nome di una skill per aprire la relativa pagina Dettagli skill, che mostra il nome, la descrizione, la versione attiva, l'identificatore della skill, l'ultimo aggiornamento, i metadati personalizzati e la cronologia delle revisioni.
  5. Utilizza i pulsanti di controllo dello stato per eseguire la transizione dello stato di destinazione. I pulsanti visualizzati nella pagina dipendono dallo stato attuale della skill, ad esempio Abilita, Disabilita, Ritira o Dismettere.

gcloud

Aggiorna il container della skill con il comando gcloud alpha agent-registry skills update e il flag --target-state:

gcloud alpha agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=DISABLED

Sostituisci quanto segue:

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

I valori consentiti per lo stato di destinazione sono:

  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED

REST

Invia una richiesta PATCH specificando targetState nel corpo e nella maschera di aggiornamento:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "targetState": "TARGET_STATE_DISABLED"
    }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

Sostituisci quanto segue:

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

I valori consentiti per lo stato di destinazione sono:

  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED

Elimina una skill

L'eliminazione di un container di competenze elimina definitivamente la risorsa Skill e tutte le risorse SkillRevision immutabili associate. Gli agenti che tentano di risolvere l'identificatore della skill eliminato non riescono in fase di runtime.

Console

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

    Vai ad Agent Registry

  2. Seleziona la scheda Competenze.
  3. Esamina l'elenco delle skill. Puoi filtrare la visualizzazione utilizzando i menu Località o Stato.
  4. Fai clic sul nome della skill che vuoi eliminare.
  5. Nella pagina Dettagli skill, fai clic su Elimina.
  6. Nella finestra di dialogo di conferma, inserisci DELETE e fai clic su Elimina.

gcloud

Per eliminare una skill, utilizza il comando gcloud alpha agent-registry skills delete:

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

Sostituisci quanto segue:

  • SKILL_ID: l'ID della skill che vuoi eliminare. 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 skill, 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?force=true"

Sostituisci quanto segue:

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

Passaggi successivi