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

Pré-lançamento — The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

O framework Agent Development Kit (ADK) simplifica a criação, a avaliação e a implantação de agentes de IA. O ADK oferece uma abordagem modular e com prioridade ao código para criar agentes que podem pensar, planejar e usar ferramentas.

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

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

• Escreva o aplicativo de exemplo para definir o agente de clima.
• Implante o agente no Cloud Run da origem.
• Execute o agente para consultar informações sobre o clima.

Custos

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

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

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

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

Antes de começar

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.

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. Enable the Cloud Run Admin API, Vertex AI API, and Cloud Build 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

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

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 Vertex AI (roles/aiplatform.user) no projeto
• Usuário da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
• Leitor 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 principal chamado 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 clima e a hora 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.0-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 beta 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 acesso público, siga estas etapas: responda y. Se houver um domínio, você não vai receber essa solicitação e a política de restrição da organização que impede isso. 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 exibe o URL de serviço. Acesse /list-apps no URL do serviço. Por exemplo, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Executar o agente

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

1. Para receber 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": 42}'
   

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 do clima nos resultados da consulta.

Para mais informações e exemplos sobre os comandos curl compatíveis, consulte Usar o servidor da 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 precisa mantê-lo sem as mudanças adicionadas 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:

Cuidado: a exclusão de um projeto tem os seguintes efeitos:

• 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

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 da região padrão do 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