Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 de uma cidade especificada.

Ao seguir as etapas deste guia de início rápido, o Cloud Run cria automaticamente 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 conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça 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: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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 projeto do Google Cloud .

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça 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: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

Crie um projeto do Google Cloud :
```
gcloud projects create PROJECT_ID
```
Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.
Selecione o projeto Google Cloud que você criou:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

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 projeto do Google Cloud .

Ative as APIs Cloud Run Admin, Vertex AI e Cloud Build:
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. 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.
Consulte 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 de 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.

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

Por padrão, o Cloud Build usa a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar seu 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 papel Builder do Cloud Run (roles/run.builder) 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 projeto Google Cloude 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@developer.gserviceaccount.com

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 da função de builder do Cloud Run leva alguns minutos para se propagar.

Crie o aplicativo de exemplo

Para escrever um aplicativo em Python:

Crie um novo diretório principal chamado parent_folder e mude para ele:
```
mkdir parent_folder
cd parent_folder
```
No diretório parent_folder, crie um subdiretório chamado multi_tool_agent e mude para ele:
```
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 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.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 ID do projeto do Google Cloud .
- REGION: a região em que você planeja implantar o serviço.
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 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, 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 do 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:

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

Limpar

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

Excluir o repositório

O Cloud Run não gera cobranças quando o serviço implantado não está em uso. No entanto, ainda é possível receber cobranças pelo armazenamento da imagem do 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:

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

Acessar 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 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 projeto Google Cloud interrompe o faturamento de todos os recursos nele. Para liberar todos os recursos Google Cloud no seu projeto, siga estas etapas:

Excluir um projeto do Google Cloud :

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: