Guía de inicio rápido: Compila y, luego, implementa una app web de Python (smolagents) en Cloud Run

Guía de inicio rápido: Compila y, luego, implementa una app web de Python (smolagents) en Cloud Run

En este documento, se muestra cómo compilar e implementar una aplicación de smolagents en Cloud Run.

Si sigues los pasos de esta guía de inicio rápido, Cloud Run compilará automáticamente un Dockerfile por ti cuando realices la implementación desde el código fuente.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Instala Google Cloud CLI.

Nota: Si ya instalaste gcloud CLI, ejecuta gcloud components update para asegurarte de tener la versión más reciente.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Si usas un proyecto existente en esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Instala Google Cloud CLI.

Nota: Si ya instalaste gcloud CLI, ejecuta gcloud components update para asegurarte de tener la versión más reciente.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Si usas un proyecto existente en esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

1. Si estás bajo una política de la organización de restricción de dominios que restringe las invocaciones no autenticadas para tu proyecto, deberás acceder al servicio implementado como se describe en Prueba servicios privados.

2. Habilita las APIs de Cloud Run Admin y Cloud Build:

   Roles necesarios para habilitar las APIs

   Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

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

   Después de habilitar la API de Cloud Run Admin, se crea de forma automática la cuenta de servicio predeterminada de Compute Engine.

3. Revisa los precios de Cloud Run o estima los costos con la calculadora de precios.
4. Necesitas una clave de API de Google AI Studio para implementar la app de smolagents con un modelo de Gemini. Para generar una clave de API con Google AI Studio, consulta Cómo usar claves de la API de Gemini en la documentación de la API de Gemini.

Roles obligatorios

Si quieres obtener los permisos que necesitas para completar esta guía de inicio rápido, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Administrador de Cloud Run (roles/run.admin) en el proyecto
• Desarrollador de origen de Cloud Run (roles/run.sourceDeveloper) en el proyecto
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) en la identidad del servicio
• Visualizador de registros (roles/logging.viewer) en el proyecto

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga acceso a tu proyecto a la cuenta de servicio de Cloud Build

Cloud Build usa automáticamente la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio predeterminada de Cloud Build para compilar tu código fuente y el recurso de Cloud Run, a menos que anules este comportamiento.

Para que Cloud Build compile tus fuentes, otorga a la cuenta de servicio de Cloud Build el rol de Cloud Run Builder (roles/run.builder) en tu proyecto:

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

Reemplaza PROJECT_ID por tu ID del proyecto Google Cloudy SERVICE_ACCOUNT_EMAIL_ADDRESS por la dirección de correo electrónico de la cuenta de servicio de Cloud Build. Si usas la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio de Cloud Build, usa el siguiente formato para la dirección de correo electrónico de la cuenta de servicio:

[e-mail]

Reemplaza PROJECT_NUMBER por el número del proyecto de Google Cloud.

Para obtener instrucciones detalladas sobre cómo encontrar el ID y el número de tu proyecto, consulta Crea y administra proyectos.

El otorgamiento del rol de compilador de Cloud Run tarda un par de minutos en propagarse.

Escriba la aplicación de ejemplo

Para escribir una aplicación en Python, haz lo siguiente:

1. Crea un directorio nuevo llamado my-agent-app y usa el comando de cambio de directorio en él:

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

2. Crea un archivo llamado main.py y pega el código siguiente en él:

   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. Crea un archivo llamado requirements.txt y pega el código siguiente en él:

   fastapi
   uvicorn
   smolagents[toolkit]
   litellm
   

Implementa en Cloud Run desde la fuente

La implementación desde la fuente compila automáticamente una imagen de contenedor a partir del código fuente y la implementa.

Para realizar la implementación desde la fuente, usa el siguiente comando:

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

Reemplaza API_KEY por tu clave de API de Google AI Studio.

Cloud Run muestra la URL del servicio, como https://smolagents-demo-xyz-uc.a.run.app, después de que implementas la app correctamente.

Éxito: Implementaste una app web de smolagents en Cloud Run.

Prueba tu servicio de Cloud Run

Para probar tu servicio, envía una tarea al agente con el siguiente 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"}'

Reemplaza YOUR-SERVICE-URL por la URL de tu servicio.

El agente envía la siguiente respuesta:

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

Para verificar que tu servicio funcione correctamente, consulta la pestaña Registros del servicio de Cloud Run.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página, borra el proyecto de Google Cloud que tiene los recursos.

Para evitar cargos adicionales en tu cuenta de Google Cloud , borra todos los recursos que implementaste con esta guía de inicio rápido.

Borra tu repositorio

Cloud Run no te cobra cuando el servicio implementado no está en uso. Sin embargo, es posible que se te cobre por almacenar la imagen del contenedor en Artifact Registry. Para borrar repositorios de Artifact Registry, sigue los pasos que se indican en Borra repositorios en la documentación de Artifact Registry.

Borra tu servicio

Los servicios de Cloud Run no generan costos hasta que reciben solicitudes. Para borrar tu servicio de Cloud Run, sigue uno de estos pasos:

Console

Para borrar un servicio, debes hacer lo siguiente:

1. En la consola de Google Cloud , ve a la página Servicios de Cloud Run:

   Ir a Cloud Run

2. Buscar el servicio que deseas borrar en la lista de servicios y hacer clic en su casilla de verificación para seleccionarlo

3. Haz clic en Borrar. Esta acción borra todas las revisiones del servicio

gcloud

Para borrar un servicio, ejecuta el siguiente comando:

gcloud run services delete SERVICE --region REGION

Reemplaza lo siguiente:

• SERVICE: Nombre de tu servicio.
• REGION: Google Cloud región del servicio.

Borra tu proyecto de prueba

Si borras tu proyecto de Google Cloud , se detendrá la facturación de todos los recursos que contenga. Para liberar todos los recursos Google Cloud de tu proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene las siguientes consecuencias:
• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

¿Qué sigue?

Para obtener más información sobre cómo compilar un contenedor a partir de código fuente y enviarlo a un repositorio, consulta los siguientes vínculos:

• Cómo desarrollar servicios de Cloud Run
• Compila contenedores
• Prueba un servicio de Cloud Run de forma local
• Implementa a partir del código fuente