Administrar habilidades

Agent Registry te permite inspeccionar, actualizar y administrar habilidades independientes para que puedas controlar qué versiones de habilidades y estados del ciclo de vida están disponibles para tus agentes. Después de registrar una habilidad independiente, puedes ver sus detalles, actualizar su descripción o revisión predeterminada, cambiar su estado de ciclo de vida o borrarla del Registro de agentes. También puedes enumerar y ver las habilidades administradas por Google, que están disponibles en cuanto configuras el Registro de agentes.

Antes de comenzar

  1. Configura el Registro de agentes.

  2. Obtén el ID del proyecto para el proyecto de administración en el que está habilitado el Registro de agentes.

  3. Registra una habilidad independiente.

  4. Para usar los comandos de Google Cloud CLI en este documento, configura tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para administrar las habilidades en el Registro de agentes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto de administración en el que está habilitado el Registro de agentes:

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 a través de roles personalizados o cualquier otro rol predefinido.

Otros roles de Agent Registry también pueden incluir los permisos necesarios para ver, actualizar y borrar habilidades. Para obtener más información, consulta Roles y permisos de Agent Registry.

Enumera y visualiza habilidades

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

Console

  1. En la consola de Google Cloud , 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 identificador de habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.

gcloud

Para enumerar todas las habilidades en una ubicación, usa el comando gcloud alpha agent-registry skills list:

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

Para ver los detalles de una habilidad específica, usa el comando gcloud alpha agent-registry skills describe:

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. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.

REST

Para recuperar la lista de todas las habilidades, envía una solicitud GET:

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, envía una solicitud GET:

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. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.

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

Puedes modificar el nombre visible o la descripción de una habilidad, o 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 una habilidad o la revisión predeterminada de una habilidad en particular, sigue estos pasos:

Console

  1. En la consola de Google Cloud , 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 identificador de habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.

  5. Elige entre las siguientes opciones:

    • Actualiza los 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.

    • Actualiza la revisión predeterminada:

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

gcloud

  • Para actualizar los metadatos de una habilidad, usa el comando gcloud alpha agent-registry skills update:

    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, usa el comando gcloud alpha agent-registry skills update y especifica el nombre del recurso de la revisión de destino:

    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 quieres actualizar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • 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 quieres 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 quieres actualizar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • 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 entorno de ejecución, puedes cambiar el estado objetivo de la habilidad:

  • Activa: La habilidad se publica y se puede resolver por completo. Para establecer una habilidad como Activa, se requiere que su campo defaultRevision apunte a una revisión de habilidad activa.
  • Inhabilitada: Es el estado inicial predeterminado cuando se crea una habilidad. La habilidad no se entrega en el entorno de ejecución, la resolución de la habilidad falla de inmediato y se bloquean las descargas de la carga útil. Una habilidad también se coloca en el 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.
  • Obsoleta: La habilidad se puede seguir cargando y descargando, pero indica que se retirará.
  • Retirada: La habilidad se desactiva de forma permanente, ya no se publica y no se puede revertir a Activa ni a ningún otro estado. Una habilidad solo se puede retirar después de que ya se haya dejado de usar. Proporciona tiempo suficiente para migrar antes de dar de baja la habilidad. Como este estado es terminal, úsalo con precaución.

Para cambiar el estado del ciclo de vida de una habilidad, sigue estos pasos:

Console

  1. En la consola de Google Cloud , 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 identificador de habilidad, la última actualización, los metadatos personalizados y el historial de revisiones.
  5. Usa los botones de control de estado para cambiar el estado de destino. Los botones que muestra la página dependen del estado actual de la habilidad, por ejemplo, Habilitar, Inhabilitar, Obsoleto o Retirar.

gcloud

Actualiza el contenedor de habilidades con el comando gcloud alpha agent-registry skills update y la marca --target-state:

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

Reemplaza lo siguiente:

  • SKILL_ID: Es el ID de la habilidad que quieres actualizar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.

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

  • ACTIVE
  • DISABLED
  • DEPRECATED
  • DECOMMISSIONED

REST

Envía una solicitud PATCH que especifique el 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"

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 quieres actualizar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.

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

  • TARGET_STATE_ACTIVE
  • TARGET_STATE_DISABLED
  • TARGET_STATE_DEPRECATED
  • TARGET_STATE_DECOMMISSIONED

Cómo borrar una habilidad

Si borras un contenedor de habilidades, se borra de forma permanente el recurso Skill y todos los recursos SkillRevision inmutables asociados. Los agentes que intentan resolver el identificador de habilidad borrado fallan en el entorno de ejecución.

Console

  1. En la consola de Google Cloud , 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 quieras 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

Para borrar una habilidad, usa el comando gcloud alpha agent-registry skills delete:

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

Reemplaza lo siguiente:

  • SKILL_ID: Es el ID de la habilidad que deseas borrar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.

REST

Para borrar una habilidad, envía una solicitud DELETE:

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"

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 borrar. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.

¿Qué sigue?