Configurar o ambiente

Antes de trabalhar com o Agent Engine, 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 Vertex AI para Python. Confira os tópicos a seguir para começar a trabalhar com o Agente Engine.

Para conferir um exemplo de referência do Terraform para simplificar a configuração e a implantação do ambiente do Agente Engine, consulte o agent-starter-pack.

Configurar seu projeto do Google Cloud

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

Ter os papéis necessários

Para receber as permissões necessárias a fim de usar o Agente Engine, peça que o administrador conceda a você os seguintes papéis do IAM no projeto:

• Usuário da Vertex AI (roles/aiplatform.user)
• Administrador de armazenamento (roles/storage.admin)

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 por meio de papéis personalizados ou de outros papéis predefinidos.

Configurar as permissões do agente de serviço

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. Esta conta tem o papel 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.

Se você precisar de outras permissões, conceda outros papéis ao agente de serviço. Para isso, siga estas etapas:

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 um agente de serviço manualmente

Embora o agente de serviço do Reasoning Engine seja provisionado automaticamente durante a implantação do agente do mecanismo, pode haver cenários em que você precisa gerar manualmente. 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:

1. Gere o agente de serviço do Reasoning Engine usando a CLI do Google Cloud.

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

   Observação: a resposta ao comando da CLI do Google Cloud pode mostrar apenas o agente de serviço da Vertex AI. No entanto, o agente de serviço do mecanismo de raciocínio 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 participantes, insira [e-mail].

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

5. Clique no botão Save.

Criar um bucket do Cloud Storage

O mecanismo de agentes 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 o 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.

Console do Google Cloud

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

   Go to Buckets page

2. Click Create bucket.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   • For Name your bucket, enter a name that meets the bucket naming requirements.
   • For Choose where to store your data, do the following:
     • Select a Location type option.
     • Select a Location option.
   • For Choose a default storage class for your data, select a storage class.
   • For Choose how to control access to objects, select an Access control option.
   • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
4. Click Create.

Linha de comando

Create a Cloud Storage bucket and configure it as follows:
• 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 exclusivo um nome de bucket que atenda aos requisitos de nome de bucket.

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

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 ambiente de execução adequado que tenha sido configurado para você).

(Opcional) Configurar um ambiente virtual

Também recomendamos configurar um ambiente virtual para isolar as 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 agente.
• langchain: o conjunto de pacotes compatíveis do LangChain.
• langgraph: o conjunto de pacotes compatíveis do LangGraph.

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

pip install google-cloud-aiplatform[agent_engines,langchain,langgraph]

Autenticação

Colab

Execute o seguinte código:

from google.colab import auth

auth.authenticate_user()

Cloud Shell

Nenhuma ação é necessária.

Shell local

Execute este comando:

gcloud auth application-default login

Importar e inicializar o SDK

Execute o seguinte código para importar e inicializar o SDK do mecanismo de agente:

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

• PROJECT_ID: o ID do projeto.
• LOCATION: sua região da nuvem.
• BUCKET_NAME: seu bucket Google Cloud .

A seguir

• Desenvolver um aplicativo.