Creare e gestire skill

Questa guida spiega come creare, aggiornare e gestire le competenze nel registro delle competenze utilizzando l'API REST.

Prima di iniziare

Prima di utilizzare Skill Registry, configura l'ambiente:

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.viewer or roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Conformità

La tabella seguente riepiloga lo stato di conformità:

Funzionalità Stato
Access Transparency Supportato
Residenza dei dati (DRZ) negli Stati Uniti e nell'UE Supportato
Chiavi di crittografia gestite dal cliente (CMEK) Non supportato
Certificazione HIPAA Non supportato
VPC-SC Non supportato

Regioni disponibili

Il Registro delle competenze è disponibile nelle seguenti regioni:

Regione Località
us-central1 Iowa
europe-west4 Paesi Bassi
us-east5 Columbus, Ohio

Crea una skill

Per creare una nuova skill, utilizza il metodo CreateSkill. Questa operazione è un'operazione a lunga esecuzione.

Per esempi della struttura delle competenze prevista, consulta i file SKILL.md nel repository Google Cloud Skills.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per creare una skill.

Prepara il payload

Prima di chiamare l'API, crea un pacchetto dei file della skill in un archivio compresso e codificalo in una stringa base64 a una sola riga. Per preparare il payload, segui questi passaggi:

  1. Vai alla directory delle skill:

    cd <SKILL_DIRECTORY>

  2. Crea l'archivio zip e codificalo in base64.

    Ad esempio:

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .

  • LOCATION: La regione della tua skill. Per saperne di più, consulta Regioni disponibili.

  • SKILL_ID: L'SKILL_ID è immutabile e rimane riservato in modo permanente una volta creato, anche se elimini la skill in un secondo momento. Gli ID skill devono rispettare i seguenti vincoli:

    • Deve avere una lunghezza compresa tra 1 e 63 caratteri.
    • Deve contenere solo lettere minuscole, numeri e trattini.
    • Deve iniziare con una lettera e terminare con una lettera o un numero.
    • Non deve iniziare con gcp- (questo prefisso è riservato alle skill integrate).

  • DISPLAY_NAME: il nome della skill utilizzata con l'agente. Il metodo RetrieveSkills utilizza il nome visualizzato e la descrizione per cercare skill pertinenti.

  • DESCRIPTION: una descrizione di cosa fa la skill.

  • BASE64_ZIPPED_BODY: i contenuti codificati in base64 dell'archivio compresso della tua skill.

Metodo HTTP e URL

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

Corpo JSON della richiesta

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

comando curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Python

Organizza i file di skill (ad esempio SKILL.md, istruzioni e file di codice) in una directory locale. L'SDK supporta il passaggio di un percorso di directory locale (che viene compresso automaticamente) o di un percorso pre-zippato.

Per google-cloud-aiplatform (che fornisce agentplatform) versione 1.154.0 e successive:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    skill_id="SKILL_ID",
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Per google-cloud-aiplatform (che fornisce agentplatform) versioni precedenti a 1.154.0:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        "skill_id": "SKILL_ID",
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

Organizza i file di skill (ad esempio SKILL.md, istruzioni e file di codice) in una directory locale. L'SDK supporta il passaggio di un percorso di directory locale (che viene compresso automaticamente) o di un percorso pre-zippato.

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.create({
  skillId: 'SKILL_ID',
  displayName: 'DISPLAY_NAME',
  description: 'DESCRIPTION',
  config: {
    // Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

Aggiornare una skill

Per aggiornare una skill esistente, utilizza il metodo UpdateSkill. Questa operazione è un'operazione a lunga esecuzione.

Puoi aggiornare il nome visualizzato, la descrizione e il payload di una skill esistente (file system compresso). Vengono aggiornati solo i campi elencati nel parametro di query updateMask.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per aggiornare una skill.

Prepara il payload

Facoltativo. Se stai aggiornando i file della skill, comprimili in un archivio compresso e codificali in una stringa base64 a una sola riga:

  1. Vai alla directory delle skill:

    cd <SKILL_DIRECTORY>

  2. Crea l'archivio zip e codificalo in base64:

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione della skill. Per saperne di più, consulta Regioni disponibili.
  • SKILL_ID: l'ID della competenza da aggiornare.
  • DISPLAY_NAME: (Facoltativo) Un nuovo nome per la competenza.
  • DESCRIPTION: (Facoltativo) Una nuova descrizione di ciò che fa la skill.
  • BASE64_ZIPPED_BODY: (Facoltativo) I contenuti con codifica base64 del tuo archivio compresso aggiornato della skill.

Metodo HTTP e URL

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

Corpo JSON della richiesta

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

comando curl

Il seguente comando curl aggiorna il nome visualizzato, la descrizione e il file della skill compresso.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,zippedFilesystem"

Python

L'SDK supporta l'aggiornamento dei file di skill passando un percorso di directory locale decompressa o un percorso precompresso.

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.update(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID",
    config={
        "display_name": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        # Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

L'SDK supporta l'aggiornamento dei file di skill passando un percorso di directory locale decompressa o un percorso precompresso.

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.update({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
  config: {
    displayName: 'DISPLAY_NAME',
    description: 'DESCRIPTION',
    // Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

Elenca skill

Per recuperare i metadati di riepilogo per le skill in una posizione specifica (inclusi nome, nome visualizzato e descrizione), utilizza il metodo ListSkills.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per elencare le competenze.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione delle competenze che vuoi elencare. Per saperne di più, consulta Regioni disponibili.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills

comando curl

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

Output di esempio

{
"name": "projects/1234567890/locations/us-central1/skills/3456789012",
"createTime": "2026-05-10T00:02:12.497720Z",
"updateTime": "2026-05-10T00:02:19.064874Z",
"displayName": "cymbal_skill",
"description": "A skill for managing Cymbal projects.",
"state": "ACTIVE"
}

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

pager = client.skills.list()
for skill in pager:
    print(skill.name, skill.display_name)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const pager = await client.skills.list();
for await (const skill of pager) {
  console.log(skill.name, skill.displayName);
}

Ottenere una skill

Per recuperare i metadati e il payload dell'ultima revisione di un'abilità, utilizza il metodo GetSkill.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per ottenere una skill.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione in cui si trovano le skill. Per saperne di più, consulta Regioni disponibili.
  • SKILL_ID: l'ID della skill da recuperare.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

comando curl

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

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
print(skill)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
console.log(skill);

Eliminare una skill

Per eliminare una skill e tutte le relative revisioni, utilizza il metodo DeleteSkill. Questa operazione è un'operazione a lunga esecuzione.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per eliminare un'abilità.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione in cui si trova la skill che vuoi eliminare. Per saperne di più, consulta Regioni disponibili.
  • SKILL_ID: l'ID della skill da eliminare.

Metodo HTTP e URL

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

comando curl

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

client.skills.delete(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

await client.skills.delete({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});

Elenca le revisioni della skill

Per recuperare la cronologia delle revisioni di una skill specifica, utilizza il metodo ListSkillRevisions.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per elencare le revisioni delle skill.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione in cui si trovano le competenze che ti interessano. Per saperne di più, consulta Regioni disponibili.
  • SKILL_ID: l'ID della competenza.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions

comando curl

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

Output di esempio

{
  "skillRevisions": [
    {
      "name": "projects/1234567890/locations/us-central1/skills/cymbal_skill/revisions/4567890123",
      "createTime": "2026-05-10T00:02:12.497720Z",
      "updateTime": "2026-05-10T00:02:19.064874Z"
    }
  ]
}

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
for skill_revision in response.skill_revisions:
    print(skill_revision.name, skill_revision.create_time)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.revisions.list({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
for (const revision of response.skillRevisions || []) {
  console.log(revision.name, revision.createTime);
}

Ottenere una revisione della skill

Per recuperare una revisione specifica di un'abilità, utilizza il metodo GetSkillRevision.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per ottenere una revisione di un'abilità.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione della skill. Per saperne di più, consulta Regioni disponibili.
  • SKILL_ID: l'ID della competenza.
  • REVISION_ID: l'ID della revisione specifica da recuperare. Puoi trovarlo nel campo name restituito dal metodo ListSkillRevisions. Ad esempio, se name è projects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123, l'ID revisione è 4567890123.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID

comando curl

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

revision = client.skills.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
)
print(revision)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const revision = await client.skills.revisions.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID',
});
console.log(revision);

Recuperare le competenze

Utilizza il metodo RetrieveSkills per trovare le competenze utilizzando la ricerca semantica. Ad esempio, puoi cercare le competenze descrivendo l'attività che vuoi svolgere, ad esempio find skills to manage cloud resources.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per recuperare le competenze.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione in cui si trovano le competenze che vuoi cercare. Per saperne di più, consulta Regioni disponibili.
  • QUERY: la stringa di query per trovare le competenze corrispondenti.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY

comando curl

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY"

Python 

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.retrieve(
    query="QUERY",
    config={"top_k": TOP_K},
)
for retrieved_skill in response.retrieved_skills:
    print(retrieved_skill.skill_name, retrieved_skill.description)

Node.js 

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.retrieve({
  query: 'QUERY',
  config: {
    topK: TOP_K,
  },
});
for (const retrievedSkill of response.retrievedSkills || []) {
  console.log(retrievedSkill.skillName, retrievedSkill.description);
}

Visualizzare i dettagli di un'operazione a lunga esecuzione

Alcuni metodi dell'API Skill Registry, come CreateSkill, UpdateSkill e DeleteSkill, sono asincroni e restituiscono un'operazione a lunga esecuzione. Un'operazione a lunga esecuzione è un pattern API utilizzato per le operazioni che possono richiedere un tempo significativo per essere completate. Anziché attendere il completamento dell'operazione, l'API restituisce una risorsa operazione.

La risposta di questi metodi include un campo name, che contiene l'ID operazione. Ad esempio, un name potrebbe avere il seguente aspetto: projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID.

Per controllare lo stato e ottenere i dettagli di un'operazione a lunga esecuzione, utilizza il metodo GetOperation con il OPERATION_ID estratto.

REST

Le sezioni seguenti descrivono come utilizzare l'API REST per ottenere un'operazione.

Variabili di richiesta

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
  • LOCATION: la regione in cui è in esecuzione l'operazione. Deve corrispondere alla regione utilizzata nella richiesta iniziale. Per saperne di più, consulta Regioni disponibili.
  • OPERATION_ID: l'ID dell'operazione. Estrai questo valore dal campo name restituito da CreateSkill, UpdateSkill o DeleteSkill.

Metodo HTTP e URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

comando curl

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

Passaggi successivi

Guida

Scopri come collegare le skill registrate durante la creazione o l'aggiornamento di un agente utilizzando l'API Managed Agents sulla piattaforma Agent Platform.

Guida

Scopri come eseguire l'integrazione con Skill Registry in ADK.