Desenvolver e implantar agentes no Vertex AI Agent Engine com o Kit de Desenvolvimento de Agentes

Desenvolver e implantar agentes no Vertex AI Agent Engine com o Kit de Desenvolvimento de Agentes

Esta página demonstra como criar e implantar um agente no ambiente de execução do Vertex AI Agent Engine usando o Kit de Desenvolvimento de Agentes (ADK). Este guia de início rápido orienta você nas seguintes etapas:

• Crie o Google Cloud projeto.

• Instale o SDK da Vertex AI para Python e o ADK.

• Desenvolva um agente de câmbio.

• Implante o agente no ambiente de execução do Vertex AI Agent Engine.

• Teste o agente implantado.

Também é possível usar os seguintes guias de início rápido alternativos para o ADK:

• Guia de início rápido do ADK: o guia de início rápido do ADK é executado totalmente na sua máquina e pressupõe que você esteja usando um ambiente de desenvolvimento integrado (IDE) local e acesso ao terminal.

• Pacote inicial do agente: uma coleção de modelos de agentes de IA generativa prontos para produção criados para o Vertex AI Agent Engine.

Para o guia de início rápido usando frameworks compatíveis diferentes do Kit de Desenvolvimento de Agentes, consulte Desenvolver e implantar agentes no Vertex AI Agent Engine.

Antes de começar

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 o papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin).

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

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 and Cloud Storage 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 and Cloud Storage 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

Para receber as permissões necessárias a fim de usar o Vertex AI Agent 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 usando personalizados papéis ou outros predefinidos papéis.

Instalar e inicializar o SDK da Vertex AI para Python

1. Execute o comando a seguir para instalar o SDK da Vertex AI para Python e outros pacotes necessários:

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,adk]>=1.112

2. Autenticar como um usuário

   Shell local

   Execute este comando:

   gcloud auth application-default login

   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.

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

   Projeto do Google Cloud

   import vertexai
   
   client = vertexai.Client(
       project="PROJECT_ID",               # Your project ID.
       location="LOCATION",                # Your cloud region.
   )
   

   Em que:

   • PROJECT_ID é o Google Cloud ID do projeto em que você desenvolve e implanta agentes

   • LOCATION é uma das regiões compatíveis.

Desenvolver um agente

1. Desenvolva uma ferramenta de câmbio para seu agente:

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. Instancie um agente:

   from google.adk.agents import Agent
   from vertexai import agent_engines
   
   agent = Agent(
       model="gemini-2.0-flash",
       name='currency_exchange_agent',
       tools=[get_exchange_rate],
   )
   
   app = agent_engines.AdkApp(agent=agent)
   

3. Teste o agente localmente:

   **Observação**: o teste de um agente do ADK localmente usa sessões na memória.

   async for event in app.async_stream_query(
       user_id="USER_ID",
       message="What is the exchange rate from US dollars to SEK today?",
   ):
       print(event)
   

   em que USER_ID é um ID definido pelo usuário com um limite de 128 caracteres.

Implantar um agente

Implante o agente criando um reasoningEngine recurso na Vertex AI:

Observação: a implantação de um agente do ADK no Vertex AI Agent Engine gera automaticamente um recurso de sessão gerenciada. É possível excluir o recurso de sessão gerenciada junto com o agente na seção Limpeza.

remote_agent = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "STAGING_BUCKET",
    }
)

em que STAGING_BUCKET é um bucket do Cloud Storage com o prefixo gs://.

Usar um agente

Teste o agente implantado enviando uma consulta:

async for event in remote_agent.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

Liberar espaço

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga as etapas abaixo.

remote_agent.delete(force=True)

A seguir

• Explorar os notebooks.
• Configure o ambiente.
• Desenvolver um agente.
• Implantar um agente.
• Usar um agente.
• Gerenciar um agente.
• Receba suporte.