Ce guide explique comment créer, mettre à jour et gérer des compétences dans le Skill Registry à l'aide de l'API REST.
Avant de commencer
Avant d'utiliser Skill Registry, configurez votre environnement :
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Cloud de Confiance project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Make sure that you have the following role or roles on the project:
roles/aiplatform.viewerorroles/aiplatform.user,roles/serviceusage.serviceUsageConsumerCheck for the roles
-
In the Cloud de Confiance console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Cloud de Confiance console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
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.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
Conformité
Le tableau suivant récapitule l'état de conformité :
| Fonctionnalité | État |
|---|---|
| Access Transparency | Compatible |
| Résidence des données (DRZ) aux États-Unis et dans l'UE | Compatible |
| Clés de chiffrement gérées par le client (CMEK) | Non compatible |
| Certification HIPAA | Non compatible |
| VPC-SC | Non compatible |
Régions disponibles
Le registre de compétences est disponible dans les régions suivantes :
| Région | Emplacement |
|---|---|
us-central1 |
Iowa |
europe-west4 |
Pays-Bas |
us-east5 |
Columbus, Ohio |
Créer une compétence
Pour créer une compétence, utilisez la méthode CreateSkill. Cette opération est une opération de longue durée.
Pour obtenir des exemples de structure de compétence attendue, consultez les fichiers SKILL.md dans le dépôt Google Cloud Skills.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour créer une compétence.
Préparer la charge utile
Avant d'appeler l'API, regroupez les fichiers de votre skill dans une archive ZIP et encodez-la en une chaîne Base64 sur une seule ligne. Pour préparer la charge utile, procédez comme suit :
Accédez à votre répertoire de compétences :
cd <SKILL_DIRECTORY>Créez l'archive ZIP et encodez-la en base64.
Exemple :
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
LOCATION : région de votre skill. Pour en savoir plus, consultez la section Régions disponibles.
SKILL_ID : le
SKILL_IDest immuable et reste réservé de manière permanente une fois créé, même si vous supprimez la skill ultérieurement. Les ID de skill doivent respecter les contraintes suivantes :- Doit comporter entre 1 et 63 caractères.
- Doit être composé de lettres minuscules, de chiffres et de traits d'union.
- Doit commencer par une lettre et se terminer par une lettre ou un chiffre.
- Ne doit pas commencer par
gcp-(ce préfixe est réservé aux skills intégrées).
DISPLAY_NAME : nom de la compétence utilisée avec l'agent. La méthode
RetrieveSkillsutilise le nom à afficher et la description pour rechercher les compétences pertinentes.DESCRIPTION : description de ce que fait la skill.
BASE64_ZIPPED_BODY : contenu encodé en base64 de votre archive de skill compressée.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID
Corps JSON de la requête
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
Commande 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
Organisez les fichiers de compétence (tels que SKILL.md, les instructions et les fichiers de code) dans un répertoire local. Le SDK permet de transmettre un chemin d'accès à un répertoire local (qui est automatiquement compressé) ou un chemin d'accès pré-compressé.
Pour google-cloud-aiplatform (qui fournit agentplatform) version 1.154.0 et ultérieures :
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)
Pour les versions de google-cloud-aiplatform (qui fournit agentplatform) antérieures à 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
Organisez les fichiers de compétence (tels que SKILL.md, les instructions et les fichiers de code) dans un répertoire local. Le SDK permet de transmettre un chemin d'accès à un répertoire local (qui est automatiquement compressé) ou un chemin d'accès pré-compressé.
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);
Mettre à jour une compétence
Pour mettre à jour une compétence existante, utilisez la méthode UpdateSkill. Cette opération est une opération de longue durée.
Vous pouvez modifier le nom à afficher, la description et la charge utile (système de fichiers compressé) d'une compétence existante. Seuls les champs listés dans le paramètre de requête updateMask sont mis à jour.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour mettre à jour une compétence.
Préparer la charge utile
Facultatif. Si vous mettez à jour les fichiers de la skill, regroupez-les dans une archive ZIP et encodez-les en une chaîne base64 sur une seule ligne :
Accédez à votre répertoire de compétences :
cd <SKILL_DIRECTORY>Créez l'archive ZIP et encodez-la en base64 :
zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région de la skill. Pour en savoir plus, consultez la section Régions disponibles.
- SKILL_ID : ID de la compétence à modifier.
- DISPLAY_NAME : facultatif. Nouveau nom de la compétence.
- DESCRIPTION : facultatif. Nouvelle description de ce que fait la compétence.
- BASE64_ZIPPED_BODY : facultatif. Contenu encodé en base64 de votre archive de compétence compressée mise à jour.
Méthode HTTP et URL :
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Corps JSON de la requête
{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}
Commande curl
La commande curl suivante met à jour le nom à afficher, la description et le fichier de skill compressé.
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
Le SDK permet de mettre à jour les fichiers de compétence en transmettant un chemin d'accès local non compressé ou un chemin d'accès précompressé.
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
Le SDK permet de mettre à jour les fichiers de compétence en transmettant un chemin d'accès local non compressé ou un chemin d'accès précompressé.
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);
Lister les compétences
Pour récupérer les métadonnées récapitulatives des compétences dans un lieu spécifique (y compris le nom, le nom à afficher et la description), utilisez la méthode ListSkills.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour lister les compétences.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région des compétences que vous souhaitez lister. Pour en savoir plus, consultez la section Régions disponibles.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills
Commande 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"
Exemple de résultat
{
"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);
}
Obtenir une compétence
Pour récupérer les métadonnées et la charge utile de la dernière révision d'une skill, utilisez la méthode GetSkill.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour obtenir une compétence.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région dans laquelle se trouvent les compétences. Pour en savoir plus, consultez la section Régions disponibles.
- SKILL_ID : ID de la compétence à récupérer.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Commande 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);
Supprimer une compétence
Pour supprimer une compétence et toutes ses révisions, utilisez la méthode DeleteSkill.
Cette opération est une opération de longue durée.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour supprimer une compétence.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région dans laquelle se trouve la compétence que vous souhaitez supprimer. Pour en savoir plus, consultez la section Régions disponibles.
- SKILL_ID : ID de la compétence à supprimer.
Méthode HTTP et URL :
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID
Commande 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',
});
Lister les révisions de la compétence
Pour récupérer l'historique des révisions d'une compétence spécifique, utilisez la méthode ListSkillRevisions.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour lister les révisions de compétences.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région dans laquelle se trouvent les compétences que vous souhaitez. Pour en savoir plus, consultez la section Régions disponibles.
- SKILL_ID : ID de la compétence.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions
Commande 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"
Exemple de résultat
{
"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);
}
Obtenir une révision de compétence
Pour récupérer une révision spécifique d'une skill, utilisez la méthode GetSkillRevision.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour obtenir une révision de skill.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région de la skill. Pour en savoir plus, consultez la section Régions disponibles.
- SKILL_ID : ID de la compétence.
- REVISION_ID : ID de la révision spécifique à récupérer. Vous trouverez cette valeur dans le champ
namerenvoyé par la méthodeListSkillRevisions. Par exemple, sinameestprojects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123, l'ID de révision est4567890123.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID
Commande 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);
Récupérer des compétences
Utilisez la méthode RetrieveSkills pour trouver des compétences à l'aide de la recherche sémantique. Par exemple, vous pouvez rechercher des compétences en décrivant la tâche que vous souhaitez accomplir, comme find skills to manage cloud resources.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour récupérer des compétences.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région dans laquelle se trouvent les compétences que vous souhaitez rechercher. Pour en savoir plus, consultez la section Régions disponibles.
- QUERY : chaîne de requête permettant de trouver les compétences correspondantes.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY
Commande 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);
}
Obtenir les détails d'une opération de longue durée
Certaines méthodes de l'API Skill Registry, telles que CreateSkill, UpdateSkill et DeleteSkill, sont asynchrones et renvoient une opération de longue durée.
Une opération de longue durée est un modèle d'API utilisé pour les opérations qui peuvent prendre beaucoup de temps. Au lieu d'attendre la fin de l'opération, l'API renvoie une ressource d'opération.
La réponse de ces méthodes inclut un champ name, qui contient l'ID de l'opération. Par exemple, un name peut se présenter comme suit :
projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID.
Pour vérifier l'état et obtenir des détails sur une opération de longue durée, utilisez la méthode GetOperation avec le OPERATION_ID extrait.
REST
Les sections suivantes décrivent comment utiliser l'API REST pour obtenir une opération.
Variables de requête
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Cloud de Confiance by S3NS .
- LOCATION : région dans laquelle l'opération est exécutée. Elle doit correspondre à la région utilisée dans votre demande initiale. Pour en savoir plus, consultez la section Régions disponibles.
- OPERATION_ID : ID de l'opération. Extrayez-le du champ
namerenvoyé parCreateSkill,UpdateSkillouDeleteSkill.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID
Commande 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"
Étapes suivantes
Associer des compétences à un agent
Découvrez comment associer des compétences enregistrées lorsque vous créez ou mettez à jour un agent à l'aide de l'API Managed Agents sur Agent Platform.
Intégration du registre de compétences ADK
Découvrez comment intégrer Skill Registry dans ADK.