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
- Configura Agent Registry.
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.
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:
-
Registra e gestisci skill autonome:
Agent Registry User (
roles/agentregistry.user) -
Registra e gestisci skill autonome e altre risorse di Agent Registry:
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 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.mddeve 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
Nella console Google Cloud , vai alla pagina Agent Registry:
Nel selettore di progetti, seleziona il tuo progetto Google Cloud .
Seleziona la scheda Competenze.
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.mde gli script facoltativi o un fileSKILL.mdautonomo.
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,usoeu.
Nella sezione Origine payload, scegli una delle seguenti opzioni:
- File: carica l'archivio ZIP della skill pacchettizzata o un file autonomo
SKILL.mdnel 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.
- File: carica l'archivio ZIP della skill pacchettizzata o un file autonomo
Fai clic su Crea.
La skill viene creata nello stato Disattivata (
DISABLED). Per tutte le operazioni successive, fai riferimento alla skill comeprivate-SKILL_ID, come visualizzato nella consoleGoogle Cloud .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
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_PATHcon 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 esempioworkspace-docs-skill. Dopo la creazione, il registry antepone automaticamente il prefissoprivate-. Devi utilizzare l'ID con prefisso in tutti i comandi successivi della skill, ad esempioprivate-workspace-docs-skill.PROJECT_ID: l'ID progettoLOCATION: la regione geografica, ad esempioglobal,usoeu.DISPLAY_NAME: un nome facile da usare per la skill.DESCRIPTION: un breve riepilogo che spiega le funzionalità della skill.
Quando crei una skill senza una revisione iniziale, puoi impostare solo lo stato di destinazione (
--target-state) sudraftodisabled.Quando crei una skill con una revisione iniziale, ad esempio con
--gcs-source-urio--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=activee la policy di scansione èdisabledoenabled-nonblocking, la skill passa allo stato Attiva (STATE_ACTIVE) al termine dell'operazione di creazione. - Se
--target-state=activee 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=disabledo--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.
- Se
REST
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_IDSostituisci quanto segue:
PROJECT_ID: l'ID progettoLOCATION: 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
archiveUploadSourcenella revisione iniziale (initialRevision). Quando fornisci una revisione iniziale, Agent Registry la imposta come revisione predefinita della skill. Puoi impostare lo stato di destinazione suTARGET_STATE_DRAFT,TARGET_STATE_DISABLEDoTARGET_STATE_ACTIVE. Senza una revisione iniziale, sono supportati soloTARGET_STATE_DRAFTeTARGET_STATE_DISABLEDcome 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 progettoLOCATION: 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.
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_ACTIVEe la policy di scansione èDISABLEDoENABLED_NONBLOCKING, la skill entra nello statoSTATE_ACTIVEal completamento dell'operazione a lunga esecuzione (LRO). - Se lo stato di destinazione è
TARGET_STATE_ACTIVEe la policy di scansione èENABLED_BLOCKING(predefinita), la skill entra nello statoSTATE_DRAFTal completamento dell'LRO. In background, al termine dell'analisi della sicurezza, la skill principale passa aSTATE_ACTIVEsolo se l'analisi non produce risultati e la skill principale è ancora inSTATE_DRAFTcon la revisione predefinita che punta ancora alla revisione iniziale. - Se lo stato target è
TARGET_STATE_DISABLEDoTARGET_STATE_DRAFT, la skill inizia inSTATE_DISABLEDoSTATE_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 suTARGET_STATE_ACTIVE. Per istruzioni, vedi Gestisci le competenze.
- Se lo stato di destinazione è
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
- Scopri come gestire le tue competenze registrate.
- Scopri come aggiungere e gestire le revisioni delle skill.
- Scopri come eseguire la scansione delle skill per rilevare problemi di sicurezza.
- Esamina i dettagli del publisher verificato.