Compila e implementa un agente de IA en Cloud Run con el Kit de desarrollo de agentes (ADK)

Versión preliminar — The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

El framework del Kit de desarrollo de agentes (ADK) simplifica la creación, la evaluación y la implementación de agentes de IA. El ADK proporciona un enfoque modular y centrado en el código para crear agentes que pueden razonar, planificar y utilizar herramientas.

En este instructivo, se muestra cómo compilar e implementar un agente de IA en Cloud Run con el ADK de Python. Este agente recupera el informe meteorológico de una ciudad que especifiques.

Para obtener más información sobre cómo alojar tu agente del ADK con Google Cloud CLI, consulta Implementa en Cloud Run en la documentación del ADK.

Objetivos

• Escribe la aplicación de ejemplo para definir el agente del clima.
• Implementa el agente en Cloud Run desde la fuente.
• Ejecuta tu agente para consultar información sobre el clima.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

Para obtener una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios nuevos de Google Cloud cumplan con los requisitos para acceder a una prueba gratuita.

Antes de comenzar

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.

In the Google Cloud console, on the project selector page, select or create 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create 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.

Go to project selector

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.

   Enable the APIs

2. Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
3. Instala el ADK siguiendo las instrucciones de la documentación del Kit de desarrollo de agentes.

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

Roles obligatorios

Para obtener los permisos que necesitas para implementar un agente de IA en Cloud Run, 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.

Escriba la aplicación de ejemplo

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

1. Crea un directorio principal 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 ID del proyecto de Google Cloud .
   • REGION: Es la región en la que planeas implementar tu servicio.

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

   google-adk
   

   Tu proyecto fuente 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 beta 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 permitir 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 del 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 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 del clima en los resultados de tu búsqueda.

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

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

Realiza una limpieza

Para evitar cargos adicionales en tu cuenta de Google Cloud , borra todos los recursos que implementaste con este instructivo.

Borra el proyecto

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y necesitas conservarlo sin los cambios que agregaste en este instructivo, borra los recursos que creaste para el instructivo.

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue los pasos que se indican más abajo:

Precaución: Borrar un proyecto tiene las consecuencias siguientes:

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

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimina recursos de instructivos

1. Borra el servicio de Cloud Run que implementaste en este instructivo. Los servicios de Cloud Run no generan costos hasta que reciben solicitudes.

   Para borrar tu servicio de Cloud Run, ejecuta el siguiente comando:

   gcloud run services delete SERVICE-NAME

   SERVICE-NAME por el nombre del servicio

   También puedes borrar los servicios de Cloud Run desde la consola deGoogle Cloud .

2. Quita la configuración de región predeterminada de gcloud que agregaste durante la configuración del instructivo:

    gcloud config unset run/region
   

3. Quita la configuración del proyecto:

    gcloud config unset project