Configure o ambiente

Antes de trabalhar com o Vertex AI Agent Engine, tem de se certificar de que o seu ambiente está configurado. Tem de ter um Google Cloud projeto com a faturação ativada, ter as autorizações necessárias, configurar um contentor do Cloud Storage e instalar o SDK Vertex AI para Python. Use os seguintes tópicos para garantir que está tudo pronto para começar a trabalhar com o Vertex AI Agent Engine.

Para um exemplo de referência do Terraform que simplifique a configuração e a implementação do ambiente do Vertex AI Agent Engine, considere explorar o agent-starter-pack.

Configure com o Google Cloud

Pode configurar o Google Cloud Vertex AI Agent Engine criando um Google Cloud projeto ou inscrevendo-se no Vertex AI no modo expresso:

Google Cloud projeto

Cada projeto pode ser identificado de duas formas: o número do projeto ou o ID do projeto. O PROJECT_NUMBER é criado automaticamente quando cria o projeto, enquanto o PROJECT_ID é criado por si 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

Nota: para ativar APIs, precisa da autorização serviceusage.services.enable. Se não tiver esta autorização, peça ao seu administrador para lhe conceder a função de administrador de utilização de serviços (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 expresso, pode avançar para o passo Instale e inicialize o SDK Vertex AI para Python.

Obtenha as funções necessárias

Para receber as autorizações de que precisa para usar o Vertex AI Agent Engine, peça ao seu administrador para lhe conceder a função IAM de utilizador do Vertex AI (roles/aiplatform.user) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Configure a identidade e as autorizações do seu agente

Tem as seguintes opções quando configura a identidade e as autorizações:

• Identidade do agente (recomendado) (Pré-visualização): use a identidade do agente do Identity Access Management (IAM) para fornecer funcionalidades de segurança e gestão de acesso quando usar agentes no tempo de execução do Vertex AI Agent Engine. A identidade do agente está associada a cada agente individual.

• Contas de serviço: as contas de serviço são partilhadas entre os agentes que implementa no Vertex AI Agent Engine. Tem duas opções para a conta de serviço:

  • Agente de serviço predefinido: por predefinição, os agentes usam o agente de serviço do motor de raciocínio da plataforma de IA. Esta conta de serviço gerida pela Google tem a função Agente do serviço do motor de raciocínio da Vertex AI (roles/aiplatform.reasoningEngineServiceAgent), que inclui as autorizações predefinidas necessárias para os agentes implementados.
  • Conta de serviço personalizada: pode especificar a sua própria conta de serviço para os agentes usarem. Isto dá-lhe um controlo mais detalhado sobre as autorizações concedidas aos agentes.

Identidade do agente

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Para configurar políticas de IAM antes de implementar o agente, pode criar uma identidade do agente sem implementar o código do agente. Para tal, crie uma instância do Agent Engine apenas com 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, pode fazer o seguinte:

1. Aprovisione a identidade do agente com as seguintes funções recomendadas:

   • roles/aiplatform.expressUser: conceder acesso à execução de inferências, sessões e memória.

   • roles/serviceusage.serviceUsageConsumer: conceda ao agente autorização para usar a quota do projeto e o SDK Vertex AI.

2. Conceda à identidade do agente funções adicionais, conforme necessário, para o seu exemplo de utilização.

3. Adicione o código do agente através de agent_engine.update(...).

Agente do serviço predefinido

O agente de serviço do motor de raciocínio da plataforma de IA é usado por predefinição. Pode ver a lista completa de autorizações predefinidas na documentação do IAM.

Se o seu agente precisar de autorizações além do conjunto predefinido, pode conceder funções adicionais ao agente de serviço:

1. Aceda à página IAM e selecione a caixa de verificação "Incluir concessões de funções fornecidas pela Google".

   Aceda ao IAM

2. Encontre o principal que corresponde a [e-mail].

3. Adicione as funções necessárias ao principal clicando no botão de edição e, de seguida, no botão de guardar.

Gere manualmente o agente do serviço predefinido

Embora o agente de serviço do motor de raciocínio seja aprovisionado automaticamente durante a implementação do Vertex AI Agent Engine, podem existir cenários em que tem de o gerar manualmente com antecedência. Isto é particularmente importante quando precisa de conceder funções específicas ao agente de serviço para garantir que o processo de implementação tem as autorizações necessárias e evitar potenciais falhas de implementação.

Seguem-se os passos para gerar manualmente um agente do serviço do motor de raciocínio:

1. Gere o agente de serviço do motor de raciocínio através da CLI do Google Cloud.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   Nota: a resposta ao comando da CLI do Google Cloud pode apresentar apenas o agente do serviço Vertex AI. No entanto, o agente do serviço do motor de raciocínio também é criado.

2. Aceda à página IAM e clique em Conceder acesso.

   Aceda ao IAM

3. Na secção Adicionar responsáveis, no campo Novos responsáveis, introduza [e-mail].

4. Na secção Atribuir funções, encontre e selecione as funções de que precisa.

5. Clique no botão Guardar.

Conta de serviço personalizada

Para usar a sua própria conta de serviço, tem de lhe conceder as autorizações necessárias para executar o agente. A sua conta de serviço personalizada precisa provavelmente da função Utilizador do Vertex AI (roles/aiplatform.user).

1. Se não tiver uma conta de serviço, crie uma. Consulte o artigo Crie contas de serviço.

2. Conceda à conta de serviço a função Utilizador da Vertex AI (roles/aiplatform.user).

3. Conceda quaisquer outras funções exigidas pelo seu código de agente à conta de serviço.

4. Para implementar o seu agente com esta conta de serviço, conceda a si próprio a função Utilizador da conta de serviço (roles/iam.serviceAccountUser) nesta conta de serviço personalizada.

5. Quando implementar o seu agente, especifique o endereço de email da sua conta de serviço personalizada. Consulte o artigo Configure uma conta de serviço personalizada para ver detalhes.

Conta de serviço personalizada entre projetos

Se a sua conta de serviço personalizada for de um projeto diferente, precisa de configurações adicionais no projeto onde a conta de serviço reside e no projeto onde implementa o agente.

1. Desative a política organizacional de utilização da conta de serviço entre projetos: no projeto onde a conta de serviço está localizada, certifique-se de que a política organizacional iam.disableCrossProjectServiceAccountUsage NÃO é aplicada. Consulte o artigo Desative a aplicação da utilização de contas de serviço entre projetos para ver mais detalhes.

2. Conceda autorizações ao agente do serviço Vertex AI: no projeto onde se encontra a conta de serviço, conceda a função de criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator) ao agente do serviço Vertex AI ([e-mail]) do projeto onde planeia implementar o agente.

3. Conceda autorizações à conta de serviço personalizada: no projeto onde planeia implementar o agente, conceda as funções necessárias à conta de serviço personalizada. Normalmente, isto inclui a função Utilizador da Vertex AI (roles/aiplatform.user) e quaisquer outras funções exigidas pelo código do seu agente.

(Opcional) Crie um contentor do Cloud Storage

A necessidade de um contentor do Cloud Storage depende de se o SDK Vertex AI para Python precisar de um local para preparar o código do seu agente antes da implementação:

• Implementar a partir de ficheiros de origem: o agente existe como ficheiros. O SDK Vertex AI para Python pode agrupar e carregar estes ficheiros diretamente para o serviço de implementação, pelo que não é necessário um contentor de preparação do Cloud Storage.

• Implementação a partir do objeto do agente: o agente existe na memória. O SDK do Vertex AI para Python inclui este objeto e carrega-o para um contentor do Cloud Storage, que funciona como uma área de preparação para o serviço de implementação.

Implemente a partir de ficheiros de origem

Se implementar um agente a partir de ficheiros de origem, não é necessário um contentor do Cloud Storage.

Implemente a partir do objeto

Quando implementa a partir de um objeto de agente, o Vertex AI Agent Engine prepara os artefactos dos seus agentes implementados num contentor do Cloud Storage como parte do processo de implementação. Certifique-se de que o principal autenticado para usar a Vertex AI (você ou uma conta de serviço) tem Storage Admin acesso a este contentor. Isto é necessário porque o SDK Vertex AI para Python escreve o seu código neste contentor.

Se já tiver um conjunto configurado, pode ignorar este passo. Caso contrário, pode seguir as instruções padrão para criar um contentor.

Nota: recomendamos vivamente que crie um contentor do Cloud Storage no mesmo projeto onde implementa os seus agentes no Vertex AI Agent Engine. Se usar um contentor num projeto diferente, tem de conceder manualmente autorizações de leitura ao agente de serviço do Vertex AI ([e-mail]) no seu contentor do Cloud Storage.

Peça ao administrador para lhe conceder a função de IAM Administrador de armazenamento (roles/storage.admin) no seu 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.

Instale e inicialize o SDK Vertex AI para Python

Esta secção pressupõe que configurou um ambiente de desenvolvimento Python ou que está a usar o Colab (ou qualquer outro ambiente de execução adequado que o tenha configurado por si).

(Opcional) Configure um ambiente virtual

Também recomendamos que configure um ambiente virtual para isolar as suas dependências.

Instalação

Para minimizar o conjunto de dependências que tem de instalar, separámos as dependências em:

• agent_engines: o conjunto de pacotes necessários para a implementação no Vertex AI Agent Engine.
• adk: o conjunto de pacotes do Agent Development Kit compatíveis.
• langchain: o conjunto de pacotes LangChain e LangGraph compatíveis.
• ag2: o conjunto de pacotes AG2 compatíveis.
• llama_index: o conjunto de pacotes LlamaIndex compatíveis.

Quando instala o SDK da Vertex AI para Python, pode especificar as dependências necessárias (separadas por vírgulas). Para instalar todas:

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

Para usar o Agent2Agent (A2A) no Agent Engine, também tem de instalar 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

Não é necessária nenhuma ação.

Shell local

Execute o seguinte comando:

gcloud auth application-default login

Modo expresso

Se estiver a usar o Vertex AI no modo expresso, não é necessária nenhuma ação.

Importe e inicialize o SDK

Execute o seguinte código para importar e inicializar o SDK para o 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",
)

onde

• PROJECT_ID é o Google Cloud ID do projeto no qual desenvolve e implementa agentes, e
• LOCATION é uma das regiões suportadas.

Modo expresso

Se estiver a usar o Vertex AI no modo expresso, 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"
)

onde API_KEY é a chave da API que usa para autenticar o agente.

O que se segue?

• Desenvolva um agente.
• Resolva problemas de configuração de um ambiente.
• Receba apoio técnico.