Registrare le competenze

Agent Registry ti consente di pacchettizzare e registrare manualmente le skill autonome. Le skill autonome raggruppano le istruzioni dell'agente con gli asset di metadati associati e gli script facoltativi per estendere il ragionamento e il workflow di un agente. Registrando le tue skill autonome in Agent Registry, puoi gestire, controllare le versioni e condividere centralmente le funzionalità riutilizzabili insieme alle skill gestite da Google disponibili quando configuri Agent Registry.

Prima di iniziare

  1. Configura Agent Registry.
  2. Per una configurazione con un singolo progetto, recupera l'ID progetto del progetto di governance in cui è abilitato Agent Registry. Se hai configurato un confine di gestione per più progetti, utilizza l'ID del progetto di gestione per il rilevamento e la registrazione a livello di confine oppure specifica l'ID di un progetto membro per le operazioni su un singolo progetto.

  3. Per utilizzare i comandi di Google Cloud CLI in questo documento, configura 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 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 del Registro degli agenti potrebbero includere anche le autorizzazioni necessarie per registrare e gestire le skill e le relative revisioni. 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 skill in un archivio ZIP. L'archivio deve includere un file di istruzioni SKILL.md nella directory principale. Durante la fase di importazione del processo di registrazione delle skill, Agent Registry verifica che il payload sia conforme ai seguenti vincoli:

  • Dimensioni del file ZIP: dimensioni massime dell'archivio compresso pari a 1 MB.
  • Dimensioni totali del payload non compresso: dimensioni massime non compresse di 10 MB quando la scansione è attiva.
  • Dimensioni dei singoli file: dimensioni massime non compresse di 1 MB per file quando la scansione è attiva.
  • Nidificazione profonda: profondità massima di nidificazione delle directory di 8 livelli.
  • Conformità alle specifiche: il file SKILL.md deve contenere una sezione front matter YAML valida che definisca il nome, la descrizione e i metadati come definito nella specifica delle skill dell'agente.

Quando la scansione automatica è abilitata utilizzando la policy di scansione ENABLED_BLOCKING o ENABLED_NONBLOCKING, il superamento della dimensione massima non compressa causa l'errore di creazione della revisione con un errore INVALID_ARGUMENT o la transizione dello stato di scansione della revisione a UNSUPPORTED_FORMAT. Se la scansione è disattivata, Agent Registry ignora questi limiti specifici della scansione. Per configurare le policy di scansione e scoprire di più sui vincoli relativi alle dimensioni del payload, consulta Esegui la scansione delle skill per rilevare problemi di sicurezza.

Registra una skill

Puoi registrare manualmente le tue skill in Agent Registry. Per informazioni sui prezzi e sui costi delle funzionalità per le skill, consulta Prezzi di Agent Registry.

Per registrare le tue competenze:

Console

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

    Vai ad 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 per creare un contenitore di skill e importare il pacchetto di skill iniziale. Scegli 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: registra un nuovo pacchetto di skill personalizzate caricando un bundle ZIP contenente il file di istruzioni SKILL.md e gli script facoltativi o un file SKILL.md autonomo.
  5. Nel riquadro Crea skill o Importa skill, specifica i seguenti dettagli:

    • Nome visualizzato: inserisci un nome facile da usare 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: carica l'archivio ZIP della skill pacchettizzata o un file autonomo SKILL.md nel campo Carica pacchetto o file. Le dimensioni massime di caricamento sono di 1 MB. Puoi sfogliare il file dalla tua directory locale.
    • Bucket GCS: inserisci il percorso dell'archivio ZIP archiviato in un bucket Cloud Storage nel campo URI Cloud Storage. Le dimensioni massime di caricamento sono di 1 MB. Il percorso deve essere nel formato gs://BUCKET_NAME/SKILL_PACKAGE.zip.

  7. Fai clic su Crea.

    La skill viene creata nello stato Disattivata (DISABLED). Per tutte le operazioni successive, fai riferimento alla skill come private-SKILL_ID, come visualizzato nella consoleGoogle Cloud .

  8. Per rendere la skill disponibile per il rilevamento degli agenti, imposta la sua revisione predefinita e aggiorna lo stato di destinazione su Attivo. Per istruzioni, vedi Gestisci le competenze.

gcloud

  1. Crea il container della skill e carica il payload della revisione iniziale con il comando gcloud agent-registry skills create. Puoi caricare un file ZIP locale o importare un pacchetto archiviato in Cloud Storage:

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

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

      Sostituisci LOCAL_ZIP_PATH con il percorso dell'archivio delle skill pacchettizzate 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 agent-registry skills create SKILL_ID \
          --project=PROJECT_ID \
          --location=LOCATION \
          --display-name="DISPLAY_NAME" \
          --description="DESCRIPTION" \
          --target-state=disabled \
          --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 il payload della skill.

    Sostituisci quanto segue in uno dei due comandi:

    • 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 usare per la skill.
    • DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.
  2. Quando crei una skill senza una revisione iniziale, puoi impostare solo lo stato di destinazione (--target-state) su draft o disabled.

    Quando crei una skill con una revisione iniziale, ad esempio con --gcs-source-uri o --payload, Agent Registry imposta la revisione iniziale come revisione predefinita della skill. Puoi impostare lo stato di destinazione su uno dei seguenti valori, a seconda della policy di scansione:

    • Se --target-state=active e la policy di scansione è disabled o enabled-nonblocking, la skill passa allo stato Attiva (STATE_ACTIVE) al termine dell'operazione di creazione.
    • Se --target-state=active e la policy di scansione è enabled-blocking (predefinita), la skill entra nello stato Bozza (STATE_DRAFT) al termine dell'operazione di creazione. In background, al termine dell'analisi della sicurezza, la skill principale passa allo stato Attiva (STATE_ACTIVE) solo se l'analisi non produce risultati e la skill principale è in stato Bozza con la revisione predefinita che punta ancora alla revisione iniziale.
    • Se --target-state=disabled o --target-state=draft, puoi renderlo disponibile in un secondo momento per il rilevamento degli agenti impostando una revisione predefinita valida e aggiornando lo stato di destinazione su Attivo. Per istruzioni, vedi Gestisci le skill.

REST

  1. Crea il container di skill con una revisione iniziale in linea:

    Metodo HTTP e URL

    POST https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID
    

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto
    • LOCATION: la località del registry.
    • SKILL_ID: un identificatore univoco per il container di skill.

    Corpo JSON della richiesta (caricamento di file locali)

    Per creare una skill caricando direttamente i byte dell'archivio ZIP locale, utilizza il payload archiveUploadSource nella revisione iniziale (initialRevision). Quando fornisci una revisione iniziale, Agent Registry la imposta come revisione predefinita della skill. Puoi impostare lo stato di destinazione su TARGET_STATE_DRAFT, TARGET_STATE_DISABLED o TARGET_STATE_ACTIVE. Senza una revisione iniziale, sono supportati solo TARGET_STATE_DRAFT e TARGET_STATE_DISABLED come stati di destinazione:

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

    Sostituisci quanto segue:

    • DISPLAY_NAME: un nome facile da usare per la skill.
    • DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.
    • BASE64_ZIP_BYTES: la rappresentazione della stringa con codifica Base64 del file 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_DISABLED",
      "initialRevision": {
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }
    }
    

    Sostituisci quanto segue:

    • DISPLAY_NAME: un nome facile da usare per la skill.
    • DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.
    • BUCKET_NAME: il nome del bucket Cloud Storage che contiene il bundle ZIP.
    • SKILL_PACKAGE: il nome del pacchetto di competenze contenente il payload delle competenze.

    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_DISABLED",
          "initialRevision": {
            "archiveUploadSource": {
              "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
            }
          }
        }' \
        "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"
    

    Sostituisci quanto segue:

    • DISPLAY_NAME: un nome facile da usare per la skill.
    • DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.
    • PROJECT_ID: l'ID progetto
    • LOCATION: la località del registry.
    • SKILL_ID: un identificatore univoco per il container di skill.

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

  2. Quando crei una skill con una revisione iniziale, Agent Registry imposta la revisione iniziale come revisione predefinita della skill principale e modifica lo stato della skill in base allo stato di destinazione e alla policy di scansione:

    • Se lo stato di destinazione è TARGET_STATE_ACTIVE e la policy di scansione è DISABLED o ENABLED_NONBLOCKING, la skill entra nello stato STATE_ACTIVE al completamento dell'operazione a lunga esecuzione (LRO).
    • Se lo stato di destinazione è TARGET_STATE_ACTIVE e la policy di scansione è ENABLED_BLOCKING (predefinita), la skill entra nello stato STATE_DRAFT al completamento dell'LRO. In background, al termine dell'analisi della sicurezza, la skill principale passa a STATE_ACTIVE solo se l'analisi non produce risultati e la skill principale è ancora in STATE_DRAFT con la revisione predefinita che punta ancora alla revisione iniziale.
    • Se lo stato target è TARGET_STATE_DISABLED o TARGET_STATE_DRAFT, la skill inizia in STATE_DISABLED o STATE_DRAFT. Per rendere la skill disponibile per il rilevamento degli agenti in un secondo momento, devi impostare la revisione predefinita e aggiornare lo stato di destinazione su TARGET_STATE_ACTIVE. Per istruzioni, vedi Gestisci le competenze.

Le skill create da te o da altri utenti vengono assegnate automaticamente al publisher private predefinito per evitare conflitti di nomi con le skill gestite 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_NUMBER/locations/LOCATION/skills/private-workspace-tools. L'identificatore della skill viene assegnato come urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Devi utilizzare l'ID pubblicato private-workspace-tools per tutte le operazioni successive relative alla skill.

Quando crei una skill, Agent Registry configura automaticamente una policy IAM di autorizzazione a livello di risorsa sulla nuova risorsa Skill:

  • Alla tua entità viene concesso il ruolo Agent Registry API Admin (roles/agentregistry.admin) sulla skill.
  • Se il progetto appartiene a un'organizzazione, al set di entità che rappresenta i workload degli agenti nel progetto viene concesso il ruolo Visualizzatore API Agent Registry (roles/agentregistry.viewer) sulla skill.

Per condividere una skill con altri utenti, gruppi, service account o workload degli agenti, consulta Gestisci l'accesso a una skill.

Passaggi successivi