Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Administra el acceso de los agentes implementados

Administrar el acceso a los agentes implementados en Gemini Enterprise Agent Platform implica configurar la autenticación y la autorización tanto para el agente que accede a recursos externos como para los clientes externos que acceden al agente. En este documento, se describen los métodos de autenticación disponibles, como la identidad del agente, las cuentas de servicio, las claves de API y los clientes de OAuth.

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

Método de autenticación	Caso de uso	Acerca de este método de autenticación
Identidad del agente (versión preliminar)	Acceder a fuentes de datos directamente desde un agente	Un agente implementado con identidad de agente puede acceder a los recursos según los permisos de IAM que le otorgues.
Cuentas de servicio	Acceder a fuentes de datos directamente desde un agente	Los agentes implementados tienen acceso a todos los recursos a los que su cuenta de servicio tiene permiso para acceder.
Claves de API	Enviar solicitudes a extremos con claves de API desde un agente	Verifica que la API que quieras usar admita claves de API antes de usar este método de autenticación.
ID de cliente de OAuth	Manejar las cuentas de usuario, el registro, el acceso o la autorización de los usuarios finales del agente	Requiere que tu agente solicite y reciba el consentimiento del usuario.

Identidad del agente

Si usaste la identidad del agente para configurar la identidad y los permisos de tu agente, consulta Usa la identidad del agente con Agent Runtime para obtener información sobre cómo administrar el control de acceso a los recursos.

Cuentas de servicio

Si usaste cuentas de servicio para configurar la identidad y los permisos de tu agente, los agentes que implementes en Agent Runtime se ejecutarán con el agente de servicio de AI Platform Reasoning Engine o tu cuenta de servicio personalizada.

Agente de servicio de AI Platform Reasoning Engine

La cuenta de servicio del agente de servicio de AI Platform Reasoning Engine usa el formato service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

La cuenta de servicio tiene un rol de agente de servicio de Reasoning Engine de Gemini Enterprise Agent Platform (roles/aiplatform.reasoningEngineServiceAgent) que otorga los permisos predeterminados necesarios para los agentes implementados. Puedes ver la lista completa de permisos predeterminados en la documentación de IAM.

Enumera los roles de un agente implementado

Console

Ir a la página IAM.

Ir a IAM
Selecciona el proyecto que corresponde a tu proyecto Google Cloud .
Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.
Los roles del agente implementado se encuentran en la columna Rol.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, 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 número de tu proyecto.
PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en el entorno de ejecución.

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

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-api-python-client

Luego, autentícate y ejecuta el siguiente comando 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)

Aquí, PRINCIPAL se basa en la cuenta de servicio que se usó cuando se implementó el agente en el entorno de ejecución.

Otorga roles para un agente implementado

Consola (recomendado)

Ir a la página IAM.

Ir a IAM
Selecciona el proyecto que corresponde a tu proyecto Google Cloud .
Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.
Para agregar los roles necesarios a la principal, haz clic en el botón Editar, agrega los roles y, luego, haz clic en el botón Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, 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 el entorno de ejecución.
ROLE_NAME es el nombre del rol que deseas otorgar. Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

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

Python

No recomendamos escribir tu propio código de Python para otorgar o revocar roles para los agentes implementados. En su lugar, recomendamos usar Google Cloud console o gcloud para operaciones únicas, o bien Terraform para administrar el control de acceso de IAM de forma programática. Si deseas o necesitas hacerlo en Python, consulta la documentación de la biblioteca cliente de IAM.

Revoca roles de un agente implementado

Consola (recomendado)

Ir a la página IAM.

Ir a IAM
Selecciona el proyecto que corresponde a tu proyecto Google Cloud .
Busca el principal que coincida con la cuenta de servicio que se usa como identidad del agente.
Para revocar los roles de la principal, haz clic en el botón Editar, quita los roles correspondientes y, luego, haz clic en el botón Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, 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 el entorno de ejecución.
ROLE_NAME es el nombre del rol que deseas revocar. Para obtener una lista de roles predefinidos, consulta Cómo entender los roles.

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

Python

Claves de API

Las claves de API usan secretos, que contienen una o más versiones de secretos, junto con metadatos como etiquetas e información de replicación. La carga útil real de un secreto se almacena en una versión de secreto. Los secretos se administran (a través de Secret Manager) a nivel del proyecto y se pueden compartir entre los agentes implementados. Para enumerar los secretos correspondientes a un agente en Secret Manager, puedes agregar etiquetas y usarlas para filtrar.

Crea un secreto

Console

Ve a la página de Secret Manager.

Ir a Secret Manager
En la página de Secret Manager, haz clic en Crear secreto.
En el campo Nombre, ingresa un nombre para el secreto (por ejemplo, my-secret).
Opcional: Para agregar también una versión del secreto cuando creas el secreto inicial, ingresa un valor en el campo Valor del secreto (por ejemplo, abcd1234).
Ve a Etiquetas y, luego, haz clic en Agregar etiqueta.
Ingresa una clave y su valor correspondiente para crear una etiqueta.
Haz clic en Crear secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, 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 completamente calificado del secreto.
FILE_PATH es la ruta de acceso completa (incluido el nombre del archivo) al archivo que contiene los detalles de la versión.

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

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

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

Console

Ve a la página de Secret Manager.

Ir a Secret Manager
En la página de Secret Manager, haz clic en el nombre de un secreto para describirlo.
En la página Detalles del secreto, se muestra información sobre el secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, 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 completamente calificado para el 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 cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

from google.cloud import secretmanager

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

Mostrar lista de secretos

Console

Ve a la página de Secret Manager.

Ir a Secret Manager
En la tabla Secrets, haz clic en el campo Filter.
Elige una propiedad de filtro y su valor correspondiente, por ejemplo, Location:asia-east1.
La tabla se filtra automáticamente según los valores ingresados.
(Opcional) Para filtrar versiones de secretos, selecciona un secreto para acceder a sus versiones y, luego, usa la opción Filtro en la tabla Versiones.

gcloud

Primero, instala y 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 (p.ej., name:asecret OR name:bsecret) o expresiones regulares (p.ej., name ~ "secret_ab.*").

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

gcloud secrets versions list SECRET_ID

Aquí, SECRET_ID es el ID del secreto o el identificador completamente calificado del secreto.

Para obtener más detalles, consulta la documentación de Secret Manager para 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 cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

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}")

Actualiza un secreto

Console

Ve a la página de Secret Manager.

Ir a Secret Manager
En la página de Secret Manager, haz clic en la casilla de verificación junto al nombre del secreto.
Si el Panel de información está cerrado, haz clic en Mostrar panel de información para mostrarlo.
En el panel de información, haz clic en la pestaña Etiquetas.
Haz clic en Agregar etiqueta y, luego, ingresa una clave y un valor para la etiqueta.
Haz clic en Guardar.

gcloud

Primero, instala y inicializa la CLI de gcloud. Luego, ejecuta el siguiente comando:

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

donde

SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto.
KEY es la clave de la etiqueta.
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 cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

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}")

Borra un secreto

Console

Ve a la página de Secret Manager.

Ir a Secret Manager
En la página Secret Manager, en la columna Acciones del secreto, haz clic en Ver más.
En el menú, selecciona Borrar.
En el diálogo Borrar secreto, ingresa el nombre del secreto.
Haz clic en el botón Borrar secreto.

gcloud

Primero, instala y inicializa la CLI de gcloud.

Para borrar una versión del secreto, ejecuta el siguiente comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

donde

VERSION_ID es el nombre del recurso de la versión del secreto.
SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto.

Para borrar 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 completamente calificado para el secreto

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

Python

Primero, instala la biblioteca cliente ejecutando el siguiente comando:

pip install google-cloud-secret-manager

Luego, autentícate y ejecuta el siguiente comando:

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

Un ID de cliente se usa para identificar un solo agente para los servidores de OAuth de Google. Si tu agente se ejecuta en varias plataformas, cada una de ellas necesita su propio ID de cliente. En términos generales, para integrar un agente basado en OAuth, sigue estos pasos:

Crea un cliente de OAuth y una credencial.
Almacena el ID de cliente y el secreto en Secret Manager. (Consulta Cómo crear un secreto).
Accede al secreto en tu agente durante el desarrollo.

Crea una credencial de cliente de OAuth

En la consola de Google Cloud , ve a la página Google Auth Platform > Clients.

Ir a Google Auth Platform > Clients
Si es necesario, y si la pantalla muestra el mensaje "Aún no se configuró Google Auth Platform", haz clic en Comenzar y completa la sección Configuraciones del proyecto. (Se pueden actualizar más adelante). Para obtener detalles sobre la preparación para la producción, visita Cumplimiento de la política de OAuth 2.0.
Haz clic en Crear cliente.
Configura Tipo de aplicación como Web application.
Establece el nombre del cliente de OAuth en OAUTH_CLIENT_DISPLAY_NAME.
En URIs de redireccionamiento autorizados, agrega el URI de REDIRECT_URI.
En Client Secrets, haz clic en el botón "Descargar JSON". Se descarga 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.
}}

Almacena el ID de cliente y el secreto 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),
    },
})

Mostrar clientes de OAuth

En la consola de Google Cloud , ve a la página Google Auth Platform > Clients, en la que se enumeran las credenciales del cliente de OAuth.

Ir a Google Auth Platform > Clients

Borra un cliente de OAuth

En la consola de Google Cloud , ve a la página Google Auth Platform > Clients.

Ir a Google Auth Platform > Clients
Selecciona las credenciales de cliente de OAuth que deseas borrar y haz clic en Borrar.

Claves de encriptación administradas por el cliente (CMEK)

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

Consulta la documentación sobre la CMEK para Agent Platform de Gemini Enterprise para conocer los requisitos generales y obtener orientación sobre el uso de la CMEK con Agent Platform de Gemini Enterprise, incluidos los siguientes temas:

Configuración del proyecto (facturación y APIs habilitadas)
Creación de llaveros de claves y claves
Permisos requeridos

Para habilitar la CMEK en tu agente, debes especificar encryption_spec con tu clave de Cloud KMS cuando crees una instancia de Agent Platform. Consulta Configura las claves de encriptación administradas por el cliente para ver muestras de código.

Limitaciones

Se aplican las siguientes limitaciones cuando se usa la CMEK con Agent Runtime:

No se permiten las claves multirregionales: Solo se admiten las claves de una sola región. La región del llavero de claves y la clave debe ser la misma que la de tu instancia de Agent Platform.
No se puede actualizar la clave de encriptación para las instancias de CMEK: Una vez que se implementa un agente con una clave de CMEK, no se puede cambiar la clave de encriptación para esa implementación. Para usar una clave nueva, debes implementar una instancia nueva de Agent Platform.
Determinados metadatos y datos operativos no se encriptan con tu clave: La CMEK encripta los datos principales del agente en reposo. Sin embargo, ciertos metadatos y datos operativos del tiempo de ejecución no se encriptan con tu clave. En cambio, se encriptan con la encriptación predeterminada de Google. Esto incluye lo siguiente:
- Metadatos del agente:
  - Los nombres visibles
  - Descripciones
- Datos operativos del tiempo de ejecución:
  - Correos electrónicos de la cuenta de servicio
  - Nombres de métodos de clase de objetos del agente
  - Variables de entorno

Controles del servicio de VPC (VPC-SC)

Agent Runtime admite los Controles del servicio de VPC para fortalecer la seguridad de los datos y mitigar los riesgos de robo de datos.

Cuando se configuran los Controles del servicio de VPC, el agente implementado conserva el acceso seguro a las APIs y los servicios de Google, como la API de BigQuery, la API de Cloud SQL Admin y la API de Agent Platform, lo que verifica el funcionamiento sin problemas dentro del perímetro definido. Fundamentalmente, los Controles del servicio de VPC bloquean de manera efectiva todo el acceso a Internet pública, lo que limita el movimiento de datos a los límites de tu red autorizada y mejora significativamente tu nivel de seguridad empresarial.

Las opciones de implementación disponibles se enumeran en Implementa un agente. Según la opción de implementación, se deben configurar las siguientes reglas de entrada:

Para las implementaciones basadas en pickle, se requiere la entrada al servicio storage.googleapis.com y al servicio artifactregistry.googleapis.com.
Para las implementaciones basadas en código fuente, las implementaciones basadas en Git y las implementaciones de tu propio Dockerfile (BYOD), se requiere la entrada al servicio artifactregistry.googleapis.com.
En el caso de las implementaciones de Bring Your Own Container (BYOC), no se requiere ninguna regla de entrada adicional.

Limitaciones

Los Controles del servicio de VPC no son compatibles con Agent Gateway.

Sin embargo, puedes usar restricciones personalizadas de políticas de la organización para restringir qué puertas de enlace se pueden asociar con tus agentes. Para obtener más información, consulta Cómo enrutar el tráfico a través de Agent Gateway.

Administra el acceso de los agentes implementados Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Identidad del agente

Cuentas de servicio

Agente de servicio de AI Platform Reasoning Engine

Enumera los roles de un agente implementado

Console

gcloud

Python

Otorga roles para un agente implementado

Consola (recomendado)

gcloud

Python

Revoca roles de un agente implementado

Consola (recomendado)

gcloud

Python

Claves de API

Crea un secreto

Console

gcloud

Python

Obtener un secreto

Console

gcloud

Python

Mostrar lista de secretos

Console

gcloud

Python

Actualiza un secreto

Console

gcloud

Python

Borra un secreto

Console

gcloud

Python

Clientes y credenciales de OAuth

Crea una credencial de cliente de OAuth

Mostrar clientes de OAuth

Borra un cliente de OAuth

Claves de encriptación administradas por el cliente (CMEK)

Limitaciones

Controles del servicio de VPC (VPC-SC)

Limitaciones

Administra el acceso de los agentes implementados