Gerir o acesso para agentes implementados

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

Exemplo de utilização	Método de autenticação	Acerca deste método de autenticação
Aceder a origens de dados diretamente a partir de um agente.	Conta de serviço	Os agentes implementados têm acesso a todos os recursos aos quais a respetiva conta de serviço tem autorização de acesso.
Enviar pedidos para pontos finais através de chaves de API a partir de um agente.	Chaves de API	Verifique se a API que quer usar suporta chaves da API antes de usar este método de autenticação.
Gerir contas de utilizador, registo, início de sessão ou autorização para os utilizadores finais do agente.	ID de cliente OAuth	Requer que o seu agente peça e receba o consentimento do utilizador.

Funções

Os agentes que implementa 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. Consulte o artigo Configure a identidade e as autorizações do seu agente para mais informações.

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 [e-mail].

A conta de serviço tem uma função (roles/aiplatform.reasoningEngineServiceAgent) do agente do serviço do Reasoning Engine do Vertex AI 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

1. Aceda à página IAM.

   Aceder ao IAM

2. Selecione o projeto correspondente ao seu Google Cloud projeto.

3. Encontre o principal que corresponde à conta de serviço usada como identidade do agente.

4. Pode encontrar as funções do agente implementado na coluna Função.

Nota: para a conta de serviço Agente do serviço do AI Platform Reasoning Engine, tem de selecionar "Incluir concessões de funções fornecidas pela Google" para apresentar a conta de serviço na tabela de responsáveis.

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

1. Aceda à página IAM.

   Aceder ao IAM

2. Selecione o projeto correspondente ao seu Google Cloud projeto.

3. Encontre o principal que corresponde à conta de serviço usada como identidade do agente.

4. 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.

Nota: para a conta de serviço Agente do serviço do AI Platform Reasoning Engine, tem de selecionar "Incluir concessões de funções fornecidas pela Google" para apresentar a conta de serviço na tabela de responsáveis.

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 consolagcloud ou o gcloud para operações únicas, ou o Terraform para gerir o controlo de acesso do 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)

1. Aceda à página IAM.

   Aceder ao IAM

2. Selecione o projeto correspondente ao seu Google Cloud projeto.

3. Encontre o principal que corresponde à conta de serviço usada como identidade do agente.

4. 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.

Nota: para a conta de serviço Agente do serviço do AI Platform Reasoning Engine, tem de selecionar "Incluir concessões de funções fornecidas pela Google" para apresentar a conta de serviço na tabela de responsáveis.

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

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 consolagcloud ou o gcloud para operações únicas, ou o Terraform para gerir o controlo de acesso do IAM de forma programática. Se quiser ou precisar de o fazer em Python, consulte a documentação da biblioteca cliente do IAM.

Secrets

Um segredo 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

1. Aceda à página Secret Manager.

   Aceda ao Secret Manager

2. Na página Secret Manager, clique em Create Secret.

3. No campo Nome, introduza um nome para o segredo (por exemplo, my-secret).

4. 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).

5. Aceda a Etiquetas e, de seguida, clique em Adicionar etiqueta.

6. Introduza uma chave e o respetivo valor correspondente para criar uma etiqueta.

7. 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

1. Aceda à página Secret Manager.

   Aceda ao Secret Manager

2. Na página Secret Manager, clique no nome de um segredo para descrever.

3. 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, 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.get_secret(request={"name": name})

Apresente segredos

Consola

1. Aceda à página Secret Manager.

   Aceda ao Secret Manager

2. Na tabela Segredos, clique no campo Filtro.

3. Escolha uma propriedade de filtro e o respetivo valor, por exemplo, Location:asia-east1.

4. A tabela é filtrada automaticamente com base nos valores introduzidos.

5. (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

1. Aceda à página Secret Manager.

   Aceda ao Secret Manager

2. Na página Secret Manager, clique na caixa de verificação junto ao nome do segredo.

3. Se o painel de informações estiver fechado, clique em Mostrar painel de informações para o apresentar.

4. No Painel de informações, selecione o separador Etiquetas.

5. Clique em Adicionar etiqueta e introduza uma chave e um valor para a etiqueta.

6. 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

1. Aceda à página Secret Manager.

   Aceda ao Secret Manager

2. Na página Secret Manager, na coluna Ações do segredo, clique em Ver mais.

3. No menu, selecione Eliminar.

4. Na caixa de diálogo Eliminar segredo, introduza o nome do segredo.

5. 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 Secret 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 um segredo, ou a referência da CLI para eliminar um segredo e destruir uma versão de um 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 uma precisa do seu próprio ID de cliente. A um nível elevado, para integrar um agente baseado em OAuth, faz o seguinte:

1. Crie um cliente e uma credencial OAuth.

2. Armazene o ID de cliente e o segredo no Secret Manager. (Consulte Crie um segredo).

3. Aceder ao segredo no seu agente durante o desenvolvimento.

Nota: consulte o artigo Configurar o OAuth 2.0 para mais informações. Saiba mais acerca dos tipos de clientes OAuth.

Crie uma credencial de cliente OAuth

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

   Aceda a Google Auth Platform > Clients

2. (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.

3. Clique em Criar cliente.

4. Defina o Tipo de aplicação como Web application.

5. Defina o nome do cliente OAuth como OAUTH_CLIENT_DISPLAY_NAME.

6. Em URIs de redirecionamento autorizados, adicione o URI para REDIRECT_URI.

7. Em Segredos do cliente, clique no botão "Transferir JSON". É transferido um ficheiro client_secret.json 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.
}}

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

Nota: pode verificar se a credencial do cliente OAuth foi armazenada no Secret Manager através da Google Cloud consola.

Liste os clientes OAuth

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

   Aceda a Google Auth Platform > Clients

2. São apresentadas as credenciais do cliente OAuth que tem.

Elimine um cliente OAuth

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

   Aceda a Google Auth Platform > Clients

2. 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 uma única região. A região do porta-chaves e da chave tem de ser a mesma que a da 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 de agentes
    • Variáveis de ambiente