Como gerenciar o acesso a agentes implantados

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

Caso de uso	Método de autenticação	Sobre esse método de autenticação
Acesse as fontes de dados diretamente em um agente.	Conta de serviço	Os agentes implantados têm acesso a todos os recursos que a conta de serviço tem permissão para acessar.
Envie solicitações para endpoints usando chaves de API em um agente.	Chaves de API	Verifique se a API que você quer usar é compatível com chaves de API antes de usar esse método de autenticação.
Processar contas de usuário, registro, login ou autorização para os usuários finais do agente.	ID do cliente OAuth	Requer que o agente solicite e receba o consentimento do usuário.

Papéis

Os agentes implantados no mecanismo de agente são executados usando a conta de serviço do agente de serviço do mecanismo de raciocínio do AI Platform que corresponde a [e-mail].

A conta de serviço tem um papel (roles/aiplatform.reasoningEngineServiceAgent) de Agente de serviço do mecanismo de raciocínio da Vertex AI, que concede as permissões padrão necessárias para agentes implantados. Confira a lista completa de permissões padrão na documentação do IAM.

Listar os papéis de um agente implantado

Console

1. Acesse a página IAM e marque a caixa de seleção "Incluir concessões de papéis fornecidos pelo Google".

   Acessar IAM

2. Selecione o projeto correspondente ao Google Cloud .

3. Encontre o Participante que corresponde a [e-mail].

4. As funções do agente implantado podem ser encontradas 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)"

em que

• PROJECT_ID_OR_NUMBER é o ID ou número do projeto.
• PRINCIPAL é baseado na conta de serviço gerada quando o agente é implantado no Agente Engine.

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, autentique-se e execute o seguinte para listar as funções 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 gerada quando o agente é implantado no Agente Engine.

Conceder papéis a um agente implantado

Console (recomendado)

1. Acesse a página IAM e marque a caixa de seleção "Incluir concessões de papéis fornecidos pelo Google".

   Acessar IAM

2. Selecione o projeto correspondente ao Google Cloud .

3. Encontre o Participante que corresponde a [e-mail].

4. Adicione os papéis necessários ao Participante 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 seguinte comando:

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

em que

• PRINCIPAL é baseado na conta de serviço gerada quando o agente é implantado no Agente Engine.
• 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 funções para agentes implantados. Em vez disso, recomendamos usar o console do Google Cloud ou gcloud para operações únicas ou o Terraform para gerenciar o controle de acesso do IAM de forma 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)

1. Acesse a página IAM e marque a caixa de seleção "Incluir concessões de papéis fornecidos pelo Google".

   Acessar IAM

2. Selecione o projeto correspondente ao Google Cloud .

3. Encontre o Participante que corresponde a [e-mail].

4. Revogue as funções do principal clicando no botão de edição, removendo as funções correspondentes e depois clicando no botão "Salvar".

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

em que

• PRINCIPAL é baseado na conta de serviço gerada quando o agente é implantado no Agente Engine.
• 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

Não recomendamos escrever seu próprio código Python para conceder ou revogar funções 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 forma programática. Se você quiser ou precisar fazer isso em Python, consulte a documentação da biblioteca de cliente do IAM.

Secrets

Um secret contém uma ou mais versões dele, junto com metadados como rótulos e informações de replicação. O payload real de um secret é armazenado em uma versão do secret. Os segredos 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 filtrar.

Criar um secret

Console

1. Acesse a página Secret Manager.

   Acessar o Secret Manager

2. Na página Gerenciador de secrets, clique em Criar secret.

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

4. Opcional: para adicionar uma versão do secret ao criar o secret inicial, no campo Valor do secret, insira um valor para o secret (por exemplo, abcd1234).

5. Acesse Rótulos e clique em Adicionar rótulo.

6. Insira uma chave e o valor correspondente para criar um rótulo.

7. 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 segredo ou o identificador totalmente qualificado do segredo.
• 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 para 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, 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}")

Conferir um secret

Console

1. Acesse a página Secret Manager.

   Acessar o Secret Manager

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

3. A página Detalhes do secret lista 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

em que

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

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

Listar secrets

Console

1. Acesse a página Secret Manager.

   Acessar o Secret Manager

2. Na tabela "Chaves secretas", clique no campo Filtro.

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

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

5. (Opcional) Para filtrar versões de segredos: selecione um segredo 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 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 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 segredo ou o identificador totalmente qualificado para o segredo.

Para mais detalhes, acesse a documentação do Secret Manager para filtrar secrets e listar 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, 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}")

Atualizar um secret

Console

1. Acesse a página Secret Manager.

   Acessar o Secret Manager

2. Na página do Gerenciador de secrets, clique na caixa de seleção ao lado do nome do secret.

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

4. No painel de informações, clique na guia Rótulos.

5. Clique em Adicionar rótulo e insira uma chave e um valor para o rótulo.

6. Clique em Salvar.

gcloud

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

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

em que

• SECRET_ID é o ID do segredo ou o identificador totalmente qualificado do segredo.
• KEY é a chave do rótulo e
• 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, 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}")

Excluir um secret

Console

1. Acesse a página Secret Manager.

   Acessar o Secret Manager

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

3. No menu, selecione Excluir.

4. Na caixa de diálogo Excluir secret, insira o nome do secret.

5. Clique no botão Excluir secret.

gcloud

Primeiro instale e inicialize a CLI gcloud.

Para excluir uma versão do 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 segredo ou o identificador totalmente qualificado do segredo.

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

gcloud secrets delete SECRET_ID

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

Para mais detalhes, acesse a documentação do Secret Manager para excluir um secret e 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, 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 do 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á do próprio ID do cliente. Em um nível alto, para integrar um agente baseado em OAuth, faça o seguinte:

1. Crie um cliente e uma credencial OAuth.

2. Armazene o ID e o secret do cliente no Secret Manager. Consulte Criar um secret.

3. Acesse o secret no seu agente durante o desenvolvimento.

Observação: consulte Como configurar o OAuth 2.0 para mais informações. Saiba mais sobre os tipos de clientes OAuth.

Criar uma credencial de cliente OAuth

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

   Acesse a Plataforma Google Auth > Clientes

2. (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 saber se a produção está pronta, acesse a conformidade com a política do OAuth 2.0.

3. Clique em Criar cliente.

4. Defina o Tipo de aplicativo 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 "Chaves secretas do cliente", clique no botão "Fazer o download do JSON". Ele vai fazer o download de um arquivo 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 e o secret do cliente 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),
    },
})

Observação: é possível verificar se a credencial do cliente OAuth foi armazenada no Secret Manager pelo console do Google Cloud.

Listar clientes OAuth

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

   Acesse a Plataforma Google Auth > Clientes

2. Ele vai listar as credenciais do cliente OAuth que você tem.

Excluir um cliente OAuth

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

   Acesse a Plataforma Google Auth > Clientes

2. Selecione as credenciais de cliente OAuth que serão excluídas e clique em "Excluir".