Criar e implantar um agente de IA no Cloud Run usando o Kit de Desenvolvimento de Agente (ADK)

O framework do Kit de Desenvolvimento de Agente (ADK) simplifica a criação, a avaliação e a implantação de agentes de IA. O ADK oferece uma abordagem modular e focada em código para criar agentes que podem raciocinar, planejar e usar ferramentas.

Neste tutorial, mostramos como criar e implantar um agente de IA no Cloud Run usando o ADK para Python. Este agente recupera a previsão do tempo para uma cidade que você especificar.

Para mais informações sobre como hospedar seu agente do ADK usando a Google Cloud CLI, consulte Implantar no Cloud Run na documentação do ADK.

Objetivos

• Escrever o aplicativo de exemplo para definir o weather-agent.
• Implante o agente no Cloud Run usando o código-fonte.
• Execute o agente para consultar informações sobre o clima.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Agent Platform

Para gerar uma estimativa de custo baseada na sua projeção de uso, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Antes de começar

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.

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.

1. Ative a API Cloud Run Admin, Vertex AI e Cloud Build, se ainda não estiverem ativadas.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

2. Configure o ambiente de desenvolvimento do Cloud Run no projeto do Google Cloud .
3. Instale o ADK seguindo as instruções na documentação do Kit de Desenvolvimento de Agentes.

4. Se você precisa seguir uma política da organização de restrição de domínio que restringe invocações não autenticadas para seu projeto, será necessário acessar o serviço implantado, conforme descrito em Como testar serviços particulares.

Funções exigidas

Para receber as permissões necessárias para implantar um agente de IA no Cloud Run, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper) no projeto
• Usuário da Agent Platform (roles/aiplatform.user) no projeto
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço
• Visualizador de registros (roles/logging.viewer) 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 usando papéis personalizados ou outros papéis predefinidos.

Crie o aplicativo de exemplo

Para escrever um aplicativo em Python:

1. Crie um novo diretório pai com o nome parent_folder e mude para ele:

   mkdir parent_folder
   cd parent_folder
   

2. No diretório parent_folder, crie um novo subdiretório chamado multi_tool_agent e mude para ele:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. Crie um arquivo __init__.py para importar o agente:

   from . import agent
   

4. Crie um arquivo agent.py para definir o agente que vai responder a perguntas sobre o horário e o clima em uma cidade específica:

   import datetime
   from zoneinfo import ZoneInfo
   from google.adk.agents import Agent
   
   def get_weather(city: str) -> dict:
       """Retrieves the current weather report for a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the weather report.
   
       Returns:
           dict: status and result or error msg.
       """
       if city.lower() == "new york":
           return {
               "status": "success",
               "report": (
                   "The weather in New York is sunny with a temperature of 25 degrees"
                   " Celsius (77 degrees Fahrenheit)."
               ),
           }
       else:
           return {
               "status": "error",
               "error_message": f"Weather information for '{city}' is not available.",
           }
   
   def get_current_time(city: str) -> dict:
       """Returns the current time in a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the current time.
   
       Returns:
           dict: status and result or error msg.
       """
   
       if city.lower() == "new york":
           tz_identifier = "America/New_York"
       else:
           return {
               "status": "error",
               "error_message": (
                   f"Sorry, I don't have timezone information for {city}."
               ),
           }
   
       tz = ZoneInfo(tz_identifier)
       now = datetime.datetime.now(tz)
       report = (
           f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
       )
       return {"status": "success", "report": report}
   
   root_agent = Agent(
       name="weather_time_agent",
       model="gemini-2.5-flash",
       description=(
           "Agent to answer questions about the time and weather in a city."
       ),
       instruction=(
           "You are a helpful agent who can answer user questions about the time and weather in a city."
       ),
       tools=[get_weather, get_current_time],
   )
   

5. Crie um arquivo .env e adicione as seguintes variáveis:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Substitua:

   • PROJECT_ID: o ID do projeto do Google Cloud .
   • REGION: a região em que você planeja implantar o serviço.

6. Navegue até o diretório da pasta mãe parent_folder e crie um arquivo requirements.txt para adicionar a dependência google-adk:

   google-adk
   

   O projeto de origem inclui a seguinte estrutura:

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

O app está concluído e pronto para ser implantado.

Implantar no Cloud Run da origem

A implantação da origem cria automaticamente uma imagem de contêiner com base no código-fonte e a implanta.

1. No diretório do código-fonte (parent_folder), implante no Cloud Run usando o seguinte comando:

   gcloud run deploy --source .

   1. Quando o nome do serviço for solicitado, pressione "Enter" para aceitar o nome padrão, por exemplo, weather-agent.

   2. Se for solicitado que você ative APIs adicionais no projeto, por exemplo, a API Artifact Registry, responda pressionando y:

   3. Quando a região for solicitada, selecione a região que preferir, por exemplo, europe-west1.

   4. Se você for solicitado a criar um repositório na região especificada, responda pressionando y.

   5. Se for solicitado que você permita o acesso público, responda y. Você pode não ver essa solicitação se houver uma política da organização de restrição de domínio que a impeça; para mais detalhes, consulte a seção Antes de começar.

   Aguarde alguns instantes até a conclusão da implantação. Em caso de sucesso, a linha de comando vai exibir o URL de serviço do agente implantado, que estará no seguinte formato: https://weather-agent-123456789101.us-central1.run.app/list-apps.

Executar o agente

Para usar o agente do ADK, execute os seguintes comandos curl:

1. Para ver a lista de apps, execute o seguinte comando:

   curl -X GET SERVICE_URL/list-apps
   

   Substitua SERVICE_URL pelo URL do serviço implantado.

2. Para iniciar uma sessão, execute o seguinte comando:

   curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": "value2"}'
   

3. Para consultar o agente, execute o seguinte comando:

   curl -X POST SERVICE_URL/run \
   -H "Content-Type: application/json" \
   -d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"
   

O agente retorna as informações meteorológicas nos resultados da consulta.

Para mais informações e exemplos sobre os comandos curl compatíveis, consulte Usar o servidor de API na documentação do ADK.

Sucesso:você implantou um agente de IA usando o Kit de Desenvolvimento de Agente no Cloud Run.

Limpar

Para evitar cobranças extras na sua conta do Google Cloud , exclua todos os recursos implantados com este tutorial.

Excluir o projeto

Se você criou um novo projeto para este tutorial, exclua-o. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Atenção: excluir um projeto tem os efeitos a seguir.

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No console Google Cloud , acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir recursos do tutorial

1. Exclua o serviço do Cloud Run que você implantou neste tutorial. Os serviços do Cloud Run não geram custos até receberem solicitações.

   Para excluir o serviço do Cloud Run, execute o seguinte comando:

   gcloud run services delete SERVICE-NAME

   SERVICE-NAME pelo nome do serviço;

   Também é possível excluir os serviços do Cloud Run no console doGoogle Cloud .

2. Remova a configuração de região padrão gcloud que você adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project