Esta página foi traduzida pela API Cloud Translation.

Gerir o acesso para agentes implementados

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

Método de autenticação	Exemplo de utilização	Acerca deste método de autenticação
Identidade do agente (pré-visualização)	Aceder a origens de dados diretamente a partir de um agente.	Um agente implementado com a identidade do agente pode aceder a recursos de acordo com as autorizações de IAM que concede ao agente.
Contas de serviço	Aceder a origens de dados diretamente a partir de um agente.	Os agentes implementados têm acesso a todos os recursos aos quais a respetiva conta de serviço tem autorização de acesso.
Chaves de API	Envie pedidos para pontos finais através de chaves de API a partir de um agente.	Verifique se a API que quer usar suporta chaves da API antes de usar este método de autenticação.
ID de cliente OAuth	Gerir contas de utilizador, registo, início de sessão ou autorização para os utilizadores finais do agente.	Requer que o seu agente peça e receba o consentimento do utilizador.

Identidade do agente

Se usou a identidade do agente para configurar a identidade e as autorizações do seu agente, consulte o artigo Use agent identity with Vertex AI Agent Engine para informações sobre como gerir o controlo de acesso aos recursos.

Contas de serviço

Se usou contas de serviço para configurar a identidade e as autorizações do seu agente, os agentes que implementar no Vertex AI Agent Engine são executados através do agente do serviço AI Platform Reasoning Engine ou da sua conta de serviço personalizada.

Agente de serviço do motor de raciocínio da AI Platform

A conta de serviço do agente do serviço do AI Platform Reasoning Engine usa o formato service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

A conta de serviço tem uma função de agente do serviço do Reasoning Engine do Vertex AI (roles/aiplatform.reasoningEngineServiceAgent) que concede as autorizações predefinidas necessárias para os agentes implementados. Pode ver a lista completa de autorizações predefinidas na documentação do IAM.

Indique as funções de um agente implementado

Consola

Aceda à página IAM.

Aceda ao IAM
Selecione o projeto correspondente ao seu Google Cloud projeto.
Encontre o principal que corresponde à conta de serviço usada como identidade do agente.
Pode encontrar as funções do agente implementado na coluna Função.

gcloud

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

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

onde

PROJECT_ID_OR_NUMBER é o ID ou o número do seu projeto e
PRINCIPAL baseia-se na conta de serviço que foi usada quando o agente é implementado no Vertex AI Agent Engine.

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

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-api-python-client

Em seguida, autentique-se e execute o seguinte para listar as funções de um 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)

Em que o PRINCIPAL se baseia na conta de serviço que foi usada quando o agente é implementado no Vertex AI Agent Engine.

Conceda funções para um agente implementado

Consola (recomendado)

Aceda à página IAM.

Aceda ao IAM
Selecione o projeto correspondente ao seu Google Cloud projeto.
Encontre o principal que corresponde à conta de serviço usada como identidade do agente.
Adicione as funções necessárias ao Principal clicando no botão de edição, adicionando as funções e, de seguida, clicando no botão de guardar.

gcloud

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

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

onde

PRINCIPAL baseia-se na conta de serviço que foi usada quando o agente é implementado no Vertex AI Agent Engine.
ROLE_NAME é o nome da função que quer conceder. Para ver uma lista de funções predefinidas, consulte o artigo Compreender as funções.

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

Python

Não recomendamos que escreva o seu próprio código Python para conceder ou revogar funções para agentes implementados. Em alternativa, recomendamos que use a Google Cloud consola ou o gcloudTerraform para gerir o controlo de acesso da IAM de forma programática. Se quiser ou precisar de o fazer em Python, consulte a documentação da biblioteca cliente do IAM.

Revogue funções de um agente implementado

Consola (recomendado)

Aceda à página IAM.

Aceda ao IAM
Selecione o projeto correspondente ao seu Google Cloud projeto.
Encontre o principal que corresponde à conta de serviço usada como identidade do agente.
Revogue as funções do Principal clicando no botão de edição, removendo as funções correspondentes e, de seguida, clicando no botão de guardar.

gcloud

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

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

onde

PRINCIPAL baseia-se na conta de serviço que foi usada quando o agente é implementado no Vertex AI Agent Engine.
ROLE_NAME é o nome da função que quer revogar. Para ver uma lista de funções predefinidas, consulte o artigo Compreender as funções.

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

Python

Chaves da API

As chaves da API usam segredos, que contêm uma ou mais versões secretas, juntamente com metadados, como etiquetas e informações de replicação. A carga útil real de um segredo é armazenada numa versão do segredo. Os segredos são geridos (através do Secret Manager) ao nível do projeto e podem ser partilhados entre agentes implementados. Para listar os segredos correspondentes a um agente no Secret Manager, pode adicionar etiquetas e usá-las para filtragem.

Crie um segredo

Consola

Aceda à página Secret Manager.

Aceda ao Secret Manager
Na página Secret Manager, clique em Create Secret.
No campo Nome, introduza um nome para o segredo (por exemplo, my-secret).
Opcional: para também adicionar uma versão do Secret quando criar o Secret inicial, no campo Valor do Secret, introduza um valor para o Secret (por exemplo, abcd1234).
Aceda a Etiquetas e, de seguida, clique em Adicionar etiqueta.
Introduza uma chave e o respetivo valor correspondente para criar uma etiqueta.
Clique em Criar segredo.

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"

onde

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

Para obter detalhes, consulte a documentação do Secret Manager para criar um segredo e uma versão do segredo ou a referência da CLI para criar um segredo e uma versão do segredo, respetivamente.

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-cloud-secret-manager

Em seguida, autentique-se e execute o seguinte

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

Obtenha um segredo

Consola

Aceda à página Secret Manager.

Aceda ao Secret Manager
Na página Secret Manager, clique no nome de um segredo para descrever.
A página Detalhes do Secret apresenta informações sobre o Secret.

gcloud

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

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

onde

VERSION_ID é o ID da versão do Secret e
SECRET_ID é o ID do segredo ou o identificador totalmente qualificado do segredo.

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

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-cloud-secret-manager

Em seguida, autentique-se e execute o seguinte

from google.cloud import secretmanager

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

Apresente segredos

Consola

Aceda à página Secret Manager.

Aceda ao Secret Manager
Na tabela Segredos, clique no campo Filtro.
Escolha uma propriedade de filtro e o respetivo valor, por exemplo, Location:asia-east1.
A tabela é filtrada automaticamente com base nos valores introduzidos.
(Opcional) Para filtrar versões secretas: selecione um segredo para aceder às respetivas versões e, de seguida, use a opção Filtrar na tabela Versões.

gcloud

Primeiro, instale e inicialize a CLI gcloud.

Para apresentar uma lista de todos os segredos 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 apresentar uma lista de todas as versões de um segredo, execute o seguinte comando:

gcloud secrets versions list SECRET_ID

onde SECRET_ID é o ID do segredo ou o identificador totalmente qualificado do segredo.

Para ver detalhes, visite a documentação do Secret Manager para filtrar segredos e listar versões de segredos, ou a referência da CLI para listar segredos e versões de segredos, respetivamente.

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-cloud-secret-manager

Em seguida, autentique-se e execute o seguinte

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

Atualize um segredo

Consola

Aceda à página Secret Manager.

Aceda ao Secret Manager
Na página Secret Manager, clique na caixa de verificação junto ao nome do segredo.
Se o painel de informações estiver fechado, clique em Mostrar painel de informações para o apresentar.
No painel de informações, selecione o separador Etiquetas.
Clique em Adicionar etiqueta e introduza uma chave e um valor para a etiqueta.
Clique em Guardar.

gcloud

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

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

onde

SECRET_ID é o ID do segredo ou o identificador totalmente qualificado do segredo,
KEY é a chave da etiqueta e
VALUE é o valor correspondente da etiqueta.

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

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-cloud-secret-manager

Em seguida, autentique-se e execute o seguinte

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

Elimine um segredo

Consola

Aceda à página Secret Manager.

Aceda ao Secret Manager
Na página Secret Manager, na coluna Ações do segredo, clique em Ver mais.
No menu, selecione Eliminar.
Na caixa de diálogo Eliminar segredo, introduza o nome do segredo.
Clique no botão Eliminar segredo.

gcloud

Primeiro, instale e inicialize a CLI gcloud.

Para eliminar uma versão secreta, execute o seguinte comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

onde

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

Para eliminar um segredo e todas as respetivas versões, execute o seguinte comando:

gcloud secrets delete SECRET_ID

onde SECRET_ID é o ID do segredo ou o identificador totalmente qualificado do segredo

Para obter detalhes, visite a documentação do Secret Manager para eliminar um segredo e destruir uma versão de segredo, ou a referência da CLI para eliminar um segredo e destruir uma versão de segredo.

Python

Primeiro, instale a biblioteca de cliente executando o seguinte comando:

pip install google-cloud-secret-manager

Em seguida, autentique-se e execute o seguinte

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 de cliente é usado para identificar um único agente nos servidores OAuth da Google. Se o seu agente for executado em várias plataformas, cada plataforma precisa do seu próprio ID do cliente. A um nível elevado, para integrar um agente baseado em OAuth, faz o seguinte:

Crie um cliente e uma credencial OAuth.
Armazene o ID de cliente e o segredo no Secret Manager. (Consulte Crie um segredo).
Aceder ao segredo no seu agente durante o desenvolvimento.

Crie uma credencial do cliente OAuth

Na Google Cloud consola, aceda à página Google Auth Platform > Clients.

Aceda a Google Auth Platform > Clients
(Se necessário) Se o ecrã apresentar a mensagem "A plataforma de autenticação da Google ainda não foi configurada", clique em Introdução e preencha as Configurações do projeto. (Podem ser atualizadas mais tarde.) Para ver detalhes sobre a prontidão para produção, visite o artigo Conformidade com a Política do OAuth 2.0.
Clique em Criar cliente.
Defina o Tipo de aplicação 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 Segredos do cliente, clique no botão "Transferir JSON". Um ficheiro client_secret.json é transferido 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 de cliente e o segredo 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),
    },
})

Liste os clientes OAuth

Na Google Cloud consola, aceda à página Google Auth Platform > Clients, que apresenta as credenciais do cliente OAuth.

Aceda a Google Auth Platform > Clients

Elimine um cliente OAuth

Na Google Cloud consola, aceda à página Google Auth Platform > Clients.

Aceda a Google Auth Platform > Clients
Selecione as credenciais do cliente OAuth a eliminar e clique em Eliminar.

Chaves de encriptação geridas pelo cliente (CMEK)

Por predefinição, Google Cloud encripta automaticamente os dados quando estão em repouso através de chaves de encriptação geridas pela Google. Se tiver requisitos de conformidade ou regulamentares específicos relacionados com as chaves que protegem os seus dados, pode usar chaves de encriptação geridas pelo cliente (CMEK) para os seus agentes implementados.

Consulte a documentação CMEK para o Vertex AI para ver os requisitos gerais e as orientações sobre a utilização das CMEK com o Vertex AI, incluindo:

Configuração do projeto (faturação e APIs ativadas)
Criação de conjuntos de chaves e chaves
Concessões de autorizações necessárias

Para ativar as CMEK para o seu agente, tem de especificar o encryption_spec com a sua chave do Cloud KMS quando criar uma instância do Agent Engine. Consulte o artigo Configure chaves de encriptação geridas pelo cliente para ver exemplos de código.

Limitações

Aplicam-se as seguintes limitações quando usa as CMEK com o Vertex AI Agent Engine:

Não são permitidas chaves de várias regiões: apenas são suportadas chaves de região única. A região do porta-chaves e da chave tem de ser a mesma que a da sua instância do Agent Engine.
Não é possível atualizar a chave de encriptação para instâncias de CMEK: depois de um agente ser implementado com uma chave de CMEK, não é possível alterar a chave de encriptação para essa implementação. Para usar uma nova chave, tem de implementar uma nova instância do Agent Engine.
Determinados metadados e dados operacionais não encriptados: a CMEK encripta os dados principais do agente em repouso. No entanto, determinados metadados e dados operacionais de tempo de execução não são encriptados. Isto inclui:
- Metadados do agente:
  - Nomes a apresentar
  - Descrições
- Dados operacionais do tempo de execução:
  - Emails de contas de serviço
  - Nomes dos métodos da classe de objetos do agente
  - Variáveis de ambiente

Gerir o acesso para agentes implementados 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 motor de raciocínio da AI Platform

Indique as funções de um agente implementado

Consola

gcloud

Python

Conceda funções para um agente implementado

Consola (recomendado)

gcloud

Python

Revogue funções de um agente implementado

Consola (recomendado)

gcloud

Python

Chaves da API

Crie um segredo

Consola

gcloud

Python

Obtenha um segredo

Consola

gcloud

Python

Apresente segredos

Consola

gcloud

Python

Atualize um segredo

Consola

gcloud

Python

Elimine um segredo

Consola

gcloud

Python

Clientes e credenciais OAuth

Crie uma credencial do cliente OAuth

Liste os clientes OAuth

Elimine um cliente OAuth

Chaves de encriptação geridas pelo cliente (CMEK)

Limitações

Gerir o acesso para agentes implementados