Compila una app de varios agentes con MCP Toolbox para AlloyDB y el ADK

1. Descripción general

Un agente es un programa autónomo que habla con un modelo de IA para realizar una operación basada en objetivos con las herramientas y el contexto que tiene, y es capaz de tomar decisiones autónomas basadas en la verdad.

Cuando tu aplicación tiene varios agentes que trabajan juntos de forma autónoma y según sea necesario para cumplir con su propósito más amplio, y cada uno de sus agentes tiene conocimientos de forma independiente y es responsable de un área de enfoque específica, tu aplicación se convierte en un sistema multiagente.

El Kit de desarrollo de agentes (ADK)

El Kit de desarrollo de agentes (ADK) es un framework flexible y modular para desarrollar y, luego, implementar agentes de IA. El ADK admite la creación de aplicaciones sofisticadas a través de la composición de varias instancias de agentes distintos en un sistema multiagente (MAS).

En el ADK, un sistema multiagente es una aplicación en la que diferentes agentes, que a menudo forman una jerarquía, colaboran o se coordinan para lograr un objetivo mayor. Estructurar tu aplicación de esta manera ofrece ventajas significativas, como mayor modularidad, especialización, reutilización, capacidad de mantenimiento y la posibilidad de definir flujos de control estructurados con agentes de flujo de trabajo dedicados.

Aspectos que debes tener en cuenta para un sistema multiagente

Primero, es importante comprender y razonar correctamente la especialización de cada agente. "¿Sabes por qué necesitas un subagente específico para algo?", primero averigua eso.

Segundo, cómo reunirlos con un agente raíz para enrutar y comprender cada una de las respuestas.

Tercero, existen varios tipos de enrutamiento de agentes que puedes encontrar aquí en esta documentación. Asegúrate de elegir el que mejor se adapte al flujo de tu aplicación. También debes definir los diversos contextos y estados que necesitas para el control de flujo de tu sistema multiagente.

Qué compilarás

Creemos un sistema multiagente para manejar renovaciones de cocinas con MCP Toolbox para AlloyDB y ADK.

Agente de propuestas de renovación
Agente de verificación de permisos y cumplimiento
Verificación del estado del pedido (herramienta que usa MCP Toolbox para bases de datos)

Agente de propuestas de renovación, para generar el documento de propuesta de renovación de la cocina.

Agente de Permisos y Cumplimiento, para ocuparse de las tareas relacionadas con los permisos y el cumplimiento

Agente de verificación del estado del pedido para verificar el estado del pedido de materiales trabajando en la base de datos de administración de pedidos que configuramos en AlloyDB. Sin embargo, para esta parte de la base de datos, usaremos MCP Toolbox para AlloyDB para implementar la lógica de recuperación del estado de los pedidos.

2. MCP

MCP significa Protocolo de contexto del modelo, un estándar abierto desarrollado por Anthropic que proporciona una forma coherente para que los agentes de IA se conecten con herramientas, servicios y datos externos. Básicamente, funciona como un estándar común para las aplicaciones de IA, lo que les permite interactuar sin problemas con diferentes fuentes de datos y herramientas.

Utiliza un modelo cliente-servidor, en el que las aplicaciones de IA (los hosts) ejecutan el cliente de MCP, que se comunica con los servidores de MCP.
Cuando un agente de IA necesita acceder a una herramienta o datos específicos, envía una solicitud estructurada al cliente de MCP, que la reenvía al servidor de MCP adecuado.
Permite que los modelos de IA accedan a datos y herramientas externos sin necesidad de código personalizado para cada integración.
Simplifica el proceso de creación de agentes y flujos de trabajo complejos sobre modelos de lenguaje grandes (LLM).

MCP Toolbox para bases de datos

MCP Toolbox for Databases de Google es un servidor de MCP de código abierto para bases de datos. Se diseñó pensando en la calidad de producción y el nivel empresarial. Te permite desarrollar herramientas de forma más fácil, rápida y segura, ya que se encarga de las complejidades, como la agrupación de conexiones, la autenticación y mucho más.

Permite que tus agentes accedan a los datos de tu base de datos. ¿Cómo?

Desarrollo simplificado: Integra herramientas a tu agente con menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks y, luego, implementa nuevas versiones de las herramientas con mayor facilidad.

Mejor rendimiento: Prácticas recomendadas, como la agrupación de conexiones, la autenticación y mucho más.

Seguridad mejorada: Autenticación integrada para un acceso más seguro a tus datos

Observabilidad de extremo a extremo: Métricas y seguimiento listos para usar con compatibilidad integrada para OpenTelemetry.

Tenemos que mencionar el hecho de que esto es anterior al MCP.

MCP Toolbox for Databases se encuentra entre el framework de organización de tu aplicación basada en agentes y tu base de datos, y proporciona un plano de control que se usa para modificar, distribuir o invocar herramientas. Simplifica la administración de tus herramientas, ya que te proporciona una ubicación centralizada para almacenarlas y actualizarlas, lo que te permite compartirlas entre agentes y aplicaciones, y actualizarlas sin necesidad de volver a implementar tu aplicación.

Tendremos un agente raíz que coordinará estos agentes según el requisito.

Requisitos

Un navegador, como Chrome o Firefox.
Un proyecto de Google Cloud con facturación habilitada.

3. Antes de comenzar

Crea un proyecto

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto .

Además, si estás leyendo esto y quieres obtener créditos para comenzar a usar Google Cloud y el ADK, usa este vínculo para canjear créditos. Puedes seguir las instrucciones aquí para canjearlo. Ten en cuenta que este vínculo solo es válido hasta fines de mayo para canjear la tarjeta.

Haz clic en este vínculo para activar Cloud Shell. Para alternar entre la terminal de Cloud Shell (para ejecutar comandos de Cloud) y el editor (para compilar proyectos), haz clic en el botón correspondiente de Cloud Shell.
Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto usando el siguiente comando:

gcloud auth list

En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Ejecuta los siguientes comandos para habilitar las APIs:

gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com

Asegúrate de tener Python 3.9 o una versión posterior.
Consulta la documentación para ver los comandos y el uso de gcloud.

4. Configuración del ADK

Crea y activa el entorno virtual (recomendado)

En la terminal de Cloud Shell, crea un entorno virtual:

python -m venv .venv

Activa el entorno virtual:

source .venv/bin/activate

Instala el ADK.

pip install google-adk

5. Estructura del proyecto

Desde la terminal de Cloud Shell, ejecuta los siguientes comandos uno por uno para crear las carpetas raíz y del proyecto:

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

Ve al editor de Cloud Shell y crea la siguiente estructura del proyecto creando los archivos (vacíos al principio):

renovation-agent/
        __init__.py
        agent.py
        .env

6. Código fuente

Ve a init.py y actualízalo con el siguiente contenido:

from . import agent

Ve a agent.py y actualiza el archivo con el siguiente contenido de la siguiente ruta:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

En agent.py, importamos las dependencias necesarias, recuperamos los parámetros de configuración del archivo .env y definimos el root_agent que usa 1 herramienta para invocar la herramienta de la caja de herramientas.

Ve a requirements.txt y actualízalo con el contenido de lo siguiente:

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

7. Configuración de la base de datos

En una de las herramientas que usa ordering_agent, llamada "check_status", accedemos a la base de datos de pedidos de AlloyDB para obtener el estado de los pedidos. En esta sección, configuraremos un clúster y una instancia de la base de datos de AlloyDB.

Crea un clúster y una instancia

Navega por la página de AlloyDB en Cloud Console. Una forma sencilla de encontrar la mayoría de las páginas en la consola de Cloud es buscarlas con la barra de búsqueda de la consola.
Selecciona CREATE CLUSTER en esa página:

Verás una pantalla como la que se muestra a continuación. Crea un clúster y una instancia con los siguientes valores (asegúrate de que los valores coincidan si clonas el código de la aplicación desde el repo):

ID del clúster: "vector-cluster"
contraseña: "alloydb"
Se recomienda PostgreSQL 16 compatible o la versión más reciente.
Región: "us-central1"
Networking: "default"

Cuando selecciones la red predeterminada, verás una pantalla como la que se muestra a continuación.

Selecciona CONFIGURAR CONEXIÓN.

Allí, selecciona "Usar un rango de IP asignado automáticamente" y haz clic en Continuar. Después de revisar la información, selecciona CREAR CONEXIÓN.

6. NOTA IMPORTANTE: Asegúrate de cambiar el ID de la instancia (que puedes encontrar en el momento de configurar el clúster o la instancia) a

vector-instance. Si no puedes cambiarlo, recuerda usar el ID de tu instancia en todas las referencias futuras.

Como preparación para configurar Toolbox, habilitaremos la conectividad de IP pública en nuestra instancia de AlloyDB para que la nueva herramienta pueda acceder a la base de datos.
Ve a la sección Conectividad de IP pública, marca la casilla de verificación Habilitar IP pública y, luego, ingresa la dirección IP de tu máquina de Cloud Shell.
Para obtener la IP de tu máquina de Cloud Shell, ve a la terminal de Cloud Shell y, luego, ingresa ifconfig. En el resultado, identifica la dirección inet de eth0 y reemplaza los últimos 2 dígitos por 0.0 con un tamaño de máscara "/16". Por ejemplo, se vería como "XX.XX.0.0/16", donde XX son números.
Pega esta IP en el cuadro de texto “Redes” de las redes externas autorizadas en la página de edición de la instancia.

Una vez que configures tu red, podrás continuar con la creación del clúster. Haz clic en CREAR CLÚSTER para completar la configuración del clúster, como se muestra a continuación:

Ten en cuenta que la creación del clúster tardará alrededor de 10 minutos. Una vez que se complete correctamente, deberías ver una pantalla que muestre el resumen del clúster que acabas de crear.

Transferencia de datos

Ahora es momento de agregar una tabla con los datos de la tienda. Navega a AlloyDB, selecciona el clúster principal y, luego, AlloyDB Studio:

Es posible que debas esperar a que termine de crearse la instancia. Una vez que lo hagas, accede a AlloyDB con las credenciales que creaste cuando creaste el clúster. Usa los siguientes datos para autenticarte en PostgreSQL:

Nombre de usuario : "postgres"
Base de datos : "postgres"
Contraseña : "alloydb"

Una vez que te autentiques correctamente en AlloyDB Studio, ingresa los comandos SQL en el editor. Puedes agregar varias ventanas del editor con el signo más que se encuentra a la derecha de la última ventana.

Ingresarás comandos para AlloyDB en ventanas del editor, y usarás las opciones Ejecutar, Formatear y Borrar según sea necesario.

Crea una tabla

Puedes crear una tabla con la siguiente instrucción DDL en AlloyDB Studio:

-- Table DDL for Procurement Material Order Status

CREATE TABLE material_order_status (
    order_id VARCHAR(50) PRIMARY KEY,
    material_name VARCHAR(100) NOT NULL,
    supplier_name VARCHAR(100) NOT NULL,
    order_date DATE NOT NULL,
    estimated_delivery_date DATE,
    actual_delivery_date DATE,
    quantity_ordered INT NOT NULL,
    quantity_received INT,
    unit_price DECIMAL(10, 2) NOT NULL,
    total_amount DECIMAL(12, 2),
    order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
    delivery_address VARCHAR(255),
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    tracking_number VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    quality_check_passed BOOLEAN,  -- Indicates if the material passed quality control
    quality_check_notes TEXT,        -- Notes from the quality control check
    priority VARCHAR(20),            -- e.g., "High", "Medium", "Low"
    project_id VARCHAR(50),          -- Link to a specific project
    receiver_name VARCHAR(100),        -- Name of the person who received the delivery
    return_reason TEXT,               -- Reason for returning material if applicable
    po_number VARCHAR(50)             -- Purchase order number
);

Insertar registros

Copia la instrucción de consulta insert de la secuencia de comandos database_script.sql mencionada anteriormente en el editor.

Haz clic en Ejecutar.

Ahora que el conjunto de datos está listo, configuremos MCP Toolbox para bases de datos para que actúe como el plano de control de todas nuestras interacciones con la base de datos de pedidos en AlloyDB.

8. Configuración de MCP Toolbox para bases de datos

Toolbox se encuentra entre el framework de orquestación de tu aplicación y tu base de datos, y proporciona un plano de control que se usa para modificar, distribuir o invocar herramientas. Simplifica la administración de tus herramientas, ya que te proporciona una ubicación centralizada para almacenarlas y actualizarlas, lo que te permite compartirlas entre agentes y aplicaciones, y actualizarlas sin necesidad de volver a implementar tu aplicación.

Puedes ver que una de las bases de datos compatibles con MCP Toolbox para bases de datos es AlloyDB y, como ya la aprovisionamos en la sección anterior, configuremos Toolbox.

Navega a la terminal de Cloud Shell y asegúrate de que tu proyecto esté seleccionado y se muestre en el mensaje de la terminal. Ejecuta el siguiente comando desde la terminal de Cloud Shell para navegar al directorio de tu proyecto:

cd adk-renovation-agent

Ejecuta el siguiente comando para descargar e instalar la caja de herramientas en tu carpeta nueva:

# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Navega al editor de Cloud Shell (para el modo de edición de código) y, en la carpeta raíz del proyecto, agrega un archivo llamado "tools.yaml".

sources:
    alloydb-orders:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
        instance: "<<YOUR_ALLOYDB_INSTANCE>>"
        database: "<<YOUR_ALLOYDB_DATABASE>>"
        user: "<<YOUR_ALLOYDB_USER>>"
        password: "<<YOUR_ALLOYDB_PASSWORD>>"

tools:
  get-order-data:
    kind: postgres-sql
    source: alloydb-orders
    description: Get the status of an order based on the material description.
    parameters:
      - name: description
        type: string
        description: A description of the material to search for its order status.
    statement: |
      select order_status from material_order_status where lower(material_name) like lower($1) 
      LIMIT 1;

En la parte de la consulta (consulta el parámetro "statement" más arriba), solo recuperamos el valor del campo order_status cuando el nombre del material coincide con el texto de búsqueda del usuario.

Comprendamos tools.yaml

Las fuentes representan las diferentes fuentes de datos con las que una herramienta puede interactuar. Un objeto Source representa una fuente de datos con la que puede interactuar una herramienta. Puedes definir fuentes como un mapa en la sección sources de tu archivo tools.yaml. Por lo general, una configuración de origen contendrá toda la información necesaria para conectarse con la base de datos y para interactuar con ella.

Las herramientas definen las acciones que puede realizar un agente, como leer y escribir en una fuente. Una herramienta representa una acción que puede realizar tu agente, como ejecutar una instrucción SQL. Puedes definir herramientas como un mapa en la sección tools de tu archivo tools.yaml. Por lo general, una herramienta requerirá una fuente para actuar.

Para obtener más detalles sobre cómo configurar tu archivo tools.yaml, consulta esta documentación.

Ejecutemos el servidor de MCP Toolbox para bases de datos

Ejecuta el siguiente comando (desde la carpeta mcp-toolbox) para iniciar el servidor:

./toolbox --tools-file "tools.yaml"

Ahora, si abres el servidor en modo de vista previa web en la nube, deberías poder ver el servidor de Toolbox en funcionamiento con tu nueva herramienta llamada get-order-data.

El servidor de MCP Toolbox se ejecuta de forma predeterminada en el puerto 5000. Usemos Cloud Shell para probarlo.

Haz clic en Vista previa en la Web en Cloud Shell, como se muestra a continuación:

Haz clic en Cambiar puerto y establece el puerto en 5000, como se muestra a continuación. Luego, haz clic en Cambiar y obtener vista previa.

Esto debería generar el siguiente resultado:

El MCP Toolkit for Databases describe un SDK de Python para que valides y pruebes las herramientas, que se documenta aquí. Omitiremos ese paso y pasaremos directamente al Kit de desarrollo de agentes (ADK) en la siguiente sección, en la que se utilizarán estas herramientas.

Implementemos Toolbox en Cloud Run

Primero, podemos comenzar con el servidor de MCP Toolbox y alojarlo en Cloud Run. Esto nos proporcionaría un extremo público que podríamos integrar con cualquier otra aplicación o con las aplicaciones del agente. Las instrucciones para alojar esto en Cloud Run se proporcionan aquí. Ahora repasaremos los pasos clave.

Inicia una nueva terminal de Cloud Shell o usa una existente. Ve a la carpeta del proyecto en la que se encuentran el archivo binario de la caja de herramientas y el archivo tools.yaml, en este caso adk-renovation-agent.
Configura la variable PROJECT_ID para que apunte a tu ID del proyecto de Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

Habilita estos servicios de Google Cloud

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Creemos una cuenta de servicio independiente que actuará como la identidad del servicio de Toolbox que implementaremos en Google Cloud Run.

gcloud iam service-accounts create toolbox-identity

También nos aseguramos de que esta cuenta de servicio tenga los roles correctos, es decir, la capacidad de acceder a Secret Manager y comunicarse con AlloyDB.

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/alloydb.client

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/serviceusage.serviceUsageConsumer

Subiremos el archivo tools.yaml como un secreto:

gcloud secrets create tools --data-file=tools.yaml

Si ya tienes un secreto y quieres actualizar su versión, ejecuta el siguiente comando:

gcloud secrets versions add tools --data-file=tools.yaml

Establece una variable de entorno en la imagen de contenedor que deseas usar para Cloud Run:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

El último paso del comando de implementación conocido en Cloud Run:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

Esto debería iniciar el proceso de implementación del servidor de Toolbox con nuestro archivo tools.yaml configurado en Cloud Run. Si la implementación se realizó correctamente, deberías ver un mensaje similar al siguiente:

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

Ya está todo listo para usar la herramienta que acabas de implementar en tu aplicación basada en agentes.

Conectemos la herramienta Toolbox a nuestro agente.

Ya creamos la fuente para nuestra aplicación de agente. Actualicemos eso para incluir una nueva herramienta de MCP Toolbox para bases de datos que acabamos de implementar en Cloud Run.

Observa tu archivo requirements.txt con la fuente del repo:

Incluimos la dependencia de MCP Toolbox para bases de datos en requirements.txt

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

Observa tu archivo agent.py con el código del repositorio:

Incluimos la herramienta que invoca el extremo de la caja de herramientas para recuperar los datos del pedido de un material específico solicitado.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

9. Configuración del modelo

La capacidad de tu agente para comprender las solicitudes de los usuarios y generar respuestas se basa en un modelo de lenguaje grande (LLM). Tu agente debe realizar llamadas seguras a este servicio externo de LLM, lo que requiere credenciales de autenticación. Sin una autenticación válida, el servicio de LLM rechazará las solicitudes del agente y este no podrá funcionar.

Obtén una clave de API de Google AI Studio.
En el siguiente paso, en el que configurarás el archivo .env, reemplaza <<your API KEY>> por el valor real de tu clave de API.

10. Configuración de variables de entorno

Configura tus valores para los parámetros en el archivo .env de la plantilla. En mi caso, el archivo .env tiene estas variables:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>

Reemplaza los marcadores de posición por tus valores.

11. Ejecuta tu agente

Con la terminal, navega al directorio principal de tu proyecto del agente:

cd renovation-agent

Instala las dependencias:

pip install -r requirements.txt

Puedes ejecutar el siguiente comando en tu terminal de Cloud Shell para ejecutar el agente:

adk run .

Puedes ejecutar lo siguiente para ejecutarlo en una IU web aprovisionada por el ADK:

adk web

Haz la prueba con las siguientes instrucciones:

user>> 

Hello. Check order status for Cement Bags.

12. Resultado

13. Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta publicación:

En la consola de Google Cloud, ve a la página Administrar recursos.
En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

14. Felicitaciones

¡Felicitaciones! Creaste correctamente una aplicación multiagente con el ADK y MCP Toolbox para bases de datos. Para obtener más información, consulta la documentación del producto: Kit de desarrollo de agentes y MCP Toolbox para bases de datos.

Compila una app de varios agentes con MCP Toolbox para AlloyDB y el ADK Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.