Desenvolva e implante agentes no Agent Runtime com o Kit de Desenvolvimento de Agente (ADK)

Desenvolva e implante agentes no Agent Runtime com o Kit de Desenvolvimento de Agente (ADK)

O Agent Runtime permite hospedar agentes desenvolvidos com o Kit de Desenvolvimento de Agente (ADK). Neste documento, explicamos como criar, implantar e testar um agente usando o ADK.

Este guia de início rápido orienta você nas seguintes etapas:

• Crie o projeto Google Cloud .
• Instale o SDK da Plataforma de Agentes para Python e o ADK.
• Desenvolver um agente de câmbio.
• Implantar o agente no Agent Runtime.
• 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 inteiramente na sua máquina e pressupõe que você esteja usando um ambiente de desenvolvimento integrado 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 a Agent Platform.

Para o guia de início rápido que usa outros frameworks compatíveis, consulte Desenvolver e implantar agentes no Agent Runtime.

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

Faça login na sua conta do Google Cloud . 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 sem custos financeiros.

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 Agent Platform and Cloud Storage APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 Agent Platform and Cloud Storage APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Para receber as permissões necessárias para usar o Agent Runtime, peça ao administrador que conceda a você os seguintes papéis do IAM no projeto:

• Usuário da Agent Platform (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 da Agent Platform para Python

1. Execute o seguinte comando para instalar o SDK da plataforma de agentes 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.

3. Execute o código a seguir para importar a Agent Platform 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 do Google Cloud em que você desenvolve e implanta agentes.

   • LOCATION é uma das regiões com disponibilidade.

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-3.5-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 caracteres de 128.

Implantar um agente

Implante o agente criando um recurso reasoningEngine na Agent Platform:

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

from vertexai import types

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

em que STAGING_BUCKET é um bucket do Cloud Storage prefixado por 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

Guia

Configuração do ambiente de execução da plataforma de agentes

Configure o ambiente para usar o ambiente de execução da Agent Platform.

Guia

Implantar agentes

Conheça as cinco maneiras de implantar um agente no Agent Platform Runtime com base nas suas necessidades de desenvolvimento.

Guia

Gerenciar agentes implantados

Saiba como gerenciar agentes que foram implantados no ambiente de execução gerenciado da Agent Platform.

Guia

Usar um agente

Usar um agente com o ambiente de execução da plataforma de agentes.

Recurso

Receber suporte

Encontre recursos e suporte para a Plataforma de Agentes do Google.