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.

Crie o projeto 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:

  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.

    Go to project selector

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

  4. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

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

    Go to project selector

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

  7. Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Enable the APIs

    8.

    Ter os papéis necessários

    Para receber as permissões necessárias para usar o mecanismo de agente da Vertex AI, peça ao administrador para conceder a você os seguintes papéis do IAM 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 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 Vertex AI Agent Engine são executados usando a conta de serviço do Agente de serviço do mecanismo de raciocínio do AI Platform. Essa 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 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

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

      Acessar IAM

    3. Na seção Adicionar principais, no campo Novos principais, insira service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

    5. Clique no botão Salvar.

    Criar um bucket do Cloud Storage

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

    Google Cloud console

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

    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 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 agentes.
    • 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:

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

    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 Vertex AI Agent Engine:

    import vertexai
from vertexai import agent_engines

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

    em que

    A seguir