Guia de início rápido: criar e implantar um app da Web em Python (smolagents) no Cloud Run

Guia de início rápido: criar e implantar um app da Web em Python (smolagents) no Cloud Run

Este documento mostra como criar e implantar um aplicativo smolagents no Cloud Run.

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.

Antes de começar

Faça login na sua Google Cloud conta do. Se você é novo no 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 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, é necessário ter o papel de 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 planeja manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um projeto atual. Depois de concluir essas etapas, você poderá excluir o projeto, removendo todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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 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, é necessário ter o papel de 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 planeja manter os recursos criados neste procedimento, crie um projeto em vez de selecionar um projeto atual. Depois de concluir essas etapas, você poderá excluir o projeto, removendo todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

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

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

2. Ative a API Cloud Run Admin 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 cloudbuild.googleapis.com

   Depois que a API Cloud Run Admin for ativada, a conta de serviço padrão do Compute Engine será criadas automaticamente.

3. Analise os preços do Cloud Run ou estime os custos com a calculadora de preços.
4. Você precisa de uma chave de API do Google AI Studio para implantar o app smolagents com um modelo do Gemini. Para gerar uma chave de API usando o Google AI Studio, consulte Como usar chaves de API do Gemini na documentação da API Gemini.

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:

• Administrador do Cloud Run (roles/run.admin) no projeto
• Desenvolvedor de origem do Cloud Run (roles/run.sourceDeveloper) 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 papel de criador 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 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 seu Google Cloud número do projeto.

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:

1. Crie um novo diretório com o nome my-agent-app e altere o diretório nele:

   mkdir my-agent-app
   cd my-agent-app
   

2. Crie um arquivo chamado main.py e cole o seguinte código nele:

   import os
   from fastapi import FastAPI, HTTPException
   from pydantic import BaseModel
   from smolagents import CodeAgent, LiteLLMModel, tool
   
   # 1. Define a simple tool for the agent
   @tool
   def get_greeting(name: str) -> str:
     """
     Returns a special greeting for the user.
     Args:
         name: The name of the person to greet.
     """
     return f"Hello {name}, welcome to the agentic world running on Cloud Run!"
   
   # 2. Initialize the Gemini Model via LiteLLM
   # Make sure GEMINI_API_KEY is set in your environment variables
   model = LiteLLMModel(
   model_id="gemini/gemini-2.5-flash", # This is the model name. If a newer model is available, you can use that.
   api_key=os.environ.get("GEMINI_API_KEY")
   )
   
   # 3. Create the CodeAgent
   agent = CodeAgent(
     tools=[get_greeting],
     model=model,
     add_base_tools=True # Adds basic python tools like print
   )
   
   # 4. Setup FastAPI
   app = FastAPI()
   
   class AgentRequest(BaseModel):
     task: str
   
   @app.get("/")
   def health_check():
     return {"status": "running", "service": "smolagents-fastapi"}
   
   @app.post("/run")
   def run_agent(request: AgentRequest):
     try:
       # Run the agent with the user's task
       response = agent.run(request.task)
       return {"response": str(response)}
     except Exception as e:
       raise HTTPException(status_code=500, detail=str(e))
   

3. Crie um arquivo chamado requirements.txt e cole o seguinte código nele:

   fastapi
   uvicorn
   smolagents[toolkit]
   litellm
   

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.

Para implantar da origem usando o comando a seguir:

  gcloud run deploy smolagents-demo \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

Substitua API_KEY pela sua chave de API do Google AI Studio.

O Cloud Run mostra o URL do serviço, como https://smolagents-demo-xyz-uc.a.run.app, depois que você implanta o app.

Sucesso:você implantou um app da Web smolagents no Cloud Run.

Testar o serviço do Cloud Run

Teste o serviço enviando uma tarefa ao agente usando o seguinte comando curl:

  curl -X POST YOUR-SERVICE-URL/run \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"task": "Use the greeting tool to say hello to Gemini User"}'

Substitua YOUR-SERVICE-URL pelo URL do serviço.

O agente envia a seguinte resposta:

{
 "response": "Hello Gemini User, welcome to the agentic world running on Cloud Run!"
}

Para verificar se o serviço está funcionando corretamente, confira a guia Registros do serviço do Cloud Run.

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, exclua o Google Cloud projeto do e os recursos.

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ê seja cobrado 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 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 Google Cloud projeto interrompe o faturamento de todos os recursos desse projeto. Para liberar todos os Google Cloud recursos no projeto, siga estas etapas:

Atenção: a exclusão de 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:

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