O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar o acesso para agentes implantados

O gerenciamento do acesso de agentes implantados na Gemini Enterprise Agent Platform envolve a configuração da autenticação e da autorização para o agente que acessa recursos externos e para os clientes externos que acessam o agente. Neste documento, descrevemos os métodos de autenticação disponíveis, incluindo identidade do agente, contas de serviço, chaves de API e clientes OAuth.

Há diferentes tipos de métodos de autenticação disponíveis para diferentes modos de acesso:

Método de autenticação	Caso de uso	Sobre este método de autenticação
Identidade do agente (pré-lançamento)	Acesse fontes de dados diretamente de um agente.	Um agente implantado com identidade de agente pode acessar recursos de acordo com as permissões do IAM que você conceder a ele.
Contas de serviço	Acesse fontes de dados diretamente de um agente.	Os agentes implantados têm acesso a todos os recursos que a conta de serviço tem permissão para acessar.
Chaves de API	Enviar solicitações para endpoints usando chaves de API de um agente.	Verifique se a API que você quer usar é compatível com chaves de API antes de usar esse método de autenticação.
ID do cliente OAuth	Processar contas de usuário, registro, login ou autorização para os usuários finais do agente.	Exige que o agente solicite e receba o consentimento do usuário.

Identidade do agente

Se você usou a identidade do agente para configurar a identidade e as permissões do agente, consulte Usar a identidade do agente com o Agent Runtime para saber como gerenciar o controle de acesso aos recursos.

Contas de serviço

Se você usou contas de serviço para configurar a identidade e as permissões do seu agente, os agentes implantados no Agent Runtime serão executados usando o agente de serviço do mecanismo de raciocínio da plataforma de IA ou sua conta de serviço personalizada.

Agente de serviço do mecanismo de raciocínio da plataforma de IA

A conta de serviço do agente de serviço do mecanismo de raciocínio da plataforma de IA usa o formato de service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

A conta de serviço tem um papel de Agente de serviço do mecanismo de raciocínio da Gemini Enterprise Agent Platform (roles/aiplatform.reasoningEngineServiceAgent) que concede as permissões padrão necessárias para os agentes implantados. É possível conferir a lista completa de permissões padrão na documentação do IAM.

Listar os papéis de um agente implantado

Console

Acessar a página IAM

Acessar IAM
Selecione o projeto correspondente ao seu projeto do Google Cloud .
Encontre o Principal que corresponde à conta de serviço usada como identidade do agente.
Os papéis do agente implantado podem ser encontrados na coluna Papel.

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute o comando:

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

em que

PROJECT_ID_OR_NUMBER é o ID ou número do projeto;
PRINCIPAL é baseado na conta de serviço usada quando o agente é implantado no ambiente de execução.

Para mais detalhes, acesse a documentação do IAM e a referência da CLI.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-api-python-client

Em seguida, faça sua autenticação e execute o seguinte para listar os papéis de um agente implantado:

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)

Em que PRINCIPAL é baseado na conta de serviço usada quando o agente é implantado no ambiente de execução.

Conceder papéis para um agente implantado

Console (recomendado)

Acessar a página IAM

Acessar IAM
Selecione o projeto correspondente ao seu projeto do Google Cloud .
Encontre o Principal que corresponde à conta de serviço usada como identidade do agente.
Adicione os papéis necessários ao Principal clicando no botão de edição, adicionando os papéis e clicando no botão "Salvar".

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute o comando:

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

em que

PRINCIPAL é baseado na conta de serviço usada quando o agente é implantado no ambiente de execução.
ROLE_NAME é o nome do papel que você quer conceder. Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.

Para mais detalhes, acesse a documentação do IAM e a referência da CLI.

Python

Não recomendamos escrever seu próprio código Python para conceder ou revogar papéis para agentes implantados. Em vez disso, recomendamos usar o console do Google Cloud ou o gcloud para operações únicas ou o Terraform para gerenciar o controle de acesso do IAM de maneira programática. Se você quiser ou precisar fazer isso em Python, consulte a documentação da biblioteca de cliente do IAM.

Revogar papéis de um agente implantado

Console (recomendado)

Acessar a página IAM

Acessar IAM
Selecione o projeto correspondente ao seu projeto do Google Cloud .
Encontre o Principal que corresponde à conta de serviço usada como identidade do agente.
Revogue os papéis do Principal clicando no botão de edição, removendo os papéis correspondentes e clicando no botão "Salvar".

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute o comando:

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

em que

PRINCIPAL é baseado na conta de serviço usada quando o agente é implantado no ambiente de execução.
ROLE_NAME é o nome do papel que você quer revogar. Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.

Para mais detalhes, acesse a documentação do IAM e a referência da CLI.

Python

Chaves de API

As chaves de API usam secrets, que contêm uma ou mais versões de secrets, além de metadados, como rótulos e informações de replicação. O payload real de um secret é armazenado em uma versão do secret. Os secrets são gerenciados (pelo Secret Manager) no nível do projeto e podem ser compartilhados entre os agentes implantados. Para listar os secrets correspondentes a um agente no Secret Manager, adicione rótulos e use-os para filtragem.

Criar um secret

Console

Acesse a página do Secret Manager.

Acessar o Secret Manager
Na página do Secret Manager, clique em Criar secret.
No campo Nome, insira um nome para o secret (por exemplo, my-secret).
Opcional: para adicionar uma versão do secret ao criar o secret inicial, no campo Valor do secret, digite um valor (por exemplo, abcd1234).
Acesse Rótulos e clique em Adicionar rótulo.
Insira uma chave e o valor correspondente para criar um rótulo.
Clique em Criar secret.

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute os seguintes comandos:

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

em que

SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.
FILE_PATH é o caminho completo (incluindo o nome do arquivo) para o arquivo que contém os detalhes da versão.

Para mais detalhes, acesse a documentação do Secret Manager sobre como criar um secret e uma versão do secret ou a referência da CLI para criar um secret e uma versão do secret, respectivamente.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-cloud-secret-manager

Em seguida, faça sua autenticação e execute o seguinte 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}")

Receber um secret

Console

Acesse a página do Secret Manager.

Acessar o Secret Manager
Na página do Secret Manager, clique no nome de um secret para descrevê-lo.
A página Detalhes do secret lista informações sobre o secret.

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute o comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

em que

VERSION_ID é o ID da versão do secret;
SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.

Para mais detalhes, acesse a documentação do Secret Manager ou a referência da CLI.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-cloud-secret-manager

Em seguida, faça sua autenticação e execute o seguinte comando:

from google.cloud import secretmanager

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

Listar secrets

Console

Acesse a página do Secret Manager.

Acessar o Secret Manager
Na tabela "Secrets", clique no campo Filtro.
Escolha uma propriedade de filtro e o valor correspondente, por exemplo, Location:asia-east1.
A tabela é filtrada automaticamente com base nos valores inseridos.
(Opcional) Para filtrar versões de secrets: selecione um secret para acessar as versões dele e use a opção Filtrar na tabela Versões.

gcloud

Primeiro, instale e inicialize a CLI gcloud.

Para listar todos os secrets de um projeto, execute o seguinte comando:

gcloud secrets list --filter="FILTER"

em que FILTER é uma string (por exemplo, name:asecret OR name:bsecret) ou expressões regulares (por exemplo, name ~ "secret_ab.*").

Para listar todas as versões de um secret, execute o seguinte comando:

gcloud secrets versions list SECRET_ID

em que SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.

Para mais detalhes, acesse a documentação do Secret Manager sobre filtragem de secrets e listagem de versões de secrets ou a referência da CLI para listar secrets e versões de secrets, respectivamente.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-cloud-secret-manager

Em seguida, faça sua autenticação e execute o seguinte 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}")

Atualizar um secret

Console

Acesse a página do Secret Manager.

Acessar o Secret Manager
Na página do Secret Manager, clique na caixa de seleção ao lado do nome do secret.
Se o painel de informações estiver fechado, clique em Mostrar painel de informações para exibi-lo.
No painel de informações, clique na guia Rótulos.
Clique em Adicionar rótulo e insira uma chave e um valor para o rótulo.
Clique em Salvar.

gcloud

Primeiro, instale e inicialize a CLI gcloud. Em seguida, execute o comando:

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

em que

SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.
KEY é a chave do rótulo;
VALUE é o valor correspondente do rótulo.

Para mais detalhes, acesse a documentação do Secret Manager ou a referência da CLI.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-cloud-secret-manager

Em seguida, faça sua autenticação e execute o seguinte 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}")

Excluir um secret

Console

Acesse a página do Secret Manager.

Acessar o Secret Manager
Na página do Secret Manager, na coluna Ações do secret, clique em Ver mais.
No menu, selecione Excluir.
Na caixa de diálogo Excluir secret, insira o nome do secret.
Clique no botão Excluir secret.

gcloud

Primeiro, instale e inicialize a CLI gcloud.

Para excluir uma versão de secret, execute o seguinte comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

em que

VERSION_ID é o nome do recurso da versão do secret;
SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.

Para excluir um secret e todas as versões dele, execute o seguinte comando:

gcloud secrets delete SECRET_ID

em que SECRET_ID é o ID do secret ou o identificador totalmente qualificado do secret.

Para mais detalhes, acesse a documentação do Secret Manager sobre como excluir um secret e como destruir uma versão do secret ou a referência da CLI para excluir um secret e destruir uma versão do secret.

Python

Primeiro, instale a biblioteca de cliente executando

pip install google-cloud-secret-manager

Em seguida, faça sua autenticação e execute o seguinte comando:

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

Clientes e credenciais OAuth

Um ID do cliente é usado para identificar um único agente nos servidores OAuth do Google. Se o agente for executado em várias plataformas, cada uma precisará de um ID do cliente próprio. Em um nível alto, para integrar um agente baseado em OAuth, faça o seguinte:

Crie um cliente e uma credencial OAuth.
Armazene o ID do cliente e a chave secreta no Secret Manager. Consulte Criar um secret.
Acesse o secret no agente durante o desenvolvimento.

Criar uma credencial de cliente OAuth

No console do Google Cloud , acesse a página Google Auth Platform > Clientes.

Acesse Google Auth Platform > Clientes.
(Se necessário) Se a tela mostrar "A plataforma de autenticação do Google ainda não está configurada", clique em Começar e preencha as Configurações do projeto. (Elas podem ser atualizadas mais tarde.) Para mais detalhes sobre a prontidão para produção, acesse Conformidade com a política do OAuth 2.0.
Clique em Criar cliente.
Defina o Tipo de aplicativo como Web application.
Defina o nome do cliente OAuth como OAUTH_CLIENT_DISPLAY_NAME.
Em URIs de redirecionamento autorizados, adicione o URI para REDIRECT_URI.
Em "Chaves secretas do cliente", clique no botão "Fazer o download do JSON". Um arquivo client_secret.json é baixado com o seguinte conteúdo:

{'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.
}}

Armazene o ID do cliente e a chave secreta no Secret Manager, por exemplo,

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

Listar clientes OAuth

No console do Google Cloud , acesse a página Plataforma do Google Auth > Clientes, que lista as credenciais do cliente OAuth.

Acesse Google Auth Platform > Clientes.

Excluir um cliente OAuth

No console do Google Cloud , acesse a página Google Auth Platform > Clientes.

Acesse Google Auth Platform > Clientes.
Selecione as credenciais de cliente OAuth que serão excluídas e clique em "Excluir".

Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês)

Por padrão, o Google Cloud criptografa automaticamente os dados em repouso usando chaves de criptografia gerenciadas pelo Google. Se você tiver requisitos regulatórios ou de compliance específicos relacionados às chaves que protegem seus dados, use as chaves de criptografia gerenciadas pelo cliente (CMEK) para os agentes implantados.

Consulte a documentação sobre CMEK para a plataforma de agentes do Gemini Enterprise para ver os requisitos gerais e orientações sobre o uso de CMEK com a plataforma de agentes do Gemini Enterprise, incluindo:

Configuração do projeto (faturamento e APIs ativadas)
Criação de keyrings e chaves
Concessões de permissão necessárias

Para ativar a CMEK no agente, especifique o encryption_spec com a chave do Cloud Key Management Service ao criar uma instância da Agent Platform. Consulte Configurar chaves de criptografia gerenciadas pelo cliente para ver exemplos de código.

Limitações

As seguintes limitações se aplicam ao usar CMEK com o Agent Runtime:

Chaves multirregionais não são permitidas: apenas chaves de região única são compatíveis. A região do keyring e da chave precisa ser a mesma da instância da plataforma de agente.
A chave de criptografia não pode ser atualizada para instâncias de CMEK: depois que um agente é implantado com uma chave CMEK, a chave de criptografia não pode ser alterada para essa implantação. Para usar uma nova chave, é necessário implantar uma nova instância da Agent Platform.
Alguns metadados e dados operacionais não são criptografados com sua chave: a CMEK criptografa os dados principais do agente em repouso. No entanto, alguns metadados e dados operacionais de ambiente de execução não são criptografados com sua chave. Em vez disso, eles são criptografados usando a criptografia padrão do Google. Isso inclui:
- Metadados do agente:
  - Os nomes de exibição
  - Descrições
- Dados operacionais do ambiente de execução:
  - E-mails da conta de serviço
  - Nomes de métodos de classe de objeto do agente
  - Variáveis de ambiente

VPC Service Controls (VPC-SC)

O Agent Runtime é compatível com o VPC Service Controls para reforçar a segurança de dados e reduzir os riscos de exfiltração de dados.

Quando o VPC Service Controls é configurado, o agente implantado mantém o acesso seguro às APIs e aos serviços do Google, como a API BigQuery, a API Cloud SQL Admin e a API Agent Platform, verificando a operação perfeita dentro do perímetro definido. O VPC Service Controls bloqueia de forma eficaz todo o acesso à Internet público, restringindo o movimento de dados aos limites da sua rede autorizada e melhorando significativamente a postura de segurança da sua empresa.

As opções de implantação disponíveis estão listadas em Implantar um agente. Dependendo da opção de implantação, as seguintes regras de entrada precisam ser configuradas:

Para implantações baseadas em pickle, é necessário ter entrada para os serviços storage.googleapis.com e artifactregistry.googleapis.com.
Para implantações baseadas em origem, baseadas em Git e traga seu próprio Dockerfile (BYOD), é necessário ter entrada para o serviço artifactregistry.googleapis.com.
Para implantações de traga seu próprio contêiner (BYOC, na sigla em inglês), nenhuma regra de entrada adicional é necessária.

Limitações

O VPC Service Controls não é compatível com o Gateway de Agente.

No entanto, é possível usar restrições personalizadas da política da organização para restringir quais gateways podem ser associados aos seus agentes. Para mais informações, consulte Rotear o tráfego pelo Gateway de Agente.

Gerenciar o acesso para agentes implantados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Identidade do agente

Contas de serviço

Agente de serviço do mecanismo de raciocínio da plataforma de IA

Listar os papéis de um agente implantado

Console

gcloud

Python

Conceder papéis para um agente implantado

Console (recomendado)

gcloud

Python

Revogar papéis de um agente implantado

Console (recomendado)

gcloud

Python

Chaves de API

Criar um secret

Console

gcloud

Python

Receber um secret

Console

gcloud

Python

Listar secrets

Console

gcloud

Python

Atualizar um secret

Console

gcloud

Python

Excluir um secret

Console

gcloud

Python

Clientes e credenciais OAuth

Criar uma credencial de cliente OAuth

Listar clientes OAuth

Excluir um cliente OAuth

Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês)

Limitações

VPC Service Controls (VPC-SC)

Limitações

Gerenciar o acesso para agentes implantados