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

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 puedan 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 para Python. Este agente recupera el informe meteorológico de la 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 generar 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

Accede a tu cuenta de Google Cloud . Si es la primera vez que usas 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.

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. Habilita la API de Cloud Run Admin, Vertex AI y Cloud Build si alguna de ellas aún no está habilitada.

   Roles necesarios para habilitar las APIs

   Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

   Habilitar las API

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 cambia a ese 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 clima en una ciudad específica:

   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.5-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 de 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 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 del agente implementado, que tendrá el siguiente formato: https://weather-agent-123456789101.us-central1.run.app/list-apps.

Ejecuta tu agente

Para usar el agente de ADK, puedes ejecutar 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": "value2"}'
   

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 la API en la documentación del ADK.

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

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

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. En la Google Cloud consola, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

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 predeterminada de la región 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