Gestionar el acceso de los agentes implementados

Hay diferentes tipos de métodos de autenticación disponibles para los distintos modos de acceso:

Caso práctico	Método de autenticación	Acerca de este método de autenticación
Acceder a fuentes de datos directamente desde un agente.	Cuenta de servicio	Los agentes implementados tienen acceso a todos los recursos a los que su cuenta de servicio tiene permiso para acceder.
Enviar solicitudes a endpoints mediante claves de API desde un agente.	Claves de API	Comprueba que la API que quieres usar admite claves de API antes de usar este método de autenticación.
Gestionar las cuentas de usuario, el registro, el inicio de sesión o la autorización de los usuarios finales del agente.	ID de cliente de OAuth	Requiere que tu agente solicite y reciba el consentimiento del usuario.

Roles

Los agentes que despliegues en Vertex AI Agent Engine se ejecutan con la cuenta de servicio del agente de servicio de razonamiento de AI Platform o con tu cuenta de servicio personalizada. Consulta más información en Configurar la identidad y los permisos de tu agente.

Agente de servicio de AI Platform Reasoning Engine

La cuenta de servicio Agente de servicio de AI Platform Reasoning Engine usa el formato [e-mail].

La cuenta de servicio tiene el rol Agente de servicio de Reasoning Engine de Vertex AI (roles/aiplatform.reasoningEngineServiceAgent), que concede los permisos predeterminados necesarios para los agentes desplegados. Puedes consultar la lista completa de permisos predeterminados en la documentación de gestión de identidades y accesos.

Lista los roles de un agente implementado

Consola

1. Ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Selecciona el proyecto correspondiente a tu Google Cloud proyecto.

3. Busca el principal que coincida con la cuenta de servicio que se ha usado como identidad de tu agente.

4. Los roles del agente implementado se encuentran en la columna Rol.

Nota: En el caso de la cuenta de servicio Agente de servicio de Reasoning Engine de AI Platform, debes seleccionar la opción "Incluir asignaciones de roles proporcionadas por Google" para que se muestre en la tabla de principales.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta el siguiente comando:

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

donde

• PROJECT_ID_OR_NUMBER es el ID o el número de tu proyecto.
• PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.

Para obtener más información, consulta la documentación de IAM y la referencia de la CLI.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-api-python-client

A continuación, autentícate y ejecuta lo siguiente para enumerar los roles de un agente implementado:

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

El PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.

Asignar roles a un agente implementado

Consola (recomendado)

1. Ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Selecciona el proyecto correspondiente a tu Google Cloud proyecto.

3. Busca el principal que coincida con la cuenta de servicio que se ha usado como identidad de tu agente.

4. Añade los roles necesarios al Principal haciendo clic en el botón de edición, añadiendo los roles y, a continuación, haciendo clic en el botón de guardar.

Nota: En el caso de la cuenta de servicio Agente de servicio de Reasoning Engine de AI Platform, debes seleccionar la opción "Incluir asignaciones de roles proporcionadas por Google" para que se muestre en la tabla de principales.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta el siguiente comando:

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

donde

• PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.
• ROLE_NAME es el nombre del rol que quieres conceder. Si quieres ver una lista de los roles predefinidos, consulta el artículo Descripción de los roles.

Para obtener más información, consulta la documentación de IAM y la referencia de la CLI.

Python

No te recomendamos que escribas tu propio código de Python para conceder o revocar roles de agentes implementados. En su lugar, te recomendamos que utilices la Google Cloud consolagcloud para operaciones puntuales o Terraform para gestionar el control de acceso de IAM de forma programática. Si quieres o necesitas hacerlo en Python, consulta la documentación de la biblioteca de cliente de IAM.

Revocar roles de un agente implementado

Consola (recomendado)

1. Ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Selecciona el proyecto correspondiente a tu Google Cloud proyecto.

3. Busca el principal que coincida con la cuenta de servicio que se ha usado como identidad de tu agente.

4. Revoca los roles del Principal haciendo clic en el botón de edición, quitando los roles correspondientes y, a continuación, haciendo clic en el botón de guardar.

Nota: En el caso de la cuenta de servicio Agente de servicio de Reasoning Engine de AI Platform, debes seleccionar la opción "Incluir asignaciones de roles proporcionadas por Google" para que se muestre en la tabla de principales.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta el siguiente comando:

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

donde

• PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en Vertex AI Agent Engine.
• ROLE_NAME es el nombre del rol que quieres revocar. Si quieres ver una lista de los roles predefinidos, consulta el artículo Descripción de los roles.

Para obtener más información, consulta la documentación de IAM y la referencia de la CLI.

Python

No te recomendamos que escribas tu propio código de Python para conceder o revocar roles de agentes implementados. En su lugar, te recomendamos que utilices la Google Cloud consolagcloud para operaciones puntuales o Terraform para gestionar el control de acceso de IAM de forma programática. Si quieres o necesitas hacerlo en Python, consulta la documentación de la biblioteca de cliente de IAM.

Secretos

Un secreto contiene una o varias versiones del secreto, junto con metadatos como etiquetas e información de replicación. La carga útil real de un secreto se almacena en una versión del secreto. Los secretos se gestionan (a través de Secret Manager) a nivel de proyecto y se pueden compartir entre los agentes implementados. Para enumerar los secretos correspondientes a un agente en Secret Manager, puedes añadir etiquetas y usarlas para filtrar.

Crear un secreto

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. En la página Secret Manager, haz clic en Crear secreto.

3. En el campo Name (Nombre), introduce un nombre para el secreto (por ejemplo, my-secret).

4. Opcional: Para añadir también una versión de secreto al crear el secreto inicial, introduce un valor en el campo Valor del secreto (por ejemplo, abcd1234).

5. Ve a Etiquetas y haz clic en Añadir etiqueta.

6. Introduce una clave y su valor correspondiente para crear una etiqueta.

7. Haz clic en Crear secreto.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta los siguientes comandos:

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

donde

• SECRET_ID es el ID del secreto o el identificador completo del secreto.
• FILE_PATH es la ruta completa (incluido el nombre del archivo) del archivo que contiene los detalles de la versión.

Para obtener más información, consulta la documentación de Secret Manager sobre cómo crear un secreto y una versión de secreto, o la referencia de la CLI para crear un secreto y una versión de secreto, respectivamente.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

A continuación, autentícate y ejecuta lo siguiente:

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Obtener un secreto

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. En la página Secret Manager, haz clic en el nombre de un secreto para describirlo.

3. En la página Detalles del secreto se muestra información sobre el secreto.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta el siguiente comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

donde

• VERSION_ID es el ID de la versión del secreto.
• SECRET_ID es el ID del secreto o el identificador completo del secreto.

Para obtener más información, consulta la documentación de Secret Manager o la referencia de la CLI.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

A continuación, autentícate y ejecuta lo siguiente:

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Mostrar secretos

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. En la tabla Secretos, haga clic en el campo Filtrar.

3. Elige una propiedad de filtro y su valor correspondiente, por ejemplo, Location:asia-east1.

4. La tabla se filtra automáticamente en función de los valores introducidos.

5. (Opcional) Para filtrar las versiones de un secreto, selecciona un secreto para acceder a sus versiones y, a continuación, usa la opción Filtrar de la tabla Versiones.

gcloud

Primero, instala e inicializa la CLI de gcloud.

Para enumerar todos los secretos de un proyecto, ejecuta el siguiente comando:

gcloud secrets list --filter="FILTER"

donde FILTER es una cadena (por ejemplo, name:asecret OR name:bsecret) o una expresión regular (por ejemplo, name ~ "secret_ab.*").

Para ver todas las versiones de un secreto, ejecuta el siguiente comando:

gcloud secrets versions list SECRET_ID

donde SECRET_ID es el ID del secreto o el identificador completo del secreto.

Para obtener más información, consulta la documentación de Secret Manager sobre cómo filtrar secretos y listar versiones de secretos, o la referencia de la CLI para listar secretos y versiones de secretos, respectivamente.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

A continuación, autentícate y ejecuta lo siguiente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Actualizar un secreto

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. En la página Secret Manager, marca la casilla situada junto al nombre del secreto.

3. Si el panel de información está cerrado, haz clic en Mostrar panel de información para que se muestre.

4. En el panel de información, selecciona la pestaña Etiquetas.

5. Haz clic en Añadir etiqueta e introduce una clave y un valor para la etiqueta.

6. Haz clic en Guardar.

gcloud

Primero, instala e inicializa la CLI de gcloud. A continuación, ejecuta el siguiente comando:

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

donde

• SECRET_ID es el ID del secreto o el identificador completo del secreto.
• KEY es la clave de etiqueta y
• VALUE es el valor correspondiente de la etiqueta.

Para obtener más información, consulta la documentación de Secret Manager o la referencia de la CLI.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

A continuación, autentícate y ejecuta lo siguiente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Eliminar un secreto

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. En la página Secret Manager, en la columna Acciones del secreto, haz clic en Ver más.

3. En el menú, selecciona Eliminar.

4. En el cuadro de diálogo Eliminar secreto, introduce el nombre del secreto.

5. Haz clic en el botón Eliminar secreto.

gcloud

Primero, instala e inicializa la CLI de gcloud.

Para eliminar una versión de un secreto, ejecuta el siguiente comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

donde

• VERSION_ID es el nombre de recurso de la versión del secreto y
• SECRET_ID es el ID del secreto o el identificador completo del secreto.

Para eliminar un secreto y todas sus versiones, ejecuta el siguiente comando:

gcloud secrets delete SECRET_ID

donde SECRET_ID es el ID del secreto o el identificador completo del secreto.

Para obtener más información, consulta la documentación de Secret Manager sobre cómo eliminar un secreto y destruir una versión de un secreto, o la referencia de la CLI para eliminar un secreto y destruir una versión de un secreto.

Python

Primero, instala la biblioteca de cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

A continuación, autentícate y ejecuta lo siguiente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

Clientes y credenciales de OAuth

Los IDs de cliente se utilizan para identificar agentes de manera individualizada en los servidores OAuth de Google. Si tu agente se ejecuta en varias plataformas, necesitará un ID de cliente en cada una de ellas. A grandes rasgos, para integrar un agente basado en OAuth, debes hacer lo siguiente:

1. Crea un cliente y una credencial de OAuth.

2. Almacena el ID y el secreto de cliente en Secret Manager. Consulta Crear un secreto.

3. Accede al secreto en tu agente durante el desarrollo.

Nota: Consulta el artículo sobre cómo configurar OAuth 2.0 para obtener más información. Consulta más información sobre los tipos de clientes de OAuth.

Crear una credencial de cliente de OAuth

1. En la Google Cloud consola, ve a la página Plataforma de autenticación de Google > Clientes.

   Ve a Plataforma de autenticación de Google > Clientes.

2. Si es necesario, si en la pantalla se muestra el mensaje "Google Auth Platform not configured yet" (La plataforma de autenticación de Google aún no se ha configurado), haz clic en Get Started (Empezar) y rellena la sección Project Configurations (Configuraciones del proyecto). Puedes cambiar esta información más adelante. Para obtener más información sobre la preparación para la producción, consulta el artículo Cumplimiento de la política de OAuth 2.0.

3. Haz clic en Crear cliente.

4. En Tipo de aplicación, seleccione Web application.

5. Asigna el nombre OAUTH_CLIENT_DISPLAY_NAME al cliente de OAuth.

6. En URIs de redirección autorizados, añade el URI de REDIRECT_URI.

7. En Secretos de cliente, haz clic en el botón "Descargar JSON". Se descargará un archivo client_secret.json con el siguiente contenido:

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

1. Almacena el ID y el secreto de cliente en Secret Manager, por ejemplo:

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

Nota: Puede verificar que la credencial de cliente de OAuth se ha almacenado en Secret Manager a través de la consola.

Google Cloud

Mostrar clientes de OAuth

1. En la Google Cloud consola, ve a la página Plataforma de autenticación de Google > Clientes.

   Ve a Plataforma de autenticación de Google > Clientes.

2. Se mostrarán las credenciales de cliente de OAuth que tengas.

Eliminar un cliente de OAuth

1. En la Google Cloud consola, ve a la página Plataforma de autenticación de Google > Clientes.

   Ve a Plataforma de autenticación de Google > Clientes.

2. Selecciona las credenciales de cliente de OAuth que quieras eliminar y haz clic en Eliminar.

Claves de encriptado gestionadas por el cliente (CMEK)

De forma predeterminada, Google Cloud cifra automáticamente los datos cuando están en reposo con claves de cifrado gestionadas por Google. Si tienes requisitos de cumplimiento o normativos específicos relacionados con las claves que protegen tus datos, puedes usar claves de cifrado gestionadas por el cliente (CMEK) para tus agentes implementados.

Consulta la documentación sobre CMEK para Vertex AI para obtener información sobre los requisitos generales y las directrices para usar CMEK con Vertex AI, incluidos los siguientes:

• Configuración del proyecto (facturación y APIs habilitadas)
• Creación de conjuntos de claves y claves
• Concesiones de permisos obligatorias

Para habilitar CMEK en tu agente, debes especificar el encryption_spec con tu clave de Cloud KMS al crear una instancia de Agent Engine. Consulta Configurar claves de cifrado gestionadas por el cliente para ver ejemplos de código.

Limitaciones

Se aplican las siguientes limitaciones al usar CMEK con Vertex AI Agent Engine:

• No se permiten claves multirregionales: solo se admiten claves de una sola región. La región del conjunto de claves y de la clave debe ser la misma que la de tu instancia de Agent Engine.

• Las instancias de CMEK implementadas no se pueden actualizar: una vez que se implementa un agente con una clave CMEK, la instancia no se puede actualizar ni cambiar en esa implementación. Para usar otra especificación de Agent Engine (para una clave nueva o para otras configuraciones), debes desplegar una instancia de Agent Engine nueva.

• Determinados metadatos y datos operativos no están cifrados: CMEK cifra los datos principales del agente en reposo. Sin embargo, algunos metadatos y datos operativos de tiempo de ejecución no están cifrados. Entre los datos que recoge se incluyen los siguientes:

  • Metadatos del agente:
    • Nombres visibles
    • Descripciones
  • Datos operativos de tiempo de ejecución:
    • Correos de cuentas de servicio
    • Nombres de métodos de clase de objeto de agente
    • Variables de entorno