Administrar habilidades

Después de registrar una habilidad independiente en Agent Registry, puedes ver sus detalles, actualizar su descripción, anular su puntero de revisión activo (default_revision), administrar sus estados del ciclo de vida o borrarla de Agent Registry. También puedes enumerar y ver las habilidades creadas por Google, que son visibles de inmediato cuando configuras el Registro de agentes.

En este documento, se explica cómo realizar estas tareas administrativas.

Antes de comenzar

Antes de comenzar, configura Agent Registry y registra una habilidad independiente. Necesitas el ID del proyecto para realizar estas tareas.

Para usar los comandos de Google Cloud CLI en este documento, asegúrate de haber configurado tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para administrar habilidades en el Registro de agentes, pídele a tu administrador que te otorgue el rol de IAM Usuario del Registro de agentes (roles/agentregistry.user) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Enumera y visualiza habilidades

Puedes explorar todas las habilidades registradas o buscar capacidades específicas:

Console

  1. En la Google Cloud consola, ve a la página Registro de agentes:

    Ir al Registro de agentes

  2. Selecciona la pestaña Habilidades.
  3. Revisa la lista de habilidades. Puedes filtrar la visualización con los menús Ubicación o Estado.
  4. Haz clic en cualquier nombre de habilidad para abrir su página Detalles de la habilidad , que muestra el nombre, la descripción, la versión activa, el URN de la habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.

gcloud

Para enumerar todas las habilidades en una ubicación, haz lo siguiente:

gcloud alpha agent-registry skills list \
  --project=PROJECT_ID \
  --location=LOCATION

Para ver los detalles de una habilidad específica, haz lo siguiente:

gcloud alpha agent-registry skills describe SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

Reemplaza lo siguiente:

  • SKILL_ID: Es el ID de la habilidad que deseas revisar.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.

REST

Para recuperar la lista de todas las habilidades, haz lo siguiente:

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

Para recuperar un solo contenedor de habilidades, haz lo siguiente:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID de la habilidad que deseas revisar.

Actualiza los metadatos de la habilidad o la revisión predeterminada

Puedes modificar el nombre visible o la descripción de una habilidad, o bien cambiar de forma manual el puntero de revisión predeterminado para implementar una versión diferente. Para crear revisiones de habilidades nuevas, consulta Administra las revisiones de habilidades.

Para actualizar los metadatos de la habilidad o la revisión predeterminada de una habilidad en particular, sigue estos pasos:

Console

  1. En la Google Cloud consola, ve a la página Registro de agentes:

    Ir al Registro de agentes

  2. Selecciona la pestaña Habilidades.
  3. Revisa la lista de habilidades. Puedes filtrar la visualización con los menús Ubicación o Estado.
  4. Haz clic en cualquier nombre de habilidad para abrir su página Detalles de la habilidad , que muestra el nombre, la descripción, la versión activa, el URN de la habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.

  5. Elige una de las siguientes opciones:

    • Actualizar metadatos de la habilidad:

      1. Haz clic en Editar.
      2. En el panel Editar habilidad, actualiza el nombre visible o la descripción de tu habilidad.
      3. Haz clic en Guardar.

    • Actualizar la revisión predeterminada:

      1. Ubica la tabla Historial de versiones.
      2. Busca la revisión que deseas establecer como activa.
      3. En la columna de acciones, haz clic en Activar versión.

gcloud

  • Para actualizar los metadatos de una habilidad, haz lo siguiente:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION"

  • Para actualizar la revisión de entrega predeterminada de una habilidad, haz lo siguiente:

    gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Reemplaza lo siguiente:

  • SKILL_ID: Es el ID de la habilidad que deseas actualizar.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • DISPLAY_NAME: Es el nombre visible actualizado.
  • DESCRIPTION: Es la descripción actualizada.
  • REVISION_ID: Es el ID de la revisión de la habilidad que deseas establecer como predeterminada.

REST

Envía una solicitud PATCH en la que se especifiquen los campos que deseas actualizar:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

Reemplaza lo siguiente:

  • DISPLAY_NAME: Es el nombre visible actualizado de la habilidad.
  • DESCRIPTION: Es la descripción actualizada de la habilidad.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID de la habilidad que deseas actualizar.
  • REVISION_ID: Es el ID de la revisión de la habilidad que deseas activar.

Administra los estados del ciclo de vida de las habilidades

Para controlar cómo se resuelve una habilidad en el tiempo de ejecución, puedes cambiar el estado de destino de la habilidad:

  • Borrador: La habilidad está en su fase inicial de creación o desarrollo. No se entrega en el tiempo de ejecución y se bloquean las descargas de cargas útiles. Puedes modificar la configuración y las cargas útiles de la habilidad libremente en este estado antes de promover la habilidad al estado de destino Activo.
  • Activo: La habilidad se entrega y se puede resolver por completo.
  • Inhabilitado: La resolución de la habilidad falla de inmediato y se bloquean las descargas. A diferencia del estado Retirado, puedes volver a habilitar la habilidad más adelante, lo que significa que volverá al estado de destino Activo.
  • Obsoleto: La habilidad sigue siendo cargable, pero muestra encabezados de advertencia que indican que se retirará.
  • Retirado: La habilidad se desactiva de forma permanente, ya no se entrega y no se puede revertir a Activo ni a ningún otro estado. Una habilidad solo se puede retirar después de que ya se haya declarado obsoleta. Proporciona tiempo suficiente para migrar antes de retirar la habilidad. Este es un estado terminal, que se recomienda usar con extrema precaución.

Para realizar la transición del estado del ciclo de vida de una habilidad, haz lo siguiente:

Console

  1. En la Google Cloud consola, ve a la página Registro de agentes:

    Ir al Registro de agentes

  2. Selecciona la pestaña Habilidades.
  3. Revisa la lista de habilidades. Puedes filtrar la visualización con los menús Ubicación o Estado.
  4. Haz clic en cualquier nombre de habilidad para abrir su página Detalles de la habilidad , que muestra el nombre, la descripción, la versión activa, el URN de la habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.
  5. Usa los botones de control de estado para realizar la transición del estado de destino. Los botones que muestra la página dependen del estado actual de la habilidad, por ejemplo, Habilitar, Inhabilitar, Declarar obsoleto o Retirar.

gcloud

Actualiza el contenedor de habilidades con la marca --target-state:

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --target-state=DISABLED

Los valores permitidos para el estado de destino son los siguientes:

  • DRAFT
  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED.

REST

Envía una solicitud PATCH en la que se especifique targetState en el cuerpo y en la máscara de actualización:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "targetState": "TARGET_STATE_DISABLED"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

Los valores permitidos para el estado de destino son los siguientes:

  • TARGET_STATE_DRAFT
  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED.

Borra una habilidad

Si borras un contenedor de habilidades, se borrará de forma permanente el contenedor de habilidades y todo el historial de versiones SkillRevision inmutable asociado. Los agentes que intenten resolver el URN de la habilidad borrada fallarán en el tiempo de ejecución.

Console

  1. En la Google Cloud consola, ve a la página Registro de agentes:

    Ir al Registro de agentes

  2. Selecciona la pestaña Habilidades.
  3. Revisa la lista de habilidades. Puedes filtrar la visualización con los menús Ubicación o Estado.
  4. Haz clic en el nombre de la habilidad que deseas borrar.
  5. En la página Detalles de la habilidad, haz clic en Borrar.
  6. En el diálogo de confirmación, ingresa DELETE y haz clic en Borrar.

gcloud 

gcloud alpha agent-registry skills delete SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION

REST 

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?force=true"

¿Qué sigue?