Registrare le competenze

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

In Agent Registry, una skill rappresenta una funzionalità eseguibile autonoma che un agente può avere. Contiene istruzioni in un file SKILL.md, script di codice e asset che estendono il ragionamento di un agente. Registrando le skill autonome in Agent Registry, puoi gestire, controllare le versioni e condividere le funzionalità a livello centrale tra gli agenti AI della tua organizzazione.

Le skill create da Google sono visibili immediatamente quando configuri il Registro degli agenti. Questo documento spiega come registrare manualmente le tue skill autonome in Agent Registry.

Prima di iniziare

Prima di iniziare, configura l'Agent Registry. 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 registrare le skill in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Registra e gestisci le skill autonome: Agent Registry User (roles/agentregistry.user)
• Registra e gestisci skill autonome e altre risorse del registro degli agenti: Agent Registry API Editor (roles/agentregistry.editor)

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 dell'Agent Registry potrebbero includere anche le autorizzazioni necessarie per registrare e gestire le skill e le revisioni delle skill. Per saperne di più, consulta Ruoli e autorizzazioni di Agent Registry.

Vincoli del payload di importazione

Per registrare una skill, devi comprimere i file di origine della funzionalità in un archivio ZIP. L'archivio deve includere un file di istruzioni SKILL.md nella directory principale. Durante la fase di importazione della procedura di registrazione delle skill, Agent Registry verifica che il payload sia conforme ai seguenti vincoli:

• Dimensioni dell'archivio ZIP: dimensione massima dell'archivio compresso di 500 kB.
• Dimensioni totali del payload non compresso:dimensioni massime non compresse di 10 MB.
• Dimensioni dei singoli file:dimensione massima non compressa di 1 MB per file.
• Nidificazione profonda:profondità massima di nidificazione delle directory di 8 livelli.
• Conformità alle specifiche:il file SKILL.md deve contenere una sezione di frontespizio YAML valida che definisca il nome, la descrizione e i metadati come definiti nelle specifiche delle competenze dell'agente.

Registrare una skill

Le skill create da Google sono visibili immediatamente quando configuri il Registro degli agenti. Tuttavia, puoi anche registrare manualmente le tue skill. Ogni skill ha una revisione predefinita e può contenere più revisioni della skill con controllo delle versioni.

Per registrare le tue skill, crea un container di skill logico e carica il payload della revisione iniziale in un'unica operazione. In un secondo momento, potrai gestire le skill registrate e le successive revisioni delle skill.

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

Le skill create da te o da altri utenti vengono assegnate automaticamente all'editore private predefinito per evitare conflitti di nomi con le skill create da Google. Per questo motivo, l'ID pubblicato di una determinata skill diventa private-SKILL_ID. Non puoi specificare un editore personalizzato durante la creazione dell'abilità.

Ad esempio, se crei un'abilità con l'ID workspace-tools, il nome della risorsa viene creato come projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools. Il nome URN (Uniform Resource Name) logico viene assegnato come urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Devi utilizzare questo ID pubblicato (private-workspace-tools) per tutte le operazioni successive della skill.

Per registrare una skill:

Console

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

   Vai a Agent Registry

2. Nel selettore di progetti, seleziona il tuo progetto Google Cloud .

3. Seleziona la scheda Competenze.

4. Nella scheda Skill, il pulsante Aggiungi skill mostra due opzioni. Puoi scegliere una delle seguenti opzioni:

   • Aggiungi skill: crea un nuovo contenitore di skill nel registry. Facoltativamente, puoi caricare un pacchetto di skill per creare la prima revisione.
   • Importa skill: esegui l'onboarding di un nuovo pacchetto di skill personalizzate caricando un pacchetto ZIP contenente il codice o il file di istruzioni del prompt (SKILL.md).

5. Nel riquadro Crea skill o Importa skill, specifica i seguenti dettagli:

   • Nome visualizzato:inserisci un nome intuitivo per la skill.
   • Descrizione:inserisci un breve riepilogo che spieghi le funzionalità della skill.
   • Località:seleziona la regione geografica, ad esempio global, us o eu.

6. Nella sezione Origine payload, scegli una delle seguenti opzioni:

   • File:trascina il file ZIP del pacchetto della skill o sfoglia la directory locale.

   • Bucket:inserisci il percorso dell'archivio ZIP archiviato in un bucket Cloud Storage, nel formato gs://BUCKET_NAME/SKILL_PACKAGE.zip.

     Importante: prima che Agent Registry possa accedere ai file delle tue skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel tuo bucket Cloud Storage. Il service agent Agent Registry utilizza il seguente formato: [e-mail]. Se questo service agent non esiste nel tuo progetto, ad esempio se non hai mai creato una skill, attivalo per l'API Agent Registry seguendo i passaggi descritti in Creare e concedere ruoli ai service agent. Il service agent richiede l'autorizzazione storage.objects.get sul bucket Cloud Storage contenente l'archivio ZIP. Per istruzioni su come concedere autorizzazioni IAM per le risorse bucket, consulta IAM per Cloud Storage.

7. Fai clic su Crea.

La tua skill è stata creata. Per tutte le operazioni successive relative alle skill, fai riferimento alla tua skill come private-SKILL_ID, come visualizzato nella consoleGoogle Cloud .

gcloud

Per registrare una skill e caricare il relativo payload iniziale, puoi caricare un file ZIP locale o importare un pacchetto archiviato in Cloud Storage.

Sostituisci quanto segue:

• SKILL_ID: l'ID risorsa della skill, ad esempio workspace-docs-skill. Dopo la creazione, il registro aggiunge automaticamente il prefisso private-. Devi utilizzare l'ID con prefisso in tutti i comandi successivi dell'intent integrato, ad esempio private-workspace-docs-skill.
• PROJECT_ID: l'ID progetto.
• LOCATION: la regione geografica, ad esempio global, us o eu.
• DISPLAY_NAME: un nome facile da ricordare per la skill.

• DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.

• Carica un file ZIP locale: per registrare una skill utilizzando un payload ZIP locale:

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

  Sostituisci LOCAL_ZIP_PATH con il percorso dell'archivio della skill pacchettizzata sulla tua macchina locale, ad esempio, ./workspace-docs-skill.zip.

• Importa da un bucket Cloud Storage: per registrare una skill utilizzando un archivio ZIP ospitato in un bucket Cloud Storage:

  gcloud alpha agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
  

  Importante: prima che Agent Registry possa accedere ai file delle tue skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel tuo bucket Cloud Storage. Il service agent Agent Registry utilizza il seguente formato: [e-mail]. Se questo service agent non esiste nel tuo progetto, ad esempio se non hai mai creato una skill, attivalo per l'API Agent Registry seguendo i passaggi descritti in Creare e concedere ruoli ai service agent. Il service agent richiede l'autorizzazione storage.objects.get sul bucket Cloud Storage contenente l'archivio ZIP. Per istruzioni su come concedere autorizzazioni IAM per le risorse bucket, consulta IAM per Cloud Storage.

  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 il payload della skill.

REST

Per creare una skill con una revisione iniziale incorporata:

Metodo HTTP e URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

Corpo JSON della richiesta (caricamento di file locale)

Per creare una skill caricando direttamente i byte dell'archivio ZIP locale, utilizza il payload archiveUploadSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

Sostituisci BASE64_ZIP_BYTES con la rappresentazione della stringa con codifica Base64 del tuo archivio ZIP locale.

Corpo JSON della richiesta (importazione da Cloud Storage)

In alternativa, per creare un'abilità utilizzando un archivio archiviato in un bucket Cloud Storage, utilizza gcsSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

Importante: prima che Agent Registry possa accedere ai file delle tue skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel tuo bucket Cloud Storage. Il service agent Agent Registry utilizza il seguente formato: [e-mail]. Se questo service agent non esiste nel tuo progetto, ad esempio se non hai mai creato una skill, attivalo per l'API Agent Registry seguendo i passaggi descritti in Creare e concedere ruoli ai service agent. Il service agent richiede l'autorizzazione storage.objects.get sul bucket Cloud Storage contenente l'archivio ZIP. Per istruzioni su come concedere autorizzazioni IAM per le risorse bucket, consulta IAM per Cloud Storage.

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 il payload della skill.

Comando curl (caricamento di file locali)

curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "type": "SIMPLE",
        "targetState": "TARGET_STATE_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Per il caricamento di un file del bucket Cloud Storage, sostituisci il corpo JSON della richiesta con i campi e i valori corrispondenti.

Passaggi successivi

• Scopri come gestire le tue skill registrate.
• Scopri come aggiungere e gestire le revisioni delle skill.
• Esamina i dettagli del publisher verificato.