Registra habilidades

En Agent Registry, una habilidad representa una capacidad ejecutable y autónoma que puede tener un agente. Contiene instrucciones en un archivo SKILL.md, secuencias de comandos de código y recursos que extienden el razonamiento de un agente. Si registras habilidades independientes en Agent Registry, puedes controlar, versionar y compartir capacidades de forma centralizada en los agentes de IA de tu organización.

Las habilidades creadas por Google se muestran de inmediato cuando configuras Agent Registry. En este documento, se explica cómo registrar manualmente tus propias habilidades independientes en Agent Registry.

Antes de comenzar

Antes de comenzar, configura Agent Registry. 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 registrar 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.

Restricciones de carga útil de la ingesta

Para registrar una habilidad, debes empaquetar los archivos fuente de la capacidad en un archivo ZIP. El archivo debe incluir un archivo de instrucciones SKILL.md en su raíz. Durante la fase de ingesta del proceso de registro de habilidades, Agent Registry valida que la carga útil cumpla con las siguientes restricciones:

  • Tamaño del archivo ZIP: Tamaño máximo del archivo comprimido de 500 KB
  • Tamaño total de la carga útil sin comprimir: Tamaño máximo sin comprimir de 10 MB
  • Tamaño de archivo individual: Tamaño máximo sin comprimir de 1 MB por archivo
  • Anidación profunda: Profundidad máxima de anidación de directorios de 8 niveles
  • Cumplimiento de la especificación: El archivo SKILL.md debe contener una sección de metadatos iniciales de YAML válida que defina el nombre, la descripción y los metadatos tal como se definen en la Especificación de habilidades del agente.

Registra una habilidad

Las habilidades creadas por Google se muestran de inmediato cuando configuras Agent Registry. Sin embargo, también puedes registrar tus propias habilidades de forma manual. Cada habilidad tiene una revisión predeterminada y puede contener varias revisiones de habilidades versionadas .

Para registrar tus propias habilidades, crea un contenedor de habilidades lógicas y sube la carga útil de la revisión inicial en una sola operación. Más adelante, podrás administrar tus habilidades registradas y sus posteriores revisiones de habilidades.

Las habilidades que tú u otros usuarios creen se asignan automáticamente al publicador private predeterminado para evitar conflictos de nombres con las habilidades creadas por Google. Por ese motivo, el ID publicado de una habilidad en particular se convierte en private-SKILL_ID. No puedes especificar un publicador personalizado durante la creación de habilidades.

Por ejemplo, si creas una habilidad con el ID workspace-tools, el nombre del recurso se crea como projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools. El nombre de recurso uniforme (URN) lógico se asigna como urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Debes usar este ID publicado (private-workspace-tools) para todas las operaciones de habilidades posteriores.

Para registrar una habilidad, sigue estos pasos:

Console

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

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona tu Google Cloud proyecto.

  3. Selecciona la pestaña Habilidades.

  4. En la pestaña Habilidades, el botón Agregar habilidad muestra dos opciones. Puedes elegir una de las siguientes opciones:

    • Agregar habilidad: Crea un nuevo contenedor de habilidad en el registro. De manera opcional, puedes subir un paquete de habilidades para crear la primera revisión.
    • Importar habilidad: Sube un paquete ZIP que contenga tu código o el archivo de instrucciones (SKILL.md) para incorporar un nuevo paquete de habilidades personalizadas.

  5. En el panel Crear habilidad o Importar habilidad, especifica los siguientes detalles:

    • Nombre visible: Ingresa un nombre fácil de usar para la habilidad.
    • Descripción: Ingresa un breve resumen que explique las capacidades de la habilidad.
    • Ubicación: Selecciona la región geográfica, por ejemplo, global, us o eu.

  6. En la sección Fuente de carga útil, elige una de las siguientes opciones:

    • Archivo: Arrastra el archivo ZIP de la habilidad empaquetada o explora tu directorio local.

    • Bucket: Ingresa la ruta de acceso a tu archivo ZIP almacenado en un bucket de Cloud Storage, en el formato gs://BUCKET_NAME/SKILL_PACKAGE.zip.

  7. Haz clic en Crear.

Se creó tu habilidad. Para todas las operaciones de habilidades posteriores, consulta tu habilidad como private-SKILL_ID, como se muestra en la Google Cloud consola.

gcloud

Para registrar una habilidad y subir su carga útil inicial, puedes subir un archivo ZIP local o importar un paquete almacenado en Cloud Storage.

Reemplaza lo siguiente:

  • SKILL_ID: El ID del recurso de la habilidad, por ejemplo, workspace-docs-skill. Después de la creación, el registro antepone automáticamente el prefijo private-. Debes usar el ID con prefijo en todos los comandos de habilidades posteriores, por ejemplo, private-workspace-docs-skill.
  • PROJECT_ID: El ID del proyecto
  • LOCATION: La región geográfica, por ejemplo, global, us o eu
  • DISPLAY_NAME: Un nombre fácil de usar para la habilidad

  • DESCRIPTION: Un breve resumen que explica las capacidades de la habilidad

  • Sube un archivo ZIP local: Para registrar una habilidad con una carga útil ZIP local:

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

    Reemplaza LOCAL_ZIP_PATH por la ruta de acceso al archivo de habilidades empaquetado en tu máquina local, por ejemplo, ./workspace-docs-skill.zip.

  • Importa desde un bucket de Cloud Storage: Para registrar una habilidad con un archivo ZIP alojado en un bucket de Cloud Storage:

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --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 carga útil de la habilidad

REST

Para crear una habilidad con una revisión inicial intercalada, haz lo siguiente:

Método HTTP y URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

Cuerpo JSON de la solicitud (carga de archivos locales)

Para crear una habilidad subiendo directamente bytes de archivos ZIP locales, usa la carga útil archiveUploadSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

Reemplaza BASE64_ZIP_BYTES por la representación de cadena codificada en base64 de tu archivo ZIP local.

Cuerpo JSON de la solicitud (importación desde Cloud Storage)

Como alternativa, para crear una habilidad con un archivo almacenado en un bucket de Cloud Storage, usa gcsSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "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 carga útil de la habilidad

Comando curl (carga de archivos locales)

curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "type": "SIMPLE",
        "targetState": "TARGET_STATE_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Para la carga de archivos de bucket de Cloud Storage, reemplaza el cuerpo JSON de la solicitud por los campos y valores correspondientes.

¿Qué sigue?