Administra las revisiones de habilidades

Vista previa

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En Agent Registry, una revisión de habilidad representa una instantánea inmutable y versionada de un paquete de habilidad. Cuando actualizas el código o las instrucciones de una skill, 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 o la revisión predeterminada de una habilidad.

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 configurar 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 los siguientes roles de IAM en el proyecto:

• Enumera, visualiza y descarga revisiones de habilidades: Visualizador de la API de Agent Registry (roles/agentregistry.viewer)
• Crear, actualizar y borrar revisiones de habilidades: Usuario del Registro de agentes (roles/agentregistry.user)
• Administra revisiones de habilidades y otros recursos de Agent Registry: Editor de la API de Agent Registry (roles/agentregistry.editor)

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 del Agent Registry también pueden incluir los permisos necesarios para ver, descargar, crear, actualizar y borrar revisiones de habilidades. Para obtener más información, consulta Roles y permisos del Registro de agentes.

Cómo crear una revisión de habilidad

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

Para obtener información sobre los precios y los costos de las funciones de las habilidades, consulta los precios de Agent Registry.

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

Console

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

   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 skill, busca 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 buscar 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 buscar tu archivo en tus buckets de Cloud Storage.

     Importante: Antes de que Agent Registry pueda acceder a los archivos de tu skill, debes otorgarle acceso al agente de servicio al archivo ZIP en tu bucket de Cloud Storage. El agente de servicio de Agent Registry usa el siguiente formato: [e-mail]. Si este agente de servicio no existe en tu proyecto, por ejemplo, si nunca creaste una habilidad, activa su creación para la API de Agent Registry siguiendo los pasos que se indican en Crea agentes de servicio y otórgales roles. El agente de servicio requiere el permiso storage.objects.get en el bucket de Cloud Storage que contiene tu archivo ZIP. Si quieres obtener instrucciones para otorgar permisos de IAM en recursos de bucket, consulta IAM para Cloud Storage.

6. Haz clic en Crear.

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

gcloud

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

Reemplaza lo siguiente:

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

• LOCATION: Es la ubicación del registro.

• Sube un archivo ZIP local: Para crear una revisión de habilidad 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 la skill empaquetada en tu máquina local.

• Importar desde un bucket de Cloud Storage: Para crear una revisión de habilidad 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"
  

  Importante: Antes de que Agent Registry pueda acceder a los archivos de tu habilidad, debes otorgarle acceso al agente de servicio al archivo ZIP en tu bucket de Cloud Storage. El agente de servicio de Agent Registry usa el siguiente formato: [e-mail]. Si este agente de servicio no existe en tu proyecto, por ejemplo, si nunca creaste una habilidad, activa su creación para la API de Agent Registry siguiendo los pasos que se indican en Crea agentes de servicio y otórgales roles. El agente de servicio requiere el permiso storage.objects.get en el bucket de Cloud Storage que contiene tu archivo ZIP. Si quieres obtener instrucciones para otorgar permisos de IAM en recursos de bucket, consulta IAM para Cloud Storage.

  Reemplaza lo siguiente:

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

REST

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

• Sube un archivo ZIP local: Especifica archiveUploadSource que contiene los bytes del archivo 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"
  

• Importar desde un bucket de Cloud Storage: Especifica gcsSource en el cuerpo de la solicitud que apunta a la ruta de acceso 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"
  

Importante: Antes de que Agent Registry pueda acceder a los archivos de tu habilidad, debes otorgarle acceso al agente de servicio al archivo ZIP en tu bucket de Cloud Storage. El agente de servicio de Agent Registry usa el siguiente formato: [e-mail]. Si este agente de servicio no existe en tu proyecto, por ejemplo, si nunca creaste una habilidad, activa su creación para la API de Agent Registry siguiendo los pasos que se indican en Crea agentes de servicio y otórgales roles. El agente de servicio requiere el permiso storage.objects.get en el bucket de Cloud Storage que contiene tu archivo ZIP. Si quieres obtener instrucciones para otorgar permisos de IAM en recursos de bucket, consulta IAM para Cloud Storage.

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto
• LOCATION: Es la ubicación del registro.
• SKILL_ID: Es el ID del contenedor de la skill.
• REVISION_ID: Es 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: Es el nombre del paquete ZIP.

Enumera y describe las revisiones

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

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

Console

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

   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 skill, busca la tabla Historial de versiones.
4. Revisa los IDs de versión, la hora de creación, el estado de revisión y las acciones disponibles.

gcloud

Para enumerar todas las revisiones de una skill, 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 las 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 realizar la verificación o depuración local.

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

• Skill: La skill debe estar en estado Active o Deprecated. Para cambiar el estado objetivo de la habilidad, consulta Administra los estados del ciclo de vida de la habilidad.
• Revisión de habilidades: La revisión debe estar en estado Activo. No se pueden descargar las revisiones en los estados Failed o Creating. Para revisar el estado de una revisión de habilidad, enumera y describe las revisiones. Puedes actualizar la revisión predeterminada de una skill para activar una revisión específica.

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

Console

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

   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 skill, busca la tabla Historial de versiones.
4. Busca la revisión que quieras 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 los flujos 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"

Cómo borrar una revisión específica

Si borras una revisión específica, se quitarán su carga útil ZIP y su historial de metadatos de Agent Registry.

Por lo general, solo los administradores pueden borrar revisiones individuales. No puedes borrar una revisión que esté establecida como la revisión predeterminada de la skill. Para actualizar la revisión predeterminada de una skill, consulta Actualiza los metadatos o la revisión predeterminada de una skill.

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

Console

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

   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 skill, busca la tabla Historial de versiones.
4. Busca la revisión que quieres 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?

• Obtén más información para explorar publicadores verificados.
• Comprende las cuotas y los límites para las revisiones de habilidades.