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 centralmente le funzionalità tra gli agenti AI della tua organizzazione.

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

Prima di iniziare

Prima di iniziare, configura Agent Registry. 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 registrare le skill in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Utente Agent Registry (roles/agentregistry.user) 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.

Vincoli del payload di inserimento

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 radice. Durante la fase di inserimento della procedura di registrazione della skill, Agent Registry verifica che il payload sia conforme ai seguenti vincoli:

• Dimensione dell'archivio ZIP: dimensione massima dell'archivio compresso di 500 KB.
• Dimensione totale del payload non compresso: dimensione massima non compressa di 10 MB.
• Dimensione 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 front matter YAML valida che definisca il nome, la descrizione e i metadati come definiti nelle specifiche delle skill dell'agente.

Registra una skill

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

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, puoi gestire le skill registrate e le revisioni successive delle skill.

Le skill create da te o da altri utenti vengono assegnate automaticamente al publisher 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 publisher personalizzato durante la creazione della skill.

Ad esempio, se crei una skill 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 Google Cloud console, vai alla pagina Agent Registry:

   Vai ad Agent Registry

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

3. Seleziona la scheda Skill.

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

   • Aggiungi skill: crea un nuovo container di skill nel registry. Facoltativamente, puoi caricare un pacchetto di skill per creare la prima revisione.
   • Importa skill: fai 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 facile da ricordare 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 del payload, scegli una delle seguenti opzioni:

   • File: trascina il file ZIP del pacchetto di 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 skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel 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, attiva la sua creazione 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 le autorizzazioni IAM sulle risorse dei bucket, consulta IAM per Cloud Storage.

7. Fai clic su Crea.

La skill viene creata. Per tutte le operazioni successive della skill, fai riferimento alla skill come private-SKILL_ID, come mostrato nella Google Cloud console.

gcloud

Per registrare una skill e caricare il 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 registry antepone automaticamente il prefisso private-. Devi utilizzare l'ID con prefisso in tutti i comandi successivi della skill, 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 del pacchetto di skill 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 skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel 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, attiva la sua creazione 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 le autorizzazioni IAM sulle risorse dei bucket, consulta IAM per Cloud Storage.

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

REST

Per creare una skill con una revisione iniziale in linea:

Metodo HTTP e URL

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

Corpo JSON della richiesta (caricamento di file locali)

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 dell'archivio ZIP locale.

Corpo JSON della richiesta (importazione da Cloud Storage)

In alternativa, per creare una skill 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 skill, devi concedere al suo service agent l'accesso all'archivio ZIP nel 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, attiva la sua creazione 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 le autorizzazioni IAM sulle risorse dei bucket, consulta IAM per Cloud Storage.

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 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 in un bucket Cloud Storage, sostituisci il corpo JSON della richiesta con i campi e i valori corrispondenti.

Passaggi successivi

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