O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 o relatório meteorológico de 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

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.
Configure a CLI gcloud para usar sua identidade federada.

Para mais informações, consulte Fazer login na CLI gcloud 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.
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 a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pelo papel Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
```
gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com
```
Instale o ADK seguindo as instruções na documentação do Kit de Desenvolvimento de Agente.
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.
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 com papéis personalizados ou outros papéis predefinidos.

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:

PROJECT_NUMBER-compute@

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 ser propagada.

Crie o aplicativo de exemplo

Para escrever um aplicativo em Python:

Crie um novo diretório pai chamado parent_folder e mude o diretório nele:
```
mkdir parent_folder
cd parent_folder
```
No diretório parent_folder, crie um novo subdiretório chamado multi_tool_agent e mude o diretório nele:
```
mkdir multi_tool_agent
cd multi_tool_agent
```
Crie um arquivo __init__.py para importar o agente:
```
from . import agent
```

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.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],
)

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.
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 a partir da origem cria automaticamente uma imagem de contêiner com base no código-fonte e a implanta.

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 mostra o URL de serviço do agente implantado. Ele estará no formato a seguir: https://weather-agent-123456789101.us-central1.run.app/list-apps.

Executar o agente

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

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.

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"}'

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.

Limpar

Para evitar cobranças adicionais na sua Google Cloud conta, 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:

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

Acesse o Cloud Run
Localize o serviço que você quer excluir na lista de serviços e clique na caixa de seleção para marcá-lo.
Clique em Excluir. Isso exclui 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:

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: