Guía de inicio rápido: Compila e implementa un agente de IA en Cloud Run con el Kit de desarrollo de agentes (ADK)

Guía de inicio rápido: Compila e implementa un agente de IA en Cloud Run con el Kit de desarrollo de agentes (ADK)

Aprende a usar un solo comando para compilar e implementar un agente de IA en Cloud Run con el Kit de desarrollo de agentes (ADK) para Python. El agente que implementas recupera el informe meteorológico de una ciudad que especificas.

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 a partir del código fuente.

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

Antes de comenzar

Accede a tu Google Cloud cuenta de. 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, asegúrate de tener la versión más reciente ejecutando gcloud components update.

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.
• Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto 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 Google Cloud proyecto de que estás creando.

• Selecciona el Google Cloud proyecto de que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud .

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 Google Cloud proyecto.

Instala Google Cloud CLI.

Nota: Si ya instalaste gcloud CLI, asegúrate de tener la versión más reciente ejecutando gcloud components update.

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.
• Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto 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 Google Cloud proyecto de que estás creando.

• Selecciona el Google Cloud proyecto de que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud .

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 Google Cloud proyecto.

1. Habilita la API de Cloud Run Admin, la API de Vertex AI y las APIs de 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 serviceusage.services.enable permiso. Obtén más información para otorgar roles.

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

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

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

4. Revisa los precios de Cloud Run o estima los costos con la calculadora de precios.

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:

• Desarrollador de origen de Cloud Run (roles/run.sourceDeveloper) en el proyecto
• Usuario de Vertex AI (roles/aiplatform.user) 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 la cuenta de servicio de Cloud Build a tu proyecto

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 el rol de compilador de Cloud Run (roles/run.builder) a la cuenta de servicio de Cloud Build 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 Google Cloud ID del proyecto y 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 superior nuevo llamado parent_folder y usa el comando de cambio de directorio en él:

   mkdir parent_folder
   cd parent_folder
   

2. En el directorio parent_folder, crea un subdirectorio nuevo llamado multi_tool_agent y usa el comando de cambio de directorio en él:

   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 clima en una ciudad 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],
   )
   

5. Crea un archivo .env y agrega las siguientes variables:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el Google Cloud ID del proyecto de.
   • REGION: Es la región en la que planeas implementar tu servicio.

6. Navega al directorio de la carpeta superior parent_folder y crea un archivo requirements.txt para agregar la dependencia google-adk:

   google-adk
   

   Tu proyecto de origen incluye la siguiente estructura:

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

La app está lista para implementarse.

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.

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

   gcloud run deploy --source .

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

   2. Si se te solicita que habilites las APIs adicionales en el proyecto, por ejemplo, la API de Artifact Registry, presiona y para responder.

   3. Cuando se te solicite la región, selecciona la región que prefieras, por ejemplo, europe-west1.

   4. Si se te solicita que crees un repositorio en la región especificada, presiona y para responder.

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

   Luego, espera un momento a que finalice la implementación. Si la operación se completa de forma correcta, la línea de comandos mostrará la URL de servicio. Navega a /list-apps desde la URL de tu servicio. Por ejemplo, https://weather-agent-123456789101.us-central1.run.app/list-apps.

Ejecuta tu agente

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

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

   curl -X GET SERVICE_URL/list-apps
   

   Reemplaza SERVICE_URL por la URL de tu 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 muestra la información meteorológica en los resultados de tu consulta.

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

Completado correctamente: Implementaste un agente de IA con el Kit de desarrollo de agentes en Cloud Run.

Limpia

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

Borra tu repositorio

Cloud Run no te cobra cuando tu servicio implementado no está en uso. Sin embargo, es posible que aún se te cobre por almacenar la imagen de 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 Google Cloud consola de, 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: Es el nombre de tu servicio.
• REGION: Google Cloud Es la región del servicio.

Borra tu proyecto de prueba

Si borras tu Google Cloud proyecto de, se dejan de facturar todos los recursos que usaste en ese proyecto. Para liberar todos los Google Cloud recursos de tu proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene estas 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 appspot.com URL, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Borra un Google Cloud proyecto de:

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