Configurar o ambiente

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

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

Configurar com Google Cloud

É possível configurar o Google Cloud para o Vertex AI Agent Engine criando um projeto Google Cloud ou se inscrevendo na Vertex AI no modo expresso:

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:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, and Cloud Trace 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, and Cloud Trace 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

Observação: para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você não tiver essa permissão, peça ao administrador para conceder a função de administrador do uso de serviço (roles/serviceusage.serviceUsageAdmin).

Modo expresso

Siga as instruções em Vertex AI no modo expresso para configurar o Vertex AI Agent Engine no modo expresso.

Depois de configurar o Vertex AI Agent Engine no modo rápido, pule para a etapa Instalar e inicializar o SDK da Vertex AI para Python.

Ter os papéis necessários

Para receber as permissões necessárias para usar o Vertex AI Agent Engine, peça ao administrador para conceder a você o papel do IAM de Usuário da Vertex AI (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 identidade e permissões:

• Identidade do agente (recomendado) (prévia): use a identidade do agente do Identity Access Management (IAM) para fornecer recursos de segurança e gerenciamento de acesso ao usar agentes no Vertex AI Agent Engine Runtime. A identidade do agente está vinculada a cada agente individual.

• Contas de serviço: são compartilhadas entre os agentes implantados no Vertex AI Agent Engine. 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 Reasoning Engine da Vertex AI (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

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

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 do Agent Engine com apenas o campo identity_type:

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

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

1. Provisione a identidade do agente com os seguintes papéis recomendados:

   • roles/aiplatform.expressUser: concede acesso à inferência, sessões e memória em execução.

   • roles/serviceusage.serviceUsageConsumer: conceda ao agente permissão para usar a cota do projeto e o SDK da Vertex AI.

2. Conceda à identidade do agente papéis adicionais conforme necessário para seu caso de uso.

3. 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 precisar de permissões além do conjunto padrão, conceda outros papéis a ele:

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. Encontre o principal que corresponde a [e-mail].

3. 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 Reasoning Engine seja provisionado automaticamente durante a implantação do Vertex AI Agent Engine, pode haver cenários em que é necessário gerá-lo manualmente antes. Isso é 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.

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

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

2. Acesse a página do IAM e clique em Conceder acesso.

   Acessar IAM

3. Na seção Adicionar principais, no campo Novos principais, digite [e-mail].

4. Na seção Atribuir papéis, encontre e selecione os papéis necessários.

5. 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 de Usuário da Vertex AI (roles/aiplatform.user).

1. Se você não tiver uma conta de serviço, crie uma. Consulte Criar contas de serviço.

2. Conceda à conta de serviço o papel de Usuário da Vertex AI (roles/aiplatform.user).

3. Conceda à conta de serviço todos os outros papéis exigidos pelo código do agente.

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

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

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

2. Conceda permissões ao agente de serviço da Vertex AI:no projeto em que a conta de serviço está localizada, conceda o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço da Vertex AI ([e-mail]) do projeto em que você planeja implantar o agente.

3. 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 Vertex AI (roles/aiplatform.user) e qualquer outra função exigida pelo código do seu agente.

(Opcional) Criar um bucket do Cloud Storage

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

• Fazer implantação de arquivos de origem: o agente existe como arquivos. O SDK Vertex AI 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 Vertex AI para Python empacota esse objeto e o envia para um bucket do Cloud Storage, que funciona 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 será necessário um bucket do Cloud Storage.

Implantar do objeto

Ao implantar de um objeto de agente, o Vertex AI Agent Engine 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 Vertex AI (você ou uma conta de serviço) tem acesso Storage Admin a esse bucket. Isso é necessário porque o SDK da Vertex AI 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.

Observação: recomendamos que você crie um bucket do Cloud Storage no mesmo projeto em que implanta seus agentes no Vertex AI Agent Engine. Se você usar um bucket em um projeto diferente, conceda manualmente as permissões de leitura do Agente de serviços da Vertex AI ([e-mail]) ao bucket do Cloud Storage.

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

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets

Click Create.

On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.

1. In the Get started section, do the following:
   • Enter a globally unique name that meets the bucket naming requirements.
   • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
2. In the Choose where to store your data section, do the following:
   1. Select a Location type.
   2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
      • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
   3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

      Set up cross-bucket replication

      1. In the Bucket menu, select a bucket.

      2. In the Replication settings section, click Configure to configure settings for the replication job.

         The Configure cross-bucket replication pane appears.

         • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
         • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
         • Click Done.
3. In the Choose how to store your data section, do the following:
   1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
   2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
      Note: You cannot enable hierarchical namespace in existing buckets.
4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
   Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
5. In the Choose how to protect object data section, do the following:
   • Select any of the options under Data protection that you want to set for your bucket.
     • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
     • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
     • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
       • To enable Object Retention Lock, click the Enable object retention checkbox.
       • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
   • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.

Click Create.

Instalar e inicializar o SDK do Vertex AI para Python

Esta seção pressupõe que você configurou um ambiente de desenvolvimento do 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 Vertex AI Agent Engine.
• 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 Vertex AI para Python, é possível especificar as dependências necessárias (separadas por vírgulas). Para instalar todos eles:

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

Para usar o Agent2Agent (A2A) no Agent Engine, instale também o pacote a2a-sdk:

pip install a2a-sdk>=0.3.4

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

Modo expresso

Se você estiver usando a Vertex AI no modo expresso, nenhuma ação será necessária.

Importar e inicializar o SDK

Execute o código a seguir para importar e inicializar o SDK do Vertex AI Agent Engine:

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.

Modo expresso

Se você estiver usando a Vertex AI no modo rápido, execute o seguinte código:

import vertexai
from vertexai import agent_engines # For the prebuilt ADK template

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY"
)

em que API_KEY é a chave de API usada para autenticar o agente.

A seguir

• Desenvolver um agente.
• Resolver problemas ao configurar um ambiente.
• Receba suporte.