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 administrar, controlar las versiones y compartir capacidades de forma centralizada en todos los agentes de IA de tu organización.

Las habilidades creadas por Google se ven de inmediato cuando configuras el 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 configurar 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 los siguientes roles de IAM 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 a través de roles personalizados o cualquier otro rol predefinido.

Otros roles del 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 capacidad 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 la skill, el Registro de agentes 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: El tamaño máximo sin comprimir es de 10 MB.
  • Tamaño de archivo individual: Tamaño máximo sin comprimir de 1 MB por archivo
  • Anidación profunda: La profundidad máxima de anidación de directorios es de 8 niveles.
  • Cumplimiento de la especificación: El archivo SKILL.md debe contener una sección de metadatos iniciales en formato YAML válida que defina el nombre, la descripción y los metadatos según se definen en la especificación de habilidades del agente.

Registra una habilidad

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

Para registrar tus propias habilidades, crea un contenedor de habilidades lógico 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.

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

Las habilidades que tú o los demás 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 skill en particular se convierte en private-SKILL_ID. No puedes especificar un publicador personalizado durante la creación de la skill.

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 posteriores de la skill.

Para registrar una skill, sigue estos pasos:

Console

  1. En la consola de Google Cloud , 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:

    • Add skill: Crea un nuevo contenedor de habilidad en el registro. De manera opcional, puedes subir un paquete de skill 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 Create skill o Import skill, 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 skill 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 skill. Para todas las operaciones posteriores de la skill, consulte su skill como private-SKILL_ID, como se muestra en la consola deGoogle Cloud .

gcloud

Para registrar una skill 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: Es el ID del recurso de la skill, 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 la skill posteriores, por ejemplo, private-workspace-docs-skill.
  • PROJECT_ID: El ID del proyecto
  • LOCATION: Es la región geográfica, por ejemplo, global, us o eu.
  • DISPLAY_NAME: Es un nombre descriptivo para la skill.

  • DESCRIPTION: Es un breve resumen que explica las capacidades de la skill.

  • Sube un archivo ZIP local: Para registrar una skill con una carga útil ZIP local, haz lo siguiente:

    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 la skill empaquetada 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" \
  --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.

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 archivo local)

Para crear una skill subiendo directamente bytes de un archivo ZIP local, 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: 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_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

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

¿Qué sigue?