Guia de início rápido: criar e implantar um agente de IA no Cloud Run usando o Kit de Desenvolvimento de Agente (ADK)

Guia de início rápido: criar e implantar um agente de IA no Cloud Run usando o Kit de Desenvolvimento de Agente (ADK)

Saiba como usar um único comando para criar e implantar um agente de IA no Cloud Run usando o Kit de Desenvolvimento de Agente (ADK) para Python. O agente implantado recupera a previsão do tempo para uma cidade especificada.

Ao seguir as etapas deste guia de início rápido, o Cloud Run automaticamente cria um Dockerfile quando você implanta do código-fonte.

Para mais informações sobre como o buildpack do Python determina o ponto de entrada padrão para implantações de origem do Cloud Run, consulte Criar um aplicativo Python.

Antes de começar

Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a Google Cloud CLI.

Observação: se você já tiver instalado a CLI gcloud anteriormente, verifique se você tem a versão mais recente executando gcloud components update.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel Criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto do:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto do que você está criando.

• Selecione o Google Cloud projeto do que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto do.

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

Verifique se o faturamento está ativado para o Google Cloud projeto.

Instale a Google Cloud CLI.

Observação: se você já tiver instalado a CLI gcloud anteriormente, verifique se você tem a versão mais recente executando gcloud components update.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel Criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto do:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto do que você está criando.

• Selecione o Google Cloud projeto do que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto do.

Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.

Verifique se o faturamento está ativado para o Google Cloud projeto.

1. Ative a API Cloud Run Admin, a API Vertex AI e as APIs Cloud Build:

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

   gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com

2. Instale o ADK seguindo as instruções na documentação do Kit de Desenvolvimento de Agente.

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

4. Analise os preços do Cloud Run ou estime os custos com a calculadora de preços.

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir o guia de início rápido, 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 personalizados papéis ou outros predefinidos papéis.

Conceder acesso à conta de serviço do Cloud Build ao seu projeto

O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar o código-fonte e o recurso do Cloud Run, a menos que você substitua esse comportamento.

Para que o Cloud Build crie suas origens, conceda à conta de serviço do Cloud Build o Criador do Cloud Run(roles/run.builder) papel no seu projeto:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Substitua PROJECT_ID pelo ID do seu Google Cloud projeto e SERVICE_ACCOUNT_EMAIL_ADDRESS pelo endereço de e-mail da conta de serviço do Cloud Build. Se você estiver usando a conta de serviço padrão do Compute Engine como a conta de serviço do Cloud Build, use o seguinte formato para o endereço de e-mail da conta de serviço:

[e-mail]

Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud.

Para instruções detalhadas sobre como encontrar o ID do projeto e o número do projeto, consulte Criar e gerenciar projetos.

A concessão do papel de criador do Cloud Run leva alguns minutos para se propagar.

Crie o aplicativo de exemplo

Para escrever um aplicativo em Python:

1. Crie um novo diretório pai chamado parent_folder e altere o diretório nele:

   mkdir parent_folder
   cd parent_folder
   

2. No diretório parent_folder, crie um novo subdiretório chamado multi_tool_agent e altere o diretório nele:

   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 para responder a perguntas sobre a hora e o clima em uma 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 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 Google Cloud ID do projeto.
   • REGION: a região em que você planeja implantar o serviço.

6. Navegue até o diretório da pasta pai 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 acesso público: 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. Navegue até /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 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.

Muito bem ! Você implantou um agente de IA usando o Kit de Desenvolvimento de Agente no Cloud Run.

Liberar espaço

Para evitar cobranças adicionais na sua Google Cloud conta do, exclua todos os recursos implantados com este guia de início rápido.

Excluir o repositório

O Cloud Run não cobra quando o serviço implantado não está em uso. No entanto, ainda é possível que você receba cobranças pelo armazenamento da imagem de contêiner no Artifact Registry. Para excluir repositórios do Artifact Registry, siga as etapas em Excluir repositórios na documentação do Artifact Registry.

Excluir o serviço

Os serviços do Cloud Run não geram custos até receberem solicitações. Para excluir o serviço do Cloud Run, siga uma destas etapas:

Console

Para excluir um serviço, realize as etapas a seguir:

1. Noconsole, acesse a página Serviços do Cloud Run: Google Cloud

   Acessar o Cloud Run

2. Localize o serviço que você quer excluir na lista de serviços e clique na caixa de seleção para marcá-lo.

3. Clique em Excluir. Isso excluirá todas as revisões do serviço. Isso excluirá todas as revisões do serviço.

gcloud

Para excluir um serviço, execute o seguinte comando:

gcloud run services delete SERVICE --region REGION

Substitua:

• SERVICE: nome do serviço.
• REGION: Google Cloud região do serviço.

Excluir o projeto de teste

A exclusão do seu Google Cloud projeto interrompe o faturamento de todos os recursos nesse projeto. Para liberar todos os Google Cloud recursos no projeto, siga estas etapas:

Cuidado: excluir 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 appspot.com URL, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Excluir um Google Cloud projeto do:

gcloud projects delete PROJECT_ID

A seguir

Para mais informações sobre como criar um contêiner a partir do código-fonte e enviá-lo para um repositório, consulte:

• Como desenvolver serviços do Cloud Run
• Como criar contêineres
• Testar um serviço do Cloud Run localmente
• Como implantar do código-fonte