Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Administra el acceso a los agentes implementados

La administración del acceso para los agentes implementados en Gemini Enterprise Agent Platform implica configurar la autenticación y la autorización tanto para el agente que accede a los recursos externos como para los clientes externos que acceden al agente. En este documento, se describen los métodos de autenticación disponibles, incluidas 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)	Accede a las fuentes de datos directamente desde un agente.	Un agente implementado con la identidad del agente puede acceder a los recursos según los permisos de IAM que le otorgues.
Cuentas de servicio	Accede a las fuentes de datos directamente desde un agente.	Los agentes implementados tienen acceso a todos los recursos a los que tiene acceso su cuenta de servicio.
Claves de API	Envía 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	Controlar 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 con tu cuenta de servicio personalizada.

Agente de servicio del motor de razonamiento de la plataforma de IA

La cuenta de servicio del agente de servicio del motor de razonamiento de la plataforma de IA usa el formato de service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

La cuenta de servicio tiene un rol de agente de servicio de Vertex AI Reasoning Engine (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 correspondiente a tu proyecto de Google Cloud .
Busca la principal que coincida con la cuenta de servicio que se usa como identidad del agente.
Los roles del agente implementado se pueden encontrar en la columna Rol.

gcloud

Primero, instala e 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)

Donde 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 correspondiente a tu proyecto de Google Cloud .
Busca la 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 e 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 Información sobre 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 de los agentes implementados. En su lugar, te recomendamos que uses la consola de Google Cloud o gcloud para operaciones únicas, o Terraform para administrar el control de acceso de IAM de manera programática. Si quieres 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 correspondiente a tu proyecto de Google Cloud .
Busca la 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 e 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 Información sobre 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 Secret se almacena en una versión del Secret. Los secretos se administran (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 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 Secret (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 e 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 Secret o el identificador completamente calificado para el Secret.
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 detalles, consulta la documentación de Secret Manager para crear un secreto y una versión del secreto, o 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}")

Recupera 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 e 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 detalles, 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 Secretos, haz clic en el campo Filtro.
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 las versiones de los secretos, selecciona un secreto para acceder a sus versiones y, luego, usa la opción Filtrar en 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"

En el ejemplo anterior, 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

En el ejemplo anterior, SECRET_ID es el ID del secreto o el identificador completamente calificado para el secreto.

Para obtener más detalles, consulta la documentación de Secret Manager sobre cómo filtrar secretos y cómo enumerar versiones de secretos, o la referencia de la CLI para enumerar 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 que aparezca.
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 e 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 detalles, 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 de Secret Manager, en la columna Acciones del Secret, haz clic en Ver más.
En el menú, selecciona Borrar.
En el cuadro de diálogo Borrar secreto, ingresa el nombre del secreto.
Haz clic en el botón Borrar secreto.

gcloud

Primero, instala e 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 detalles, 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 necesitará 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 Crea 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 > Clientes.

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

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 > Clientes, en la que se enumeran las credenciales de cliente de OAuth.

Ir a Google Auth Platform > Clientes

Borra un cliente de OAuth

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

Ir a Google Auth Platform > Clientes
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 cuando están en reposo de manera automática 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 de CMEK para Gemini Enterprise Agent Platform para conocer los requisitos generales y obtener orientación sobre el uso de CMEK con Gemini Enterprise Agent Platform, lo que incluye lo siguiente:

Configuración del proyecto (facturación y APIs habilitadas)
Creación de llaveros de claves y claves
Otorgamientos de permisos obligatorios

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

Limitaciones

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

Restricciones de extremos multirregionales y globales: Los agentes implementados en Agent Runtime solo admiten claves de una sola región en Cloud Key Management Service, donde el llavero de claves y la región de la clave coinciden con la región de tu instancia de Agent Platform. No se admite la implementación de un entorno de ejecución de agentes con CMEK en extremos multirregionales (us o eu). Sin embargo, si creas una instancia superior independiente de Agent Platform sin implementar el código del entorno de ejecución del agente (para almacenar datos de sesiones de Agent Platform o bancos de memoria de Agent Platform), puedes configurar CMEK en ubicaciones regionales y multirregionales (us con una clave us o eu con una clave europe). El extremo global no admite CMEK para ningún recurso.
La clave de encriptación no se puede actualizar para las instancias de CMEK: Una vez que se implementa un agente con una clave de CMEK, la clave de encriptación no se puede cambiar para esa implementación. Para usar una clave nueva, debes implementar una instancia nueva de Agent Platform.
Ciertos metadatos y datos operativos no se encriptan con tu clave: CMEK encripta los datos principales del agente en reposo. Sin embargo, ciertos metadatos y datos operativos del entorno de ejecución no se encriptan con tu clave. En su lugar, se encriptan con la encriptación predeterminada de Google. Esto incluye lo siguiente:
- Metadatos del agente:
  - Los nombres visibles
  - Descripciones
- Datos operativos del entorno de ejecución:
  - Correos electrónicos de la cuenta de servicio
  - Nombres de métodos de clase de objetos de agentes
  - 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. De manera crucial, los Controles del servicio de VPC bloquean de forma eficaz todo el acceso público a Internet, lo que limita el movimiento de datos a los límites de tu red autorizada y mejora de forma significativa la postura de seguridad de tu empresa.

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 de storage.googleapis.com y al servicio de artifactregistry.googleapis.com.
Para las implementaciones basadas en fuentes, las implementaciones basadas en Git y las implementaciones de Dockerfile (BYOD), se requiere la entrada al servicio artifactregistry.googleapis.com.
Para las implementaciones de Bring Your Own Container (BYOC), no se requiere ninguna regla de entrada adicional.

Usa los Controles del servicio de VPC con Agent Gateway

Los Controles del servicio de VPC son compatibles con Agent Gateway para las implementaciones de agente a cualquier lugar (salida) creadas después del 8 de septiembre de 2026. Para ejecutar Agent Runtime con Agent Gateway dentro de un perímetro de servicio de los Controles del servicio de VPC, tu implementación debe cumplir con los siguientes requisitos:

La puerta de enlace debe usar una plantilla de conectividad de agente (AgentConnectivityTemplate) con vpcEgress configurado como ALL_TRAFFIC para que todo el tráfico saliente del agente se enrute a través de tu red de VPC.
Tu red de VPC debe configurar zonas de Cloud DNS privadas y el intercambio de tráfico de DNS para googleapis.com. que resuelvan el tráfico de la API de Google a restricted.googleapis.com (199.36.153.4/30) o extremos internos de Private Service Connect.
Si tu agente está vinculado a una puerta de enlace de aplicación de políticas, debes agregar a la lista de entidades permitidas los extremos regionales y de mTLS de Agent Platform API requeridos en el Registro de agentes.

Para obtener instrucciones de configuración paso a paso, consulta los siguientes recursos:

Administra el acceso a 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 del motor de razonamiento de la plataforma de IA

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

Recupera 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)

Usa los Controles del servicio de VPC con Agent Gateway

Administra el acceso a los agentes implementados