Administra las revisiones de habilidades

En Agent Registry, las revisiones de habilidades te permiten controlar las versiones de tus habilidades independientes como instantáneas inmutables sin interrumpir a los agentes activos. Cada habilidad tiene una revisión predeterminada y puede contener varias revisiones de habilidades con versiones. Cuando actualizas las instrucciones o las secuencias de comandos opcionales de una habilidad, puedes crear, enumerar, inspeccionar, descargar y borrar revisiones de habilidades en Agent Registry. Para obtener información sobre cómo actualizar la revisión predeterminada de una habilidad, consulta Actualiza los metadatos de la habilidad o la revisión predeterminada.

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 revisiones de 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, descargar, crear, actualizar y borrar revisiones de habilidades. Para obtener más información, consulta Roles y permisos de Agent Registry.

Crea una revisión de habilidad

Cuando creas una revisión nueva, se sube una carga útil de ZIP nueva al contenedor de habilidad existente. Cuando la validación se completa correctamente, la revisión ingresa al estado Activa. Para entregar la revisión nueva como la revisión predeterminada de la habilidad, actualiza la revisión predeterminada de la habilidad para que apunte a la revisión activa nueva. Solo se pueden descargar las revisiones en estado Activo.

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

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

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 y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, 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 archivo de instrucciones de SKILL.md y las secuencias de comandos opcionales. Puedes hacer clic en Explorar para encontrar el archivo en tu entorno local.

    • Bucket: Proporciona un URI de Cloud Storage de gs://... que contenga un paquete ZIP válido. Puedes hacer clic en Explorar para encontrar el 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 la habilidad en la tabla Historial de versiones.

gcloud

Para crear una revisión de habilidad, puedes subir un archivo ZIP local o importar un paquete almacenado en Cloud Storage.

Reemplaza lo siguiente:

  • REVISION_ID: Es el ID que deseas asignar a la revisión de la habilidad.
  • SKILL_ID: Es el ID de la habilidad que usas para la revisión. 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.

  • Sube un archivo ZIP local: Para crear una revisión de habilidad con una carga útil de ZIP local, ejecuta el comando gcloud alpha agent-registry skills revisions create:

    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 habilidad empaquetado en tu máquina local.

  • Importa desde un bucket de Cloud Storage: Para crear una revisión de habilidad con un archivo ZIP alojado en un bucket de Cloud Storage, ejecuta el comando gcloud alpha agent-registry skills revisions create:

    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: 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 apuntar a una ruta de acceso 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 apunta a la ruta de acceso del 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: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID del contenedor de habilidades. Para las habilidades registradas de forma manual, incluye el prefijo private-, como private-my-skill.
  • REVISION_ID: Es el ID que deseas asignar a esta revisión.
  • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que contiene el archivo ZIP.
  • SKILL_PACKAGE: Es el nombre del paquete ZIP.

Enumera y describe revisiones

Puedes ver la lista de todas las revisiones de una habilidad y, además, inspeccionar 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 consola de Google Cloud , ve a la página Registro de agentes:

    Ir al registro de agentes

  2. Selecciona la pestaña Habilidades y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, busca 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, ejecuta el comando gcloud alpha agent-registry skills revisions list:

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, ejecuta el comando gcloud alpha agent-registry skills revisions describe:

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

Reemplaza lo siguiente:

  • SKILL_ID: Es el ID del contenedor de habilidades. 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.
  • REVISION_ID: Es el ID de la revisión de la habilidad.

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 los 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID del contenedor de habilidades. 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.

Descarga la carga útil de la revisión

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

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

Para descargar la carga útil de una revisión activa, 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 y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, busca la tabla Historial de versiones.
  4. Busca la revisión que quieras descargar.
  5. En la columna Acciones, haz clic en Descargar. La carga útil ZIP se descarga en tu máquina local.

gcloud

Para descargar la carga útil de archivo de una revisión, ejecuta el comando gcloud alpha agent-registry skills revisions download y especifica la ruta de acceso de destino:

gcloud alpha agent-registry skills revisions download REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --destination="./skill_payload.zip"

Reemplaza lo siguiente:

  • REVISION_ID: Es el ID de la revisión de la habilidad que se descargará.
  • SKILL_ID: Es el ID del contenedor de habilidades. 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

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID del contenedor de habilidades. 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 se descargará.

Borra una revisión específica

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

Por lo general, solo los administradores pueden borrar revisiones individuales. Si borras la revisión que se estableció como la revisión predeterminada de la habilidad, Agent Registry borra el puntero defaultRevision y cambia una habilidad Activa al estado Inhabilitada. Para mantener la habilidad activa, actualiza la revisión predeterminada de la habilidad para que apunte a otra revisión activa antes de borrar la revisión predeterminada anterior.

Para borrar una revisión específica, 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 y haz clic en el nombre de tu habilidad.
  3. En la página Detalles de la habilidad, busca la tabla Historial de versiones.
  4. Busca la revisión que quieres borrar.
  5. En la columna Acciones, haz clic en Borrar y confirma la acción.

gcloud

Para borrar una revisión, ejecuta el comando gcloud alpha agent-registry skills revisions delete:

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

Reemplaza lo siguiente:

  • REVISION_ID: Es el ID de la revisión de la habilidad que se borrará.
  • SKILL_ID: Es el ID del contenedor de habilidades. 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 revisión, 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/revisions/REVISION_ID"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • LOCATION: Es la ubicación del registro.
  • SKILL_ID: Es el ID del contenedor de habilidades. 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 se borrará.

¿Qué sigue?