Architecture des compétences

Dans le registre d'agents, les compétences vous permettent de regrouper des instructions, des scripts facultatifs et des connaissances du domaine dans des fonctionnalités modulaires qui étendent le raisonnement et le workflow d'un agent. En enregistrant des compétences autonomes dans Agent Registry, vous pouvez gérer les versions, gouverner et partager de manière centralisée une logique de tâche réutilisable entre vos agents. Agent Registry indexe également les compétences A2A intégrées déclarées sur les cartes d'agent de vos agents, afin que d'autres agents puissent les découvrir et les appeler.

Types de compétences

Le registre d'agents accepte deux types de compétences :

  • Compétences autonomes : packages avec contrôle des versions enregistrés en tant que ressources Skill de premier niveau dans le registre d'agents. Les compétences autonomes contiennent des fichiers d'instructions SKILL.md, des scripts facultatifs et des éléments de métadonnées gérés indépendamment de tout déploiement d'agent unique.
  • Compétences A2A : descriptions des capacités listées de manière intégrée dans le champ skills de la carte d'agent agent-card.json d'un agent, qui indiquent aux autres agents quand et comment lui déléguer des tâches.

Pour comparer ces deux modèles, consultez Différences entre les compétences autonomes et les compétences A2A.

Compétences autonomes

Les compétences autonomes sont des ressources de premier niveau dans Agent Registry, gérées avec les agents, les serveurs MCP et les points de terminaison. Contrairement à ces composants, les compétences autonomes n'utilisent pas de ressources Service distinctes. À la place, vous enregistrez, versionnez et interrogez des compétences autonomes directement sur trois niveaux de ressources :

  • Éditeurs : ressources Publisher qui établissent la propriété, le niveau de validation et la syntaxe de l'identifiant de compétence pour un ensemble de compétences.
  • Conteneurs de compétences : ressources Skill de premier niveau dans le registre d'agents que les clients découvrent et résolvent au moment de l'exécution, chacune conservant un pointeur vers une révision de diffusion par défaut de la compétence.
  • Révisions de compétences : ressources SkillRevision immuables et en lecture seule contenant les instructions, les scripts facultatifs et les éléments de métadonnées d'un package de compétences à une version spécifique.

Éditeurs

Chaque compétence autonome d'Agent Registry appartient à un diffuseur. Les éditeurs établissent la provenance, le niveau de validation et le préfixe de nom des compétences :

  • Éditeurs gérés par Google (FIRST_PARTY) : éditeurs validés gérés par Google, tels que cloud.google.com et discoveryengine.googleapis.com. Les compétences gérées par Google de ces éditeurs sont détectables dans tous les projets lorsque vous configurez Agent Registry et que vous utilisez le format d'identifiant de compétence suivant : urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID. Par exemple : urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing.
  • Éditeurs privés (PRIVATE) : éditeur private par défaut automatiquement attribué aux compétences personnalisées que vous enregistrez manuellement dans un projet de gouvernance Google Cloud. Pour éviter les conflits de noms avec les compétences gérées par Google validées, Agent Registry ajoute automatiquement le préfixe private- à l'identifiant de compétence. Vous ne pouvez pas enregistrer de ressources Publisher personnalisées. Les compétences privées utilisent le format d'URN (Uniform Resource Name) suivant pour l'identifiant de compétence : urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID. Par exemple : urn:skill:projects-PROJECT_NUMBER:locations:global:private-incident-triage.

Pour savoir comment inspecter les éditeurs, consultez Examiner les détails de l'éditeur de compétences.

Conteneurs de compétences

Un conteneur de compétences est une ressource Skill qui représente une compétence autonome dans un projet et un emplacement de gouvernance. Pour une compétence créée manuellement, le registre d'agents génère un nom de ressource au format projects/PROJECT_NUMBER/locations/LOCATION/skills/private-SKILL_ID.

La ressource Skill sert de point de référence stable pour la découverte dans le registre d'agents et gère les champs suivants :

  • Métadonnées descriptives : nom à afficher lisible par l'humain (displayName), description récapitulative (description), identifiant de compétence (skillId) et attribution de l'éditeur.
  • Pointeur de révision par défaut : champ defaultRevision, qui fait référence à la ressource SkillRevision spécifique diffusée lorsque les clients résolvent ou téléchargent la compétence sans demander d'ID de révision explicite.
  • État du cycle de vie cible : champ targetState, qui contrôle si la compétence est active, désactivée, obsolète ou mise hors service.

Pour savoir comment afficher et mettre à jour des compétences, consultez Gérer les compétences.

Révisions de la compétence

Une ressource de révision de compétence (SkillRevision) représente un instantané immuable et versionné d'un package de compétences. Le nom de la ressource est au format suivant : projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID.

Lorsque vous mettez à jour les instructions, les scripts facultatifs ou les éléments de métadonnées d'une compétence, vous ne modifiez pas le package existant. Vous devez importer une nouvelle archive ZIP pour créer une révision. Lorsque Agent Registry valide que l'archive respecte la spécification des compétences de l'agent et les contraintes de charge utile d'ingestion, la révision passe à l'état Actif (ACTIVE). Vous pouvez ensuite mettre à jour le pointeur de révision par défaut sur la compétence parente pour diffuser la nouvelle révision. Si vous supprimez la révision définie comme révision par défaut de la compétence, Agent Registry efface le pointeur defaultRevision et fait passer la compétence active à l'état Désactivé (DISABLED).

La séparation du conteneur de compétences de ses instantanés de révision de compétences offre les avantages suivants :

  • Exécution déterministe : les agents épinglés à une révision spécifique sont protégés contre les modifications inattendues des requêtes ou les mises à jour de scripts.
  • Rollbacks contrôlés : vous pouvez importer et vérifier de nouvelles révisions de compétences, ou rétablir le pointeur defaultRevision vers une révision antérieure en cas de problème.
  • Auditabilité : les révisions historiques du package de compétences sont conservées et peuvent être inspectées jusqu'à ce qu'elles soient explicitement supprimées.

Pour savoir comment importer, télécharger et supprimer des révisions, consultez Gérer les révisions de compétences.

Spécification de package

Les compétences autonomes sont empaquetées sous forme d'archives ZIP conformes à la norme ouverte Agent Skills Specification.

L'archive doit contenir un fichier SKILL.md à la racine, ainsi que tous les scripts ou éléments de métadonnées requis par la compétence. Le fichier SKILL.md définit les instructions de la compétence. Ce fichier combine les métadonnées YAML front matter, telles que name et description, avec des instructions en langage naturel interprétées par les Agent Runtimes, ainsi que des références à des scripts ou des éléments complémentaires facultatifs dans l'archive.

Lorsque vous enregistrez une compétence ou créez une révision, Agent Registry valide l'archive par rapport aux contraintes de charge utile d'ingestion, analyse le fichier SKILL.md et indexe ses métadonnées pour la recherche et la découverte.

États du cycle de vie d'une compétence

Pour contrôler la façon dont une compétence autonome est résolue et téléchargée au moment de l'exécution, vous pouvez faire passer l'targetState du conteneur de compétences par quatre états :

  • Active (ACTIVE) : la compétence est diffusée, indexée pour la découverte et disponible pour la résolution de l'environnement d'exécution et les téléchargements de charges utiles. Pour définir une compétence sur Active, son pointeur defaultRevision doit référencer une ressource SkillRevision active.
  • Désactivé (DISABLED) : état initial par défaut lorsqu'une compétence est créée. La compétence n'est pas diffusée au moment de l'exécution, et la résolution et les téléchargements de la charge utile échouent immédiatement. Une compétence passe également à l'état Désactivé si son pointeur defaultRevision est effacé ou si sa révision par défaut est supprimée. Contrairement à l'état Mis hors service, vous pouvez activer une compétence désactivée en définissant un defaultRevision valide et en définissant son état cible sur Actif.
  • Obsolète (DEPRECATED) : la compétence peut toujours être résolue et téléchargée, mais indique aux utilisateurs qu'elle sera mise hors service.
  • Retirée (DECOMMISSIONED) : état final dans lequel la compétence est désactivée de manière permanente, n'est plus diffusée et ne peut pas être rétablie à l'état Active ou à tout autre état. Une compétence ne peut être mise hors service qu'après avoir été obsolète.

Vous pouvez mettre à jour l'état du cycle de vie d'une compétence à l'aide de la console Google Cloud , de la Google Cloud CLI ou de l'API Agent Registry sans supprimer les révisions historiques. Pour télécharger la charge utile ZIP d'une révision, la compétence parente doit être à l'état Actif ou Obsolète, et la révision elle-même doit être à l'état Actif. Pour obtenir des instructions détaillées, consultez Gérer les états du cycle de vie des compétences.

Différences entre les compétences autonomes et les compétences A2A

Agent Registry est compatible avec les compétences autonomes et les compétences A2A intégrées. Le tableau suivant compare leurs caractéristiques :

Caractéristique Compétence autonome Compétence A2A intégrée
Type de ressource Ressource Skill de premier niveau dans Agent Registry avec des ressources enfants SkillRevision. Tableau imbriqué dans la ressource Agent.
Contenu du package Archive ZIP contenant SKILL.md, des scripts facultatifs et des éléments compatibles. Objet JSON dans la carte "Agent" contenant id, name et description.
Modèle de gestion des versions Instantanés de révision de compétence immuables avec un pointeur defaultRevision configurable. Directement lié aux mises à jour de l'agent-card.json de l'agent.
Modèle d'exécution Téléchargé et chargé dans le contexte ou l'environnement d'exécution d'un agent. Annonce les capacités de tâches pour la délégation entre agents.
Spécification Spécification des compétences de l'agent. Spécification Agent2Agent (A2A).
Champ d'application de la gouvernance Géré entre les projets indépendamment des déploiements d'agents individuels. Couplé au cycle de vie du déploiement de l'agent hôte.

Étapes suivantes