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

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

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 Agente (ADK). Este início rápido orienta você nas seguintes etapas:

• Crie o projeto Google Cloud .

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

Você também pode 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 local e acesso ao terminal.

• Pacote inicial de agentes: 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 que não sejam o Agent Development Kit, consulte Desenvolver e implantar agentes no Vertex AI Agent Engine.

Antes de começar

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

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

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

Instalar e inicializar o SDK do Vertex AI para Python

1. Execute o seguinte comando 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 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.

   Modo expresso

   Se você estiver usando a Vertex AI no modo expresso, nenhuma ação será necessária.

3. Execute o código a seguir para importar o mecanismo de agente da Vertex AI 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 ID do projeto Google Cloud em que você desenvolve e implanta agentes.

   • LOCATION é uma das regiões com suporte.

   Modo expresso

   Se você estiver usando a Vertex AI no modo expresso, execute o seguinte código:

   import vertexai
   from vertexai import agent_engines
   
   vertexai.init(
       key="API_KEY"
   )
   

   em que API_KEY é a chave de API usada para autenticar o agente.

   Observação: para implantar o agente usando o objeto do agente, use o modo expresso com faturamento.

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 local de um agente do ADK 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 recurso reasoningEngine 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 e o agente na seção de 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)

Limpar

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

• Conheça os notebooks.
• Configure o ambiente
• Desenvolver um agente.
• Implante um agente.
• Use um agente.
• Gerenciar um agente.
• Receba suporte.