Esta página foi traduzida pela API Cloud Translation.

Início rápido: crie e implemente um agente de IA no Cloud Run com o Agent Development Kit (ADK)

Saiba como usar um único comando para criar e implementar um agente de IA no Cloud Run através do Agent Development Kit (ADK) para Python. O agente que implementa obtém o boletim meteorológico para uma cidade que especificar.

Seguindo os passos neste início rápido, o Cloud Run cria automaticamente um Dockerfile para si quando implementa a partir do código-fonte.

Para mais informações sobre como o buildpack do Python determina o ponto de entrada predefinido para implementações de origem do Cloud Run, consulte o artigo Crie uma aplicação Python.

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.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Se estiver a usar um projeto existente para este guia, verifique se tem as autorizações necessárias para concluir este guia. Se criou um novo projeto, já tem as autorizações necessárias.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select 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.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Se estiver a usar um projeto existente para este guia, verifique se tem as autorizações necessárias para concluir este guia. Se criou um novo projeto, já tem as autorizações necessárias.

Verify that billing is enabled for your Google Cloud project.

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.
```
gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com
```
Instale o ADK seguindo as instruções na documentação do Agent Development Kit.
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.
Reveja os preços do Cloud Run ou estime os custos com a calculadora de preços.

Funções necessárias

Para obter as autorizações de que precisa para concluir este início rápido, peça ao seu administrador que lhe conceda 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.

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

O Cloud Build usa automaticamente a conta de serviço predefinida do Compute Engine como a conta de serviço predefinida do Cloud Build para compilar o seu código-fonte e recurso do Cloud Run, a menos que substitua este comportamento.

Para que o Cloud Build compile as suas origens, conceda à conta de serviço do Cloud Build a função Cloud Run Builder (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 seu projeto e Google Cloudpelo endereço de email da conta de serviço do Cloud Build.SERVICE_ACCOUNT_EMAIL_ADDRESS Se estiver a usar a conta de serviço predefinida do Compute Engine como conta de serviço do Cloud Build, use o seguinte formato para o endereço de email da conta de serviço:

PROJECT_NUMBER-compute@developer.gserviceaccount.com

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

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

A atribuição da função de criador do Cloud Run demora alguns minutos a propagar-se.

Escreva a aplicação de amostra

Para escrever uma aplicação em Python:

Crie um novo diretório principal denominado parent_folder e altere o diretório para o mesmo:
```
mkdir parent_folder
cd parent_folder
```
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
```
Crie um ficheiro __init__.py para importar o agente:
```
from . import agent
```

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

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

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. Se tiver ê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:

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.

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

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.

Limpar

Para evitar custos adicionais na sua conta Google Cloud , elimine todos os recursos implementados com este início rápido.

Elimine o seu repositório

O Cloud Run não lhe cobra nada quando o serviço implementado não está a ser usado. No entanto, ainda pode ser cobrado pelo armazenamento da imagem do contentor no Artifact Registry. Para eliminar repositórios do Artifact Registry, siga os passos em Eliminar repositórios na documentação do Artifact Registry.

Elimine o seu serviço

Os serviços do Cloud Run não incorrem em custos até receberem pedidos. Para eliminar o seu serviço do Cloud Run, siga um destes passos:

Consola

Para eliminar um serviço:

Na Google Cloud consola, aceda à página Serviços do Cloud Run:

Aceda ao Cloud Run
Localize o serviço que quer eliminar na lista de serviços e clique na caixa de verificação para o selecionar.
Clique em Eliminar. Esta ação elimina todas as revisões do serviço.

gcloud

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

gcloud run services delete SERVICE --region REGION

Substitua o seguinte:

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

Elimine o projeto de teste

A eliminação do seu projeto Google Cloud interrompe a faturação de todos os recursos nesse projeto. Para libertar todos os Google Cloud recursos no seu projeto, siga estes passos:

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

O que se segue?

Para mais informações sobre a criação de um contentor a partir do código-fonte e o envio para um repositório, consulte: