Crie e implemente um agente de IA no Cloud Run através do Agent Development Kit (ADK)

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

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

A framework do Agent Development Kit (ADK) simplifica a criação, a avaliação e a implementação de agentes de IA. O ADK oferece uma abordagem modular e baseada em código para criar agentes que podem raciocinar, planear e usar ferramentas.

Este tutorial mostra como criar e implementar um agente de IA no Cloud Run com o ADK para Python. Este agente obtém o relatório meteorológico de uma cidade que especificar.

Para mais informações sobre como alojar o agente do ADK através da CLI do Google Cloud, consulte o artigo Implemente no Cloud Run na documentação do ADK.

Objetivos

• Escreva a aplicação de exemplo para definir o agente meteorológico.
• Implemente o agente no Cloud Run a partir da origem.
• Execute o seu agente para consultar informações meteorológicas.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

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

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação 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 programação do Cloud Run no seu Google Cloud projeto.
3. Instale o ADK seguindo as instruções na documentação do Agent Development Kit.

4. Se estiver ao abrigo de uma política da organização de restrição de domínio que restringe as invocações não autenticadas para o seu projeto, tem de aceder ao serviço implementado conforme descrito em Testar serviços privados.

Funções necessárias

Para receber as autorizações de que precisa para implementar um agente de IA no Cloud Run, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

• Programador de origem do Cloud Run (roles/run.sourceDeveloper) no projeto
• Utilizador do Vertex AI (roles/aiplatform.user) no projeto
• Utilizador da conta de serviço (roles/iam.serviceAccountUser) na identidade do serviço
• Visualizador de registos (roles/logging.viewer) no projeto

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Escreva a aplicação de amostra

Para escrever uma aplicação em Python:

1. Crie um novo diretório principal denominado parent_folder e altere o diretório para o mesmo:

   mkdir parent_folder
   cd parent_folder
   

2. No diretório parent_folder, crie um novo subdiretório denominado multi_tool_agent e mude o diretório para o mesmo:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

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

   from . import agent
   

4. Crie um ficheiro agent.py para definir o agente para responder a perguntas sobre a hora e o tempo numa cidade especificada:

   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 ficheiro .env e adicione as seguintes variáveis:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Substitua o seguinte:

   • PROJECT_ID: o Google Cloud ID do projeto.
   • REGION: a região na qual planeia implementar o seu serviço.

6. Navegue para o diretório da pasta principal parent_folder e crie um ficheiro 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
   

A sua app está concluída e pronta para ser implementada.

Implemente no Cloud Run a partir da origem

A implementação a partir da origem cria automaticamente uma imagem de contentor a partir do código-fonte e implementa-a.

1. No diretório do código fonte (parent_folder), implemente no Cloud Run através do seguinte comando:

   gcloud beta run deploy --source .

   1. Quando lhe for pedido o nome do serviço, prima Enter para aceitar o nome predefinido, por exemplo, weather-agent.

   2. Se lhe for pedido que ative APIs adicionais no projeto, por exemplo, a API Artifact Registry, responda premindo y.

   3. Quando lhe for pedido para indicar a região: selecione a região da sua escolha, por exemplo, europe-west1.

   4. Se lhe for pedido que crie um repositório na região especificada, responda premindo y.

   5. Se lhe for pedido que permita o acesso público: responda y. Pode não ver este pedido se existir uma política organizacional de restrição de domínio que o impeça. Para mais detalhes, consulte a secção Antes de começar.

   Em seguida, aguarde alguns momentos até que a implementação esteja concluída. Em caso de êxito, a linha de comandos apresenta o URL do serviço. Navegue para /list-apps a partir do URL do seu serviço. Por exemplo, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Execute o seu agente

Para consultar o agente 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 seu serviço implementado.

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 devolve as informações meteorológicas nos resultados da sua consulta.

Para mais informações e exemplos sobre os comandos curl suportados, consulte o artigo Use o servidor da API na documentação do ADK.

Êxito: implementou um agente de IA através do Agent Development Kit no Cloud Run.

Limpar

Para evitar custos adicionais na sua conta Google Cloud , elimine todos os recursos que implementou com este tutorial.

Elimine o projeto

Se criou um novo projeto para este tutorial, elimine-o. Se usou um projeto existente e precisa de o manter sem as alterações que adicionou neste tutorial, elimine os recursos que criou para o tutorial.

A forma mais fácil de eliminar a faturação é eliminar o projeto que criou para o tutorial.

Para eliminar o projeto:

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

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.

Elimine recursos de tutoriais

1. Elimine o serviço do Cloud Run que implementou neste tutorial. Os serviços do Cloud Run não incorrem em custos até receberem pedidos.

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

   gcloud run services delete SERVICE-NAME

   Substitua SERVICE-NAME pelo nome do seu serviço.

   Também pode eliminar serviços do Cloud Run a partir da Google Cloud consola.

2. Remova a configuração da região predefinida gcloud que adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project