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 do 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 o seu 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 (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, 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 (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, 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).

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 que lhe conceda as seguintes funções de IAM no seu projeto:

• Utilizador do Vertex AI (roles/aiplatform.user)
• Administrador de armazenamento (roles/storage.admin)

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

Os agentes que implementa no Vertex AI Agent Engine são executados com contas de serviço como identidade.

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.

Usar o agente de serviços 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.

Usar uma 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 vai 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, conforme descrito no artigo Usar uma 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.

Crie um contentor do Cloud Storage

O Vertex AI Agent Engine organiza 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 do 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 da Vertex AI ([e-mail]) no seu contentor do Cloud Storage.
1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets

2. Click Create.
3. 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.
4. 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 para 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

Importe e inicialize o SDK

Execute o seguinte código para importar e inicializar o SDK para o Vertex AI Agent Engine:

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.

O que se segue?

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