Guía de inicio rápido: crea y despliega un agente de IA en Cloud Run con Agent Development Kit (ADK)

Guía de inicio rápido: crea y despliega un agente de IA en Cloud Run con Agent Development Kit (ADK)

Vista previa — The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Aprende a usar un solo comando para crear y desplegar un agente de IA en Cloud Run con Agent Development Kit (ADK) para Python. El agente que implementes recuperará la previsión meteorológica de la ciudad que especifiques.

Si sigues los pasos de esta guía de inicio rápido, Cloud Run creará automáticamente un Dockerfile cuando despliegues desde el código fuente.

Para obtener más información sobre cómo determina el buildpack de Python el punto de entrada predeterminado para las implementaciones de origen de Cloud Run, consulta el artículo Compilar una aplicación de Python.

Antes de empezar

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: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Si vas a usar un proyecto que ya tengas para seguir esta guía, verifica que tienes los permisos necesarios para completarla. Si has creado un proyecto, ya tienes los permisos necesarios.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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

Si vas a usar un proyecto que ya tengas para seguir esta guía, verifica que tienes los permisos necesarios para completarla. Si has creado un proyecto, ya tienes los permisos necesarios.

Verify that billing is enabled for your Google Cloud project.

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

2. Instala el ADK siguiendo las instrucciones de la documentación del kit de desarrollo de agentes.

3. Si tu proyecto está sujeto a una política de organización de restricción de dominio que restringe las invocaciones no autenticadas, tendrás que acceder al servicio desplegado tal como se describe en la sección Probar servicios privados.

4. Consulta los precios de Cloud Run o calcula los costes con la calculadora de precios.

Roles obligatorios

Para obtener los permisos que necesitas para completar esta guía de inicio rápido, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

• Desarrollador de fuentes de Cloud Run (roles/run.sourceDeveloper) en el proyecto
• Usuario de Vertex AI (roles/aiplatform.user) en el proyecto
• Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en la identidad de servicio
• Visualizador de registros (roles/logging.viewer) en el proyecto

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

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

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

Para que Cloud Build compile tus fuentes, concede a la cuenta de servicio de Cloud Build el rol 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

Sustituye PROJECT_ID por el ID de tu proyecto y SERVICE_ACCOUNT_EMAIL_ADDRESS por la dirección de correo de la cuenta de servicio de Cloud Build. Google CloudSi usas la cuenta de servicio predeterminada de Compute Engine como cuenta de servicio de Cloud Build, utiliza el siguiente formato para la dirección de correo de la cuenta de servicio:

[e-mail]

Sustituye PROJECT_NUMBER por el número de tu proyecto. Google Cloud

Para obtener instrucciones detalladas sobre cómo encontrar el ID y el número de tu proyecto, consulta el artículo Crear y gestionar proyectos.

El proceso para conceder el rol de compilador de Cloud Run tarda un par de minutos en propagarse.

Escribir la aplicación de ejemplo

Para escribir una aplicación en Python, sigue estos pasos:

1. Crea un directorio principal llamado parent_folder y cambia al directorio:

   mkdir parent_folder
   cd parent_folder
   

2. En el directorio parent_folder, crea un subdirectorio llamado multi_tool_agent y cambia al directorio:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. Crea un archivo __init__.py para importar el agente:

   from . import agent
   

4. Crea un archivo agent.py para definir el agente que responderá preguntas sobre la hora y el tiempo en una ciudad concreta:

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

5. Crea un archivo .env y añade las siguientes variables:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Haz los cambios siguientes:

   • PROJECT_ID: el ID del proyecto. Google Cloud
   • REGION: la región en la que tienes previsto desplegar tu servicio.

6. Ve al directorio de la carpeta superior parent_folder y crea un archivo requirements.txt para añadir la dependencia google-adk:

   google-adk
   

   Tu proyecto de origen tiene la siguiente estructura:

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

Tu aplicación está terminada y lista para desplegarse.

Desplegar en Cloud Run desde el código fuente

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

1. En el directorio del código fuente (parent_folder), despliega en Cloud Run con el siguiente comando:

   gcloud beta run deploy --source .

   1. Cuando se te pida el nombre del servicio, pulsa Intro para aceptar el nombre predeterminado, por ejemplo, weather-agent.

   2. Si se te pide que habilites APIs adicionales en el proyecto, como la API de Artifact Registry, responde pulsando y.

   3. Cuando se te pida que elijas una región, selecciona la región que quieras, por ejemplo, europe-west1.

   4. Si se te pide que crees un repositorio en la región especificada, responde pulsando y.

   5. Si se te pide que permitas el acceso público: responde y. Es posible que no veas esta petición si hay una política de organización de restricción de dominio que lo impida. Para obtener más información, consulta la sección Antes de empezar.

   A continuación, espera unos instantes hasta que se complete el despliegue. Si la operación se realiza correctamente, la línea de comandos mostrará la URL del servicio. Ve a /list-apps desde la URL de tu servicio. Por ejemplo, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Ejecutar tu agente

Para consultar el agente ADK, ejecuta los siguientes comandos curl:

1. Para obtener la lista de aplicaciones, ejecuta el siguiente comando:

   curl -X GET SERVICE_URL/list-apps
   

   Sustituye SERVICE_URL por la URL del servicio implementado.

2. Para iniciar una sesión, ejecuta el siguiente 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}'
   

3. Para consultar el agente, ejecuta el siguiente 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?\" }]}}"
   

El agente devuelve la información meteorológica en los resultados de tu consulta.

Para obtener más información y ejemplos sobre los comandos curl admitidos, consulta Usar el servidor de la API en la documentación del ADK.

Logro: has desplegado un agente de IA en Cloud Run con Agent Development Kit.

Limpieza

Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud , elimina todos los recursos que hayas desplegado con esta guía de inicio rápido.

Eliminar un repositorio

Cloud Run no te cobra cuando no se usa el servicio desplegado. Sin embargo, es posible que se te cobre por almacenar la imagen de contenedor en Artifact Registry. Para eliminar repositorios de Artifact Registry, sigue los pasos que se indican en el artículo Eliminar repositorios de la documentación de Artifact Registry.

Eliminar tu servicio

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

Consola

Para eliminar un servicio, sigue estos pasos:

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

   Ir a Cloud Run

2. Busca el servicio que quieras eliminar en la lista de servicios y haz clic en la casilla para seleccionarlo.

3. Haz clic en Eliminar. Se eliminarán todas las revisiones del servicio.

gcloud

Para eliminar un servicio, ejecuta el siguiente comando:

gcloud run services delete SERVICE --region REGION

Haz los cambios siguientes:

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

Eliminar un proyecto de prueba

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

Precaución: Eliminar un proyecto tiene los siguientes efectos:
• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Siguientes pasos

Para obtener más información sobre cómo crear un contenedor a partir del código fuente y enviarlo a un repositorio, consulta los siguientes enlaces:

• Desarrollar servicios de Cloud Run
• Crear contenedores
• Probar un servicio de Cloud Run de forma local
• Desplegar desde el código fuente