Configurar o ambiente

Antes de trabalhar com o Agent Runtime, você precisa verificar se o ambiente está configurado. Você precisa ter um projeto do Google Cloud com o faturamento ativado, ter as permissões necessárias, configurar um bucket do Cloud Storage e instalar o SDK da plataforma de agente para Python. Confira os tópicos a seguir para começar a trabalhar com o Agent Runtime.

Para um exemplo de referência do Terraform que simplifica a configuração e a implantação do ambiente do Agent Runtime, confira o agent-starter-pack.

Configurar com Google Cloud

É possível configurar com Google Cloud para o Agent Runtime criando um projeto Google Cloud .

Projeto do Google Cloud

Cada projeto pode ser identificado de duas formas: pelo número ou pelo ID. O PROJECT_NUMBER é criado automaticamente quando você cria o projeto, enquanto o PROJECT_ID é criado por você ou por quem criou o projeto. Para configurar um projeto:

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Ter os papéis necessários

Para receber as permissões necessárias para usar o Agent Runtime, peça ao administrador para conceder a você o papel do IAM de Usuário da plataforma de agentes (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Configurar a identidade e as permissões do agente

Você tem as seguintes opções ao configurar a identidade e as permissões:

Identidade do agente (recomendado) Use a identidade do agente do Identity Access Management (IAM) para fornecer recursos de segurança e gerenciamento de acesso ao usar agentes no Agent Runtime. A identidade do agente está vinculada a cada agente individual. Por padrão, os agentes têm o papel Acesso padrão do agente da plataforma de agentes (roles/aiplatform.agentDefaultAccess), que inclui apenas permissões básicas de geração de registros e de chamada de modelo em todo o projeto, e o papel Editor de contexto do agente da plataforma de agentes (roles/aiplatform.agentContextEditor), que limita o acesso de um agente apenas às próprias sessões, memórias e sandboxes.

Observação: alguns recursos acessíveis por essa função podem estar em pré-lançamento
Contas de serviço: as contas de serviço são compartilhadas entre os agentes implantados no ambiente de execução do agente. Você tem duas opções para a conta de serviço:
- Agente de serviço padrão:por padrão, os agentes usam o agente de serviço do mecanismo de raciocínio do AI Platform. Essa conta de serviço gerenciado pelo Google tem o papel de Agente de serviço do mecanismo de raciocínio da plataforma de agentes do Gemini Enterprise (roles/aiplatform.reasoningEngineServiceAgent), que inclui as permissões padrão necessárias para agentes implantados.
- Conta de serviço personalizada:é possível especificar sua própria conta de serviço para os agentes usarem. Isso oferece um controle mais granular sobre as permissões concedidas aos agentes.

Identidade do agente

Para configurar políticas do IAM antes de implantar o agente, você pode criar uma identidade de agente sem implantar o código dele. Para isso, crie uma instância da plataforma de agentes com apenas o campo identity_type:

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

Depois de criar a instância da plataforma de agentes com a identidade do agente, é possível fazer o seguinte:

Conceda à identidade do agente papéis adicionais conforme necessário para seu caso de uso.
Adicione o código do agente usando agent_engine.update(...).

Agente de serviço padrão

O agente de serviço do mecanismo de raciocínio do AI Platform é usado por padrão. Confira a lista completa de permissões padrão na documentação do IAM.

Se o agente de serviço precisar de permissões além do conjunto padrão, conceda outros papéis a ele:

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

Acessar IAM
Encontre o principal que corresponde a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.
Adicione os papéis necessários ao principal clicando no botão de edição e, em seguida, no botão "Salvar".

Gerar manualmente o agente de serviço padrão

Embora o agente de serviço do mecanismo de raciocínio seja provisionado automaticamente durante a implantação do tempo de execução do agente, pode haver cenários em que é necessário gerá-lo manualmente antes. Isso é particularmente importante quando você precisa conceder papéis específicos ao agente de serviço para garantir que o processo de implantação tenha as permissões necessárias e evitar possíveis falhas de implantação.

Estas são as etapas para gerar manualmente um agente de serviço do mecanismo de raciocínio:

Gere o agente de serviço do Reasoning Engine usando a Google Cloud CLI.
```
gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER
```
Observação: a resposta ao comando da Google Cloud CLI pode mostrar apenas o agente de serviço da Vertex AI. No entanto, o agente de serviço do Reasoning Engine também é criado.
Acesse a página do IAM e clique em Conceder acesso.

Acessar IAM
Na seção Adicionar principais, no campo Novos principais, digite service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.
Na seção Atribuir papéis, encontre e selecione os papéis necessários.
Clique no botão Salvar.

Conta de serviço personalizada

Para usar sua própria conta de serviço, conceda a ela as permissões necessárias para executar o agente. Sua conta de serviço personalizada provavelmente precisa do papel Usuário da plataforma do agente (roles/aiplatform.user).

Se você não tiver uma conta de serviço, crie uma. Consulte Criar contas de serviço.
Conceda à conta de serviço o papel Usuário da plataforma do agente (roles/aiplatform.user).
Conceda à conta de serviço todos os outros papéis exigidos pelo código do agente.
Para implantar o agente com essa conta de serviço, conceda a si mesmo o papel Usuário da conta de serviço (roles/iam.serviceAccountUser) nessa conta de serviço personalizada.
Ao implantar o agente, especifique o endereço de e-mail da sua conta de serviço personalizada. Consulte Configurar uma conta de serviço personalizada para mais detalhes.

Conta de serviço personalizada entre projetos

Se a conta de serviço personalizada for de um projeto diferente, serão necessárias outras configurações no projeto em que a conta de serviço reside e no projeto em que você implanta o agente.

Desative a política da organização para uso de contas de serviço entre projetos:no projeto em que a conta de serviço está localizada, verifique se a política da organização iam.disableCrossProjectServiceAccountUsage NÃO está sendo aplicada. Consulte Desativar a aplicação do uso conta de serviço entre projetos para mais detalhes.
Conceda permissões ao agente de serviço da plataforma de agentes:no projeto em que a conta de serviço está localizada, conceda o papel Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço da plataforma de agentes (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) do projeto em que você planeja implantar o agente.
Conceda permissões à conta de serviço personalizada:no projeto em que você planeja implantar o agente, conceda os papéis necessários à conta de serviço personalizada. Isso geralmente inclui a função Usuário da plataforma de agente (roles/aiplatform.user) e outras funções exigidas pelo código do agente.

(Opcional) Criar um bucket do Cloud Storage

A necessidade de um bucket do Cloud Storage depende de se o SDK da plataforma de agentes para Python precisa de um lugar para organizar o código do agente antes da implantação:

Implantação de arquivos de origem: o agente existe como arquivos. O SDK da plataforma de agente para Python pode agrupar e fazer upload desses arquivos diretamente para o serviço de implantação. Assim, não é necessário um bucket de preparo do Cloud Storage.
Fazer implantação do objeto do agente: o agente existe na memória. O SDK da plataforma de agente para Python empacota esse objeto e faz upload dele para um bucket do Cloud Storage, que atua como uma área de preparo para o serviço de implantação.

Implantar de arquivos de origem

Se você implantar um agente de arquivos de origem, não é necessário um bucket do Cloud Storage.

Implantar do objeto

Ao implantar de um objeto de agente, o Agent Runtime organiza os artefatos dos agentes implantados em um bucket do Cloud Storage como parte do processo de implantação. Verifique se o principal autenticado para usar a plataforma de agentes do Gemini Enterprise (você ou uma conta de serviço) tem acesso Storage Admin a esse bucket. Isso é necessário porque o SDK da plataforma de agentes para Python grava seu código nesse bucket.

Se você já tiver um bucket configurado, pule esta etapa. Caso contrário, siga as instruções padrão para criar um bucket.

Peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto.

Console doGoogle Cloud

No console do Google Cloud , acesse a página Buckets do Cloud Storage.
Acessar buckets
Clique em Criar.
Na página Criar um bucket, insira as informações do seu bucket. Para ir à próxima etapa, clique em Continuar.
1. Na seção Começar, faça o seguinte:
  - Insira um nome globalmente exclusivo que atenda aos requisitos de nomeação de bucket.
  - Para adicionar um rótulo de bucket, abra a seção Rótulos (), clique em Adicionar rótulo e especifique um key e um value para o rótulo.
2. Na seção Escolha onde armazenar seus dados, faça o seguinte:
  1. Selecione um tipo de local.
  2. Escolha um local onde os dados do bucket são armazenados permanentemente no menu suspenso Tipo de local.
    - Se você selecionar o tipo de local birregional, também poderá ativar a replicação turbo usando a caixa de seleção relevante.
  3. Para configurar a replicação entre buckets, selecione Adicionar replicação entre buckets usando o Serviço de transferência do Cloud Storage e siga estas etapas:
    Configurar a replicação entre buckets
    
    No menu Bucket, selecione um bucket.
    
    Na seção Configurações de replicação, clique em Configurar para definir as configurações do job de replicação.
    
    O painel Configurar a replicação entre buckets aparece.
    
    Para filtrar objetos a serem replicados por prefixo de nome de objeto, insira um prefixo com que você quer incluir ou excluir objetos e clique em Adicionar um prefixo.
    
    Para definir uma classe de armazenamento para os objetos replicados, selecione uma classe de armazenamento no menu Classe de armazenamento. Se você pular esta etapa, os objetos replicados vão usar a classe de armazenamento do bucket de destino por padrão.
    
    Clique em Concluído.
3. Na seção Escolha como armazenar seus dados, faça o seguinte:
  1. Selecione uma classe de armazenamento padrão para o bucket ou Classe automática para gerenciamento automático da classe de armazenamento dos dados do bucket.
  2. Para ativar o namespace hierárquico, na seção Otimizar o armazenamento para cargas de trabalho com uso intensivo de dados, selecione Ativar namespace hierárquico neste bucket.
    Observação:não é possível ativar o namespace hierárquico em buckets existentes.
4. Na seção Escolha como controlar o acesso a objetos, selecione se o bucket aplica ou não a prevenção de acesso público e selecione um método de controle de acesso para os objetos do bucket.
  Observação:não é possível mudar a configuração Impedir acesso público se ela for aplicada em uma política da organização.
5. Na seção Escolha como proteger os dados do objeto, faça o seguinte:
  - Selecione qualquer uma das opções em Proteção de dados que você quer definir para o bucket.
    - Para ativar a exclusão reversível, clique na caixa de seleção Política de exclusão reversível (para recuperação de dados) e especifique o número de dias que você quer reter os objetos após a exclusão.
    - Para definir o controle de versões de objetos, clique na caixa de seleção Controle de versões de objetos (para controle de versões) e especifique o número máximo de versões por objeto e o número de dias após os quais as versões não atuais expiram.
    - Para ativar a política de retenção em objetos e buckets, clique na caixa de seleção Retenção (para compliance) e faça o seguinte:
      - Para ativar o bloqueio de retenção de objetos, clique na caixa de seleção Ativar retenção de objetos.
      - Para ativar o Bloqueio de buckets, clique na caixa de seleção Definir política de retenção de buckets e escolha uma unidade e um período de armazenamento para a retenção.
  - Para escolher como os dados do objeto serão criptografados, expanda a seção Criptografia de dados () e selecione um método de Criptografia de dados.
Clique em Criar.

Linha de comando

Substitua STORAGE_CLASS pela classe de armazenamento de sua preferência.
Substitua LOCATION pelo local de sua preferência (ASIA, EU ou US)
Substitua BUCKET_NAME por um nome de bucket que atenda aos requisitos.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Instalar e inicializar o SDK da Plataforma de Agentes para Python

Esta seção pressupõe que você configurou um ambiente de desenvolvimento Python ou está usando o Colab (ou qualquer outro tempo de execução adequado que tenha feito isso para você).

(Opcional) Configure um ambiente virtual

Também recomendamos configurar um ambiente virtual para isolar suas dependências.

Instalação

Para minimizar o conjunto de dependências que você precisa instalar, separamos as dependências em:

agent_engines: o conjunto de pacotes necessários para a implantação no ambiente de execução do agente.
adk: o conjunto de pacotes compatíveis do Kit de Desenvolvimento de Agente.
langchain: o conjunto de pacotes compatíveis do LangChain e do LangGraph.
ag2: o conjunto de pacotes AG2 compatíveis.
llama_index: o conjunto de pacotes compatíveis do LlamaIndex.

Ao instalar o SDK da plataforma de agentes para Python, é possível especificar as dependências necessárias (separadas por vírgulas). Para instalar todos:

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

Para usar o Agent2Agent (A2A) na Plataforma de Agentes , instale também o pacote a2a-sdk:

pip install google-adk[a2a]

Autenticação

Colab

Execute o seguinte código:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Nenhuma ação é necessária.

Shell local

Execute este comando:

gcloud auth application-default login

Importar e inicializar o SDK

Execute o código a seguir para importar e inicializar o SDK do Agent Runtime:

Projeto do Google Cloud

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

em que

PROJECT_ID é o ID do projeto do Google Cloud em que você desenvolve e implanta agentes.
LOCATION é uma das regiões com suporte.

(Opcional) Use seu próprio contêiner (BYOC)

O Agent Runtime cria um contêiner para você como parte do processo de implantação. Se você pretende criar seu próprio contêiner para implantação, siga as instruções nas subseções a seguir. Em geral, isso envolve as seguintes etapas:

Crie e envie uma imagem de contêiner para o Artifact Registry.
Configure as contas de serviço para o ambiente de execução do agente que correspondem ao projeto do usuário (em Configurar a identidade e as permissões do agente) e ao projeto de locatário (em que o ambiente de execução é executado).
Conceda o papel roles/artifactregistry.reader à conta de serviço do projeto do usuário e à conta de serviço do projeto de locatário.

Criar e enviar uma imagem do contêiner

Para criar e enviar uma imagem de contêiner, siga as instruções em Criar e enviar uma imagem Docker com o Cloud Build.

Configurar as contas de serviço para o ambiente de execução do agente

Para configurar as contas de serviço, implante um agente que imprima a conta de serviço do locatário.

Primeiro, configure o código-fonte do agente:

Abrir uma janela de terminal
Crie um novo diretório chamado byoc_setup.
```
mkdir byoc_setup
```

Crie um arquivo no diretório byoc_setup chamado metadata_agent.py com o seguinte conteúdo:

class MetadataAgent:

  def query(self):
    import requests
    url = "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id"
    try:
        response = requests.get(url, headers={"Metadata-Flavor": "Google"})
        response.raise_for_status()
        return f"service-{response.text}@serverless-robot-prod.iam.gserviceaccount.com"
    except Exception:
        return None

root_agent = MetadataAgent()

Crie outro arquivo no diretório byoc_setup chamado requirements.txt com o seguinte conteúdo:
```
google-cloud-aiplatform[agent_engines]
```

Se ainda não tiver feito isso, instale e inicialize o SDK da plataforma de agentes para Python. Na mesma sessão do Python em que você inicializa o SDK da plataforma de agentes para Python, execute o código a seguir para imprimir um TENANT_SERVICE_ACCOUNT:

remote_agent = client.agent_engines.create( # This deploys the agent
    config={
        "source_packages": ["byoc_setup"],
        "entrypoint_module": "byoc_setup.metadata_agent",
        "entrypoint_object": "root_agent",
        "requirements_file": "byoc_setup/requirements.txt",
        "class_methods": [{'api_mode': '', 'name': 'query'}],
    },
)
# This prints the tenant service account
# service-{tenant_project_number}@serverless-robot-prod.iam.gserviceaccount.com
print(remote_agent.query())
# This cleans up the resources
remote_agent.delete(force=True)

Procure o USER_SERVICE_ACCOUNT em Configurar a identidade e as permissões do seu agente. Se você estiver usando o agente de serviço padrão, isso vai corresponder a service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Conceder papéis de leitor do Artifact Registry

Você precisa conceder o papel Leitor do Artifact Registry aos seus USER_SERVICE_ACCOUNT e ao TENANT_SERVICE_ACCOUNT fornecido pelo Google.

Conta de serviço de usuário

Execute o seguinte comando para conceder os papéis necessários ao seu USER_SERVICE_ACCOUNT:

gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:USER_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"

Conta de serviço do locatário

Se a organização aplicar a restrição de política iam.allowedPolicyMemberDomains, permita o domínio do cliente do Google (C02h8e9nw) antes de conceder papéis ao TENANT_SERVICE_ACCOUNT.

Para mais informações sobre a restrição iam.allowedPolicyMemberDomains, consulte Compartilhamento restrito por domínio na documentação do IAM.

Peça a um administrador da organização, que tem permissões para modificar as restrições da sua organização, que permita seu projeto Google Cloud .

Quando você tiver permissões, execute o comando a seguir para conceder os papéis necessários ao TENANT_SERVICE_ACCOUNT:

gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:TENANT_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"

A seguir

Visão geral

Configurar o ambiente

Configurar com Google Cloud

Projeto do Google Cloud

Ter os papéis necessários

Configurar a identidade e as permissões do agente

Identidade do agente

Agente de serviço padrão

Gerar manualmente o agente de serviço padrão

Conta de serviço personalizada

Conta de serviço personalizada entre projetos

(Opcional) Criar um bucket do Cloud Storage

Implantar de arquivos de origem

Implantar do objeto

Console doGoogle Cloud

Configurar a replicação entre buckets

Linha de comando

Instalar e inicializar o SDK da Plataforma de Agentes para Python

(Opcional) Configure um ambiente virtual

Instalação

Autenticação

Colab

Cloud Shell

Shell local

Importar e inicializar o SDK

Projeto do Google Cloud

(Opcional) Use seu próprio contêiner (BYOC)

Criar e enviar uma imagem do contêiner

Configurar as contas de serviço para o ambiente de execução do agente

Conceder papéis de leitor do Artifact Registry

Conta de serviço de usuário

Conta de serviço do locatário

A seguir

Criar um agente

Resolver problemas na criação de agentes

Receber suporte

Configurar o ambiente Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Configurar com Google Cloud

Projeto do Google Cloud

Ter os papéis necessários

Configurar a identidade e as permissões do agente

Identidade do agente

Agente de serviço padrão

Gerar manualmente o agente de serviço padrão

Conta de serviço personalizada

Conta de serviço personalizada entre projetos

(Opcional) Criar um bucket do Cloud Storage

Implantar de arquivos de origem

Implantar do objeto

Console doGoogle Cloud

Configurar a replicação entre buckets

Linha de comando

Instalar e inicializar o SDK da Plataforma de Agentes para Python

(Opcional) Configure um ambiente virtual

Instalação

Autenticação

Colab

Cloud Shell

Shell local

Importar e inicializar o SDK

Projeto do Google Cloud

(Opcional) Use seu próprio contêiner (BYOC)

Criar e enviar uma imagem do contêiner

Configurar as contas de serviço para o ambiente de execução do agente

Conceder papéis de leitor do Artifact Registry

Conta de serviço de usuário

Conta de serviço do locatário

A seguir

Criar um agente

Resolver problemas na criação de agentes

Receber suporte

Configurar o ambiente