Administra las revisiones de habilidades

En Agent Registry, una revisión de habilidades representa una instantánea inmutable y versionada de un paquete de habilidades. Cuando actualizas el código o las instrucciones de una habilidad, creas una revisión nueva. Esta arquitectura desacoplada permite el control de versión de tus habilidades.

En este documento, se explica cómo crear y administrar revisiones de habilidades. Para obtener información sobre cómo actualizar la revisión predeterminada de una habilidad específica, consulta Actualiza los metadatos de la habilidad o la revisión predeterminada.

Antes de comenzar

Antes de comenzar, configura Agent Registry y registra una habilidad independiente. Necesitarás 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 las revisiones de habilidades en Agent Registry, pídele a tu administrador que te otorgue el rol de IAM de usuario de Agent Registry (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.

Crea una revisión de habilidades

Cuando creas una revisión nueva, se sube una nueva carga útil ZIP al contenedor de habilidades existente. Cuando creas una revisión de habilidades, se convierte automáticamente en la versión activa de la habilidad. Sin embargo, puedes actualizar la revisión predeterminada de una habilidad en cualquier momento. Solo se pueden descargar las revisiones que están activas.

El tamaño máximo del archivo ZIP de una revisión de habilidades es de 500 KB.

Console

  1. En la Google Cloud consola, ve a la Agent Registry página:

    Ir a Agent Registry

  2. Selecciona la pestaña Habilidades y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, ubica la tabla Historial de versiones.
  4. Haz clic en Agregar versión.

  5. En el panel Agregar versión, elige una de las siguientes opciones:

    • Archivo: Sube el paquete o el archivo ZIP que contiene tu código o el archivo de instrucciones (SKILL.md). Puedes hacer clic en Explorar para encontrar tu archivo en tu entorno local.

    • Bucket: Proporciona un URI de Cloud Storage (gs://...) que contenga un paquete ZIP válido. Puedes hacer clic en Explorar para encontrar tu archivo en tus buckets de Cloud Storage.

  6. Haz clic en Crear.

En la página Detalles de la habilidad , se muestra la revisión de habilidades en la tabla Historial de versiones.

gcloud

Puedes crear una revisión de habilidades subiendo un archivo ZIP local o importando un paquete almacenado en Cloud Storage.

Reemplaza lo siguiente:

  • REVISION_ID: El ID que deseas asignar a la revisión de habilidades
  • SKILL_ID: El ID de la habilidad que usas para la revisión
  • PROJECT_ID: El ID del proyecto

  • LOCATION: La ubicación del registro

  • Sube un archivo ZIP local: Para crear una revisión de habilidades con una carga útil ZIP local , haz lo siguiente:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --payload="LOCAL_ZIP_PATH"

    Reemplaza LOCAL_ZIP_PATH por la ruta de acceso al archivo de habilidades empaquetado en tu máquina local.

  • Importa desde un bucket de Cloud Storage: Para crear una revisión de habilidades con un archivo ZIP alojado en un bucket de Cloud Storage, haz lo siguiente:

    gcloud alpha agent-registry skills revisions create REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    Reemplaza lo siguiente:

    • BUCKET_NAME: El nombre del bucket de Cloud Storage que contiene el paquete ZIP
    • SKILL_PACKAGE: El nombre del paquete de habilidades que contiene la revisión de habilidades

REST

Para crear una revisión de habilidades, envía una solicitud POST a la colección de revisiones. Puedes subir la carga útil ZIP directamente o dirigirla a una ruta de Cloud Storage.

  • Sube un archivo ZIP local: Especifica archiveUploadSource que contenga los bytes ZIP codificados en base64 en el cuerpo de la solicitud. Puedes usar el comando base64 intercalado en curl:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "archiveUploadSource": {
          "archiveContent": "$(base64 -w0 local_skill.zip)"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

  • Importa desde un bucket de Cloud Storage: Especifica gcsSource en el cuerpo de la solicitud que dirija a la ruta de tu bucket:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • LOCATION: La ubicación del registro
  • SKILL_ID: El ID del contenedor de habilidades
  • REVISION_ID: El ID que deseas asignar a esta revisión
  • BUCKET_NAME: El nombre del bucket de Cloud Storage que contiene el archivo ZIP
  • SKILL_PACKAGE: El nombre del paquete ZIP

Enumera y describe revisiones

Puedes ver la lista de todas las revisiones de una habilidad y revisar sus metadatos. Si deseas actualizar la revisión predeterminada de una habilidad, consulta Actualiza los metadatos de la habilidad o la revisión predeterminada.

Para enumerar y ver los detalles de una revisión, sigue estos pasos:

Console

  1. En la Google Cloud consola, ve a la Agent Registry página:

    Ir a Agent Registry

  2. Selecciona la pestaña Habilidades y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, ubica la tabla Historial de versiones.
  4. Revisa los IDs de versión, la hora de creación, el estado de la revisión y las acciones disponibles.

gcloud

Para enumerar todas las revisiones de una habilidad, haz lo siguiente:

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

Para describir los metadatos de una revisión específica, haz lo siguiente:

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

REST

Para enumerar revisiones, 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/revisions"

Para obtener metadatos de una sola revisión, 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/revisions/REVISION_ID"

Descarga la carga útil de la revisión

Puedes descargar la carga útil del archivo ZIP compilado de una revisión específica para la verificación o depuración local.

Para descargar la carga útil, se deben cumplir las siguientes condiciones:

Para descargar la carga útil de la revisión de una revisión activa, sigue estos pasos:

Console

  1. En la Google Cloud consola, ve a la Agent Registry página:

    Ir a Agent Registry

  2. Selecciona la pestaña Habilidades y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, ubica la tabla Historial de versiones.
  4. Busca la revisión que deseas descargar.
  5. En la columna de acciones, haz clic en Descargar. La carga útil ZIP se descarga en tu máquina local.

gcloud

Para descargar la carga útil del archivo de una revisión, ejecuta el comando describe con la marca --alt=media y redirecciona el resultado a un archivo:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
  --skill=SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --flags="alt=media" > skill_payload.zip

REST

Envía una solicitud GET a la URL del recurso de la revisión y agrega el parámetro de consulta alt=media. Debes usar la marca -L con curl para seguir las transmisiones de redireccionamiento HTTP:

curl -L -X GET \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -o skill_payload.zip \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

Borra una revisión específica

Cuando borras una revisión específica, se quita su carga útil ZIP y el historial de metadatos de Agent Registry.

Por lo general, el borrado de revisiones individuales está restringido a los administradores. No puedes borrar una revisión que esté establecida como la revisión predeterminada de la habilidad. Para actualizar la revisión predeterminada de una habilidad, consulta Actualiza los metadatos de la habilidad o la revisión predeterminada.

Para borrar una revisión específica, sigue estos pasos:

Console

  1. En la Google Cloud consola, ve a la Agent Registry página:

    Ir a Agent Registry

  2. Selecciona la pestaña Habilidades y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, ubica la tabla Historial de versiones.
  4. Busca la revisión que deseas borrar.
  5. En la columna de acciones, haz clic en Borrar y confirma la acción.

gcloud 

gcloud alpha agent-registry skills revisions delete REVISION_ID \
  --skill=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/revisions/REVISION_ID"

¿Qué sigue?