Arquitectura de habilidades

En el Registro de agentes, las habilidades te permiten empaquetar instrucciones, secuencias de comandos opcionales y conocimientos de dominio en capacidades modulares que extienden el razonamiento y el flujo de trabajo de un agente. Si registras habilidades independientes en Agent Registry, puedes controlar las versiones, administrar y compartir de forma centralizada la lógica de tareas reutilizable en tus agentes. Agent Registry también indexa las habilidades de A2A intercaladas declaradas en las tarjetas de agente de tus agentes para que otros agentes puedan descubrirlas e invocarlas.

Tipos de habilidades

El Registro de agentes admite dos tipos de habilidades:

  • Habilidades independientes: Son paquetes con control de versiones registrados como recursos Skill de nivel superior en el Registro de agentes. Las habilidades independientes contienen archivos de instrucciones SKILL.md, secuencias de comandos opcionales y recursos de metadatos que se administran de forma independiente de cualquier implementación de agente único.
  • Habilidades de A2A: Son descripciones de capacidades que se enumeran de forma intercalada en el campo skills de la agent-card.json tarjeta de agente de un agente, que les indican a otros agentes cuándo y cómo delegarle trabajo.

Para obtener una comparación de estos dos modelos, consulta Diferencias entre las habilidades independientes y de app a app.

Habilidades independientes

Las habilidades independientes son recursos de nivel superior en Agent Registry, que se rigen junto con los agentes, los servidores de MCP y los endpoints. A diferencia de esos componentes, las habilidades independientes no usan recursos Service independientes. En su lugar, registras, creas versiones y consultas las habilidades independientes directamente en tres niveles de recursos:

  • Publicadores: Son recursos Publisher que establecen la propiedad, el nivel de verificación y la sintaxis del identificador de habilidad para una colección de habilidades.
  • Contenedores de habilidades: recursos Skill de nivel superior en el registro de agentes que los consumidores descubren y resuelven en el entorno de ejecución, cada uno de los cuales mantiene un puntero a una revisión de entrega predeterminada de la habilidad.
  • Revisiones de habilidades: recursos SkillRevision inmutables y de solo lectura que contienen las instrucciones, las secuencias de comandos opcionales y los recursos de metadatos de un paquete de habilidades en una versión específica.

Publicadores

Cada habilidad independiente en Agent Registry pertenece a un publicador. Los publicadores establecen la procedencia, el nivel de verificación y el prefijo de nombres para las habilidades:

  • Publicadores administrados por Google (FIRST_PARTY): Son publicadores verificados que administra Google, como cloud.google.com y discoveryengine.googleapis.com. Las habilidades administradas por Google de estos publicadores se pueden descubrir en todos los proyectos cuando configuras Agent Registry y usas el siguiente formato de identificador de habilidad: urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID. Por ejemplo: urn:skill:discoveryengine.googleapis.com:discoveryengine:report-writing.
  • Publicadores privados (PRIVATE): Es el publicador predeterminado de private que se asigna automáticamente a las habilidades personalizadas que registras de forma manual en un Google Cloud proyecto de administración. Para evitar colisiones de nombres con habilidades verificadas administradas por Google, el Registro de agentes antepone automáticamente el prefijo private- al identificador de habilidad. No puedes registrar recursos Publisher personalizados. Las habilidades privadas usan el siguiente formato de nombre de recurso uniforme (URN) para el identificador de habilidad: urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID. Por ejemplo: urn:skill:projects-PROJECT_NUMBER:locations:global:private-incident-triage.

Para obtener instrucciones sobre cómo inspeccionar publicadores, consulta Revisa los detalles del publicador de habilidades.

Contenedores de habilidades

Un contenedor de habilidades es un recurso Skill que representa una habilidad independiente dentro de un proyecto y una ubicación de administración. Para una habilidad creada de forma manual, Agent Registry genera un nombre de recurso con el formato projects/PROJECT_NUMBER/locations/LOCATION/skills/private-SKILL_ID.

El recurso Skill sirve como punto de referencia estable para el descubrimiento en Agent Registry y mantiene los siguientes campos:

  • Metadatos descriptivos: el nombre visible legible por humanos (displayName), la descripción resumida (description), el identificador de habilidad (skillId) y la atribución del publicador.
  • Puntero de revisión predeterminado: Es el campo defaultRevision, que hace referencia al recurso SkillRevision específico que se entrega cuando los consumidores resuelven o descargan la habilidad sin solicitar un ID de revisión explícito.
  • Estado del ciclo de vida objetivo: Es el campo targetState, que controla si la habilidad está en un estado activo, inhabilitado, obsoleto o retirado.

Para obtener instrucciones sobre cómo ver y actualizar habilidades, consulta Administra habilidades.

Revisiones de habilidades

Un recurso de revisión de habilidad (SkillRevision) representa una instantánea inmutable y con versión de un paquete de habilidades. El nombre del recurso tiene el siguiente formato: projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID.

Cuando actualizas las instrucciones, las secuencias de comandos opcionales o los recursos de metadatos de una habilidad, no modificas el paquete existente en su lugar. En su lugar, subes un archivo ZIP nuevo para crear una revisión nueva. Cuando Agent Registry valida que el archivo cumple con la especificación de habilidades del agente y las restricciones de carga útil de transferencia, la revisión ingresa al estado Activo (ACTIVE). Luego, puedes actualizar el puntero de revisión predeterminado en la habilidad superior para entregar la revisión nueva. Si borras la revisión que se estableció como la revisión predeterminada de la habilidad, Agent Registry borra el puntero defaultRevision y cambia la habilidad activa al estado Inhabilitada (DISABLED).

Separar el contenedor de habilidades de sus instantáneas de revisión de habilidades proporciona los siguientes beneficios:

  • Ejecución determinística: Los agentes fijados a una revisión específica están protegidos contra cambios inesperados en las instrucciones o actualizaciones de secuencias de comandos.
  • Reversiones controladas: Puedes subir y verificar revisiones de habilidades nuevas o revertir el puntero defaultRevision a una revisión anterior si se produce un problema.
  • Auditabilidad: Las revisiones históricas del paquete de habilidades se conservan y se pueden inspeccionar hasta que se borren de forma explícita.

Para obtener instrucciones sobre cómo subir, descargar y borrar revisiones, consulta Administra las revisiones de habilidades.

Especificación del paquete

Las habilidades independientes se empaquetan como archivos ZIP que cumplen con la especificación de habilidades para agentes de estándar abierto.

El archivo debe contener un archivo SKILL.md en su raíz, así como cualquier secuencia de comandos o recurso de metadatos que requiera la habilidad. El archivo SKILL.md define las instrucciones para la habilidad. Este archivo combina metadatos de YAML, como name y description, con instrucciones en lenguaje natural interpretadas por los Agent Runtime y referencias a cualquier secuencia de comandos opcional o recurso de apoyo en el archivo.

Cuando registras una habilidad o creas una revisión, Agent Registry valida el archivo con las restricciones de carga útil de transferencia, analiza el archivo SKILL.md y, luego, indexa sus metadatos para la búsqueda y el descubrimiento.

Estados del ciclo de vida de las habilidades

Para controlar cómo se resuelve y descarga una habilidad independiente en el entorno de ejecución, puedes realizar la transición del targetState del contenedor de habilidades en cuatro estados:

  • Activa (ACTIVE): La habilidad se publica, se indexa para el descubrimiento y está disponible para la resolución del entorno de ejecución y las descargas de cargas útiles. Para establecer una habilidad como Activa, se requiere que su puntero defaultRevision haga referencia a un recurso SkillRevision activo.
  • Inhabilitada (DISABLED): Es el estado inicial predeterminado cuando se crea una habilidad. La habilidad no se entrega en el entorno de ejecución, y las descargas de resolución y carga útil fallan de inmediato. Una habilidad también pasa al estado Inhabilitada si se borra su puntero defaultRevision o si se borra su revisión predeterminada. A diferencia del estado Retirado, puedes habilitar una habilidad inhabilitada estableciendo un defaultRevision válido y actualizando su estado objetivo a Activo.
  • Obsoleto (DEPRECATED): La habilidad se puede resolver y descargar, pero indica a los consumidores que se retirará.
  • Retirada (DECOMMISSIONED): Es un estado final en el que la habilidad se desactiva de forma permanente, ya no se entrega y no se puede revertir a Activa ni a ningún otro estado. Una habilidad solo se puede retirar después de que se haya marcado como obsoleta.

Puedes actualizar el estado del ciclo de vida de una habilidad con la consola de Google Cloud , Google Cloud CLI o la API de Agent Registry sin borrar las revisiones históricas. Para descargar la carga útil ZIP de una revisión, la habilidad superior debe estar en el estado Activo o Obsoleto, y la revisión en sí debe estar en el estado Activo. Para obtener instrucciones paso a paso, consulta Administra los estados del ciclo de vida de las habilidades.

Diferencias entre las habilidades independientes y las de A2A

Agent Registry admite habilidades independientes y habilidades de A2A intercaladas. En la siguiente tabla, se comparan sus características:

Característica Habilidad independiente Habilidad de A2A intercalada
Tipo de recurso Recurso Skill de nivel superior en el Registro de agentes con recursos SkillRevision secundarios. Es un array anidado dentro del recurso Agent.
Contenido del paquete Es un archivo ZIP que contiene SKILL.md, secuencias de comandos opcionales y recursos de apoyo. Es el objeto JSON de la tarjeta del agente que contiene id, name y description.
Modelo de control de versiones Instantáneas de revisión de habilidades inmutables con un puntero defaultRevision configurable. Se vincula directamente con las actualizaciones del agent-card.json del agente.
Modelo de ejecución Se descargan y cargan en el contexto o el entorno de ejecución de un agente. Anuncia las capacidades de tareas para la delegación entre agentes.
Especificación Especificación de habilidades de agentes. Especificación de Agent2Agent (A2A).
Alcance de la administración Se rige en todos los proyectos de forma independiente de las implementaciones de agentes individuales. Se acopla al ciclo de vida de la implementación del agente host.

¿Qué sigue?