Registra habilidades

Agent Registry te permite empaquetar y registrar de forma manual habilidades independientes. Las habilidades independientes agrupan las instrucciones del agente con recursos de metadatos asociados y secuencias de comandos opcionales para extender el razonamiento y el flujo de trabajo de un agente. Si registras tus propias habilidades independientes en Agent Registry, puedes administrar, controlar las versiones y compartir de forma centralizada las capacidades reutilizables junto con las habilidades administradas por Google que están disponibles cuando configuras Agent Registry.

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

Restricciones de la carga útil de transferencia

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

  • Tamaño del archivo ZIP: El tamaño máximo del archivo comprimido es 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.
  • Anidamiento profundo: profundidad máxima de anidamiento de directorios de 8 niveles.
  • Cumplimiento de las especificaciones: 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, como se define en la Especificación de habilidades del agente.

Registra una habilidad

Puedes registrar manualmente tus propias habilidades en Agent Registry. Para obtener información sobre los precios y los costos de las funciones de las habilidades, consulta Precios de Agent Registry.

Para registrar tus habilidades, haz lo siguiente:

Console

  1. En la consola de Google Cloud , ve a la página Registro de agentes:

    Ir al registro de agentes

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

  3. Selecciona la pestaña Habilidades.

  4. En la pestaña Habilidades, el botón Agregar habilidad muestra dos opciones para crear un contenedor de habilidades y, luego, importar tu paquete de habilidades inicial. Elige 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: Registra un nuevo paquete de habilidades personalizadas subiendo un paquete ZIP que contenga tu archivo de instrucciones SKILL.md y secuencias de comandos opcionales.

  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 resumen breve 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 la carga útil, elige una de las siguientes opciones:

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

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

  7. Haz clic en Crear.

    Tu habilidad se crea en el estado Inhabilitada (DISABLED). Para todas las operaciones de habilidades posteriores, consulta tu habilidad como private-SKILL_ID, como se muestra en la consola deGoogle Cloud .

  8. Para que la habilidad esté disponible para el descubrimiento de agentes, establece su revisión predeterminada y actualiza el estado objetivo a Activo. Para obtener instrucciones, consulta Administra los estados del ciclo de vida de las habilidades.

gcloud

  1. Crea el contenedor de habilidades y sube su carga útil de revisión inicial con el comando gcloud alpha agent-registry skills create. Puedes subir un archivo ZIP local o importar un paquete almacenado en Cloud Storage:

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

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

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

    • Importar desde un bucket de Cloud Storage: Para registrar una habilidad con un archivo ZIP alojado en un bucket de Cloud Storage, haz lo siguiente:

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

    Reemplaza lo siguiente en cualquiera de los comandos:

    • SKILL_ID: Es 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 habilidad posteriores, por ejemplo, private-workspace-docs-skill.
    • PROJECT_ID: Es el ID del proyecto.
    • LOCATION: Es la región geográfica, por ejemplo, global, us o eu.
    • DISPLAY_NAME: Es un nombre fácil de usar para la habilidad.
    • DESCRIPTION: un resumen breve en el que se explican las capacidades de la habilidad.

  2. Las habilidades recién creadas comienzan en el estado Inhabilitada (DISABLED). Para que la habilidad esté disponible para el descubrimiento de agentes, establece su revisión predeterminada y actualiza el estado objetivo a Activo. Para obtener instrucciones, consulta Administra los estados del ciclo de vida de las habilidades.

REST

  1. Crea el contenedor de la habilidad con una revisión inicial intercalada:

    Método HTTP y URL

    POST https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto.
    • LOCATION: Es la ubicación del registro.
    • SKILL_ID: Es un identificador único para el contenedor de habilidades.

    Cuerpo JSON de la solicitud (carga de archivo local)

    Para crear una habilidad subiendo directamente los bytes de un archivo ZIP local, usa la carga útil archiveUploadSource. Durante la creación, targetState debe establecerse en TARGET_STATE_DISABLED:

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

    Reemplaza lo siguiente:

    • DISPLAY_NAME: Es un nombre fácil de usar para la habilidad.
    • DESCRIPTION: un resumen breve en el que se explican las capacidades de la habilidad.
    • BASE64_ZIP_BYTES: Es 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_DISABLED",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

    Reemplaza lo siguiente:

    • DISPLAY_NAME: Es un nombre fácil de usar para la habilidad.
    • DESCRIPTION: un resumen breve en el que se explican las capacidades de la habilidad.
    • 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 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_DISABLED",
      "initialRevision": {
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }
    }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

    Reemplaza lo siguiente:

    • DISPLAY_NAME: Es un nombre fácil de usar para la habilidad.
    • DESCRIPTION: un resumen breve en el que se explican las capacidades de la habilidad.
    • PROJECT_ID: Es el ID del proyecto.
    • LOCATION: Es la ubicación del registro.
    • SKILL_ID: Es un identificador único para el contenedor de habilidades.

    Para subir un archivo de bucket de Cloud Storage, reemplaza el cuerpo JSON de la solicitud por los campos y valores correspondientes.

  2. Las habilidades recién creadas comienzan en el estado Inhabilitada (DISABLED). Para que la habilidad esté disponible para el descubrimiento de agentes, establece su revisión predeterminada y actualiza el estado objetivo a Activo. Para obtener instrucciones, consulta Administra los estados del ciclo de vida de las habilidades.

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

Por ejemplo, si creas una habilidad con el ID workspace-tools, el nombre del recurso se crea como projects/PROJECT_NUMBER/locations/LOCATION/skills/private-workspace-tools. El identificador de habilidad se asigna como urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. Debes usar el ID de publicador private-workspace-tools para todas las operaciones de habilidad posteriores.

¿Qué sigue?