GENAI124

Descripción general

En este lab, conocerás el Protocolo de contexto del modelo (MCP), un estándar abierto que permite una integración perfecta entre servicios externos, fuentes de datos, herramientas y aplicaciones. Aprenderás a integrar el MCP en tus agentes del ADK con las herramientas que proporcionan los servidores MCP existentes para mejorar tus flujos de trabajo del ADK. Además, verás cómo exponer herramientas del ADK como load_web_page a través de un servidor MCP personalizado, lo que permite una integración más amplia con clientes MCP.

¿Qué es el Protocolo de contexto del modelo (MCP)?

El Protocolo de contexto del modelo (MCP) es un estándar abierto diseñado para estandarizar la forma en que los modelos de lenguaje grandes (LLM), como Gemini y Claude, se comunican con aplicaciones externas, fuentes de datos y herramientas. Considéralo un mecanismo de conexión universal que simplifica la forma en que los LLM obtienen contexto, ejecutan acciones y, además, interactúan con distintos sistemas.

El MCP sigue una arquitectura cliente-servidor que define cómo un servidor MCP expone los datos (recursos), las plantillas interactivas (instrucciones) y las funciones ejecutables (herramientas), y cómo un cliente MCP (que podría ser una aplicación host de LLM o un agente de IA) los consume.

En este lab, se abordan dos patrones de integración principales:

• Uso de servidores MCP existentes en el ADK: Un agente del ADK actúa como cliente MCP y aprovecha las herramientas proporcionadas por servidores MCP externos.
• Exposición de herramientas del ADK a través de un servidor MCP: Crea un servidor MCP que integre las herramientas del ADK y las ponga a disposición de cualquier cliente MCP.

Objetivos

En este lab, aprenderás a realizar las siguientes tareas:

• Usar un agente del ADK como cliente MCP para interactuar con herramientas de servidores MCP existentes
• Configurar e implementar tu propio servidor MCP para exponer las herramientas del ADK a otros clientes
• Conectar agentes del ADK con herramientas externas a través de una comunicación estandarizada del MCP
• Habilitar una interacción fluida entre los LLM y las herramientas con el Protocolo de contexto del modelo

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lea estas instrucciones. Los labs tienen un tiempo límite; no puede ponerlos en pausa. El cronómetro, que comienza a funcionar cuando hace clic en Comenzar lab, indica por cuánto tiempo estarán los recursos en la nube a su disposición.

Este lab práctico de Qwiklabs le permitirá llevar a cabo las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, recibe nuevas credenciales temporales que utilizará para acceder a Google Cloud Platform durante el transcurso del lab.

Lo que necesita

Para completar este lab, necesitará lo siguiente:

• Acceso a un navegador de Internet estándar. Se recomienda el navegador Chrome
• Tiempo para completar el lab

Nota: Si ya tiene un proyecto o una cuenta personal de GCP, no los use para este lab.

Cómo iniciar tu lab y acceder a la consola de Google Cloud

1. Haz clic en el botón Comenzar lab. Si debes pagar por el lab, se abrirá un diálogo para que selecciones la forma de pago. A la izquierda, se encuentra el panel Detalles del lab, que tiene estos elementos:

   • El botón para abrir la consola de Google Cloud
   • El tiempo restante
   • Las credenciales temporales que debes usar para el lab
   • Otra información para completar el lab, si es necesaria

2. Haz clic en Abrir la consola de Google Cloud (o haz clic con el botón derecho y selecciona Abrir el vínculo en una ventana de incógnito si ejecutas el navegador Chrome).

   El lab inicia recursos y abre otra pestaña en la que se muestra la página de acceso.

   Sugerencia: Ordena las pestañas en ventanas separadas, una junto a la otra.

   Nota: Si ves el diálogo Elegir una cuenta, haz clic en Usar otra cuenta.

3. De ser necesario, copia el nombre de usuario a continuación y pégalo en el diálogo Acceder.

   {{{user_0.username | "Username"}}}

   También puedes encontrar el nombre de usuario en el panel Detalles del lab.

4. Haz clic en Siguiente.

5. Copia la contraseña que aparece a continuación y pégala en el diálogo Te damos la bienvenida.

   {{{user_0.password | "Password"}}}

   También puedes encontrar la contraseña en el panel Detalles del lab.

6. Haz clic en Siguiente.

   Importante: Debes usar las credenciales que te proporciona el lab. No uses las credenciales de tu cuenta de Google Cloud. Nota: Usar tu propia cuenta de Google Cloud para este lab podría generar cargos adicionales.

7. Haz clic para avanzar por las páginas siguientes:

   • Acepta los Términos y Condiciones.
   • No agregues opciones de recuperación o autenticación de dos factores (esta es una cuenta temporal).
   • No te registres para obtener pruebas gratuitas.

Después de un momento, se abrirá la consola de Google Cloud en esta pestaña.

Nota: Para acceder a los productos y servicios de Google Cloud, haz clic en el menú de navegación o escribe el nombre del servicio o producto en el campo Buscar.

Tarea 1: Instala el ADK y configura tu entorno

En este entorno de lab, se habilitaron la API de Vertex AI, la API de Routes y la API de Directions.

Prepara una pestaña del Editor de Cloud Shell

1. Con la ventana de la consola de Google Cloud seleccionada, abre Cloud Shell presionando la tecla G y, luego, la tecla S. También puedes hacer clic en el botón Activar Cloud Shell () en la parte superior derecha de la consola de Cloud.

2. Haz clic en Continuar.

3. Cuando se te solicite que autorices Cloud Shell, haz clic en Autorizar.

4. En la esquina superior derecha del panel de la terminal de Cloud Shell, haz clic en el botón Abrir en una ventana nueva .

5. En la terminal de Cloud Shell, ingresa lo siguiente para abrir el Editor de Cloud Shell en tu directorio principal:

   cloudshell workspace ~

6. Cierra cualquier instructivo adicional o panel de Gemini que aparezca en el lado derecho de la pantalla para que el editor de código tenga más espacio en la ventana.

7. Durante el resto de este lab, puedes trabajar en esta ventana como tu IDE con la terminal y el Editor de Cloud Shell.

Descarga e instala el ADK y las muestras de código para este lab

1. Instala el ADK ejecutando el siguiente comando en la terminal de Cloud Shell.

   Nota: Debes especificar la versión para asegurarte de que la versión del ADK que instales corresponda a la utilizada en este lab. Puedes ver el número de versión más reciente y sus notas en el repo adk-python. sudo python3 -m pip install google-adk==1.5.0

2. Pega los siguientes comandos en la terminal de Cloud Shell para copiar un archivo de un bucket de Cloud Storage y descomprimirlo, creando así un directorio de proyecto con el código para este lab:

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. Instala los requisitos adicionales del lab con este comando:

   python3 -m pip install -r adk_mcp_tools/requirements.txt

Haz clic en Revisar mi progreso para verificar el objetivo. Instalar el ADK y configurar el entorno

Tarea 2: Usa el servidor MCP de Google Maps con agentes del ADK (el ADK como cliente MCP) en adk web

En esta sección, se demuestra cómo integrar herramientas de un servidor MCP externo de Google Maps en tus agentes del ADK. Este es el patrón de integración más común cuando tu agente del ADK necesita utilizar capacidades ofrecidas por un servicio existente que expone una interfaz MCP. Verás cómo la clase MCPToolset se puede agregar directamente a la lista tools de tu agente, lo que permite conectarse sin problemas a un servidor MCP, descubrir sus herramientas y ponerlas a disposición de tu agente. Estos ejemplos se enfocan principalmente en las interacciones dentro del entorno de desarrollo adk web.

MCPToolset

La clase MCPToolset es el mecanismo principal del ADK para integrar las herramientas de un servidor MCP. Cuando incluyes una instancia de MCPToolset en la lista tools de tu agente, esta se encarga automáticamente de interactuar con el servidor MCP especificado. Aquí te mostramos cómo funciona:

• Administración de conexiones: En la inicialización, MCPToolset establece y administra la conexión al servidor MCP. Puede ser un proceso de servidor local (con StdioServerParameters para la comunicación a través de entrada/salida estándar) o de servidor remoto (con SseServerParams para eventos enviados por el servidor). El conjunto de herramientas también gestiona el cierre ordenado de esta conexión cuando el agente o la aplicación terminan.
• Descubrimiento y adaptación de herramientas: Una vez conectada, MCPToolset consulta al servidor MCP para obtener sus herramientas disponibles (a través del método list_tools del MCP). Luego, convierte los esquemas de estas herramientas del MCP identificadas en instancias BaseTool compatibles con el ADK.
• Exposición al agente: Estas herramientas adaptadas quedan a disposición de tu LlmAgent como si fueran herramientas nativas del ADK.
• Actuar como proxy para las llamadas a herramientas: Cuando tu LlmAgent decide usar una de estas herramientas, MCPToolset reenvía de manera transparente la llamada (mediante el método call_tool de MCP) al servidor MCP, pasa los argumentos necesarios y devuelve la respuesta del servidor al agente.
• Filtrado (opcional): Al crear una instancia MCPToolset, puedes usar el parámetro tool_filter para seleccionar un subconjunto específico de herramientas del servidor MCP, en lugar de exponerlas todas a tu agente.

Obtén una clave de API y habilita las APIs

En esta subsección, generarás una nueva clave de API llamada GOOGLE_MAPS_API_KEY.

1. Abre la pestaña del navegador que muestra la consola de Google Cloud (no el Editor de Cloud Shell).

2. Puedes cerrar el panel de la terminal de Cloud Shell en esta pestaña del navegador para tener más espacio en la consola.

3. Busca Credenciales en la barra de búsqueda de la parte superior de la página. Selecciona el resultado.

4. En la página Credenciales, haz clic en + Crear credenciales en la parte superior de la página y, luego, selecciona Clave de API.

   En el diálogo Se creó la clave de API, se mostrará tu nueva clave de API. Asegúrate de guardarla de forma local para usarla más adelante en el lab.

5. Haz clic en Cerrar en el cuadro de diálogo.

   Tu clave recién creada se llamará Clave de API 1 de forma predeterminada. Selecciona la clave, cámbiale el nombre a GOOGLE_MAPS_API_KEY y haz clic en Guardar.

   

Define tu agente con un MCPToolset para Google Maps

En esta subsección, configurarás tu agente de modo que use MCPToolset para Google Maps, lo que le permitirá proporcionar instrucciones sobre cómo llegar a un lugar y datos basados en la ubicación de manera fluida.

1. En el panel del explorador de archivos del Editor de Cloud Shell, busca la carpeta adk_mcp_tools. Haz clic en ella para ver su contenido.

2. Navega al directorio adk_mcp_tools/google_maps_mcp_agent.

3. Pega el siguiente comando en un archivo de texto sin formato y, luego, actualiza el valor YOUR_ACTUAL_API_KEY con la clave de la API de Google Maps que generaste y guardaste en un paso anterior:

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. Copia y pega el comando actualizado en la terminal de Cloud Shell para ejecutarlo y escribir un archivo .env que proporcione los detalles de autenticación para este directorio de agente.

5. Copia el archivo .env al otro directorio de agente que usarás en este lab con el siguiente comando:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. Luego, agrega el siguiente código donde se indica en el archivo agent.py para agregar la herramienta de Google Maps a tu agente. Esto permitirá que tu agente use MCPToolset para Google Maps y proporcione instrucciones sobre cómo llegar o información basada en la ubicación.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. Desde el directorio del proyecto adk_mcp_tools, inicia la IU de desarrollo del Kit de desarrollo de agentes con el siguiente comando:

   adk web

   Resultado:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. Para ver la interfaz web en una pestaña nueva, haz clic en el vínculo http://127.0.0.1:8000 en el resultado de la terminal.

9. Se abrirá una nueva pestaña del navegador con la IU de desarrollo del ADK. En el menú desplegable Seleccionar un agente de la izquierda, selecciona google_maps_mcp_agent.

10. Inicia una conversación con el agente y ejecuta las siguientes instrucciones:

    Obtén instrucciones sobre cómo llegar desde Googleplex hasta SFO. Nota: Si tu llamada a la API agota el tiempo de espera la primera vez que la usas, haz clic en + Nueva sesión en la parte superior derecha de la IU de desarrollo del ADK y vuelve a intentarlo. ¿Cuál es la ruta de París, Francia a Berlín, Alemania?

    Resultado:

    

11. Haz clic en el ícono del agente junto a la burbuja de chat del agente con un rayo, que indica una llamada a la función. Se abrirá el inspector de eventos para este evento:

    

12. Observa que el gráfico del agente indica varias herramientas diferentes, identificadas por el emoji de llave inglesa (🔧). Aunque solo hayas importado un MCPToolset, ese conjunto de herramientas incluía las diferentes herramientas que ves aquí, como maps_place_details y maps_directions.

    

13. En la pestaña Solicitud, puedes ver la estructura de la solicitud. Puedes usar las flechas en la parte superior del inspector de eventos para explorar los pensamientos, las llamadas a funciones y las respuestas del agente.

14. Cuando termines de hacerle preguntas a este agente, cierra la pestaña del navegador de la IU para desarrolladores.

15. Vuelve al panel de la terminal de Cloud Shell y presiona Ctrl + C para detener el servidor.

Haz clic en Revisar mi progreso para verificar el objetivo. Crear una clave de API y, luego, implementar el agente del ADK

Tarea 3: Crea un servidor MCP con herramientas del ADK (un servidor MCP que expone el ADK)

En esta sección, aprenderás a exponer la herramienta load_web_page del ADK a través de un servidor MCP creado de forma personalizada. Este patrón te permite encapsular las herramientas del ADK existentes y hacerlas accesibles a cualquier aplicación cliente MCP estándar.

Crea la secuencia de comandos del servidor MCP y aplica la lógica del servidor

1. Vuelve a la pestaña del Editor de Cloud Shell y selecciona el directorio adk_mcp_tools/adk_mcp_server.

2. Se preparó un archivo de Python llamado adk_server.py y se agregaron comentarios para ti. Dedica un momento a revisar ese archivo y lee los comentarios para entender cómo el código encapsula una herramienta y la expone como un servidor MCP. Observa cómo permite a los clientes MCP enumerar las herramientas disponibles, así como invocar la herramienta del ADK de forma asíncrona, manejando solicitudes y respuestas en un formato compatible con el MCP.

Prueba el servidor MCP personalizado con un agente del ADK

3. Haz clic en el archivo agent.py del directorio adk_mcp_server.

4. Actualiza la ruta a tu archivo adk_server.py.

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

5. A continuación, agrega el siguiente código donde se indica en el archivo agent.py para agregar MCPToolset a tu agente. Un agente del ADK actúa como cliente del servidor MCP. Este agente del ADK usará MCPToolset para conectarse a tu secuencia de comandos adk_server.py.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Comando para ejecutar la secuencia de comandos del servidor MCP args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # El argumento es la ruta de acceso a la secuencia de comandos ), timeout=15, ), tool_filter=['load_web_page'] # Opcional: Asegúrate de que solo se carguen herramientas específicas ) ],

6. Para ejecutar el servidor MCP, inicia la secuencia de comandos adk_server.py ejecutando el siguiente comando en la terminal de Cloud Shell:

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Resultado:

   

7. Para abrir una nueva pestaña de la terminal de Cloud Shell, haz clic en el botón en la parte superior de la ventana de terminal de Cloud Shell.

8. En la terminal de Cloud Shell, desde el directorio del proyecto adk_mcp_tools, inicia la IU de desarrollo del Kit de desarrollo de agentes con el siguiente comando:

   cd ~/adk_mcp_tools adk web

9. Para ver la interfaz web en una pestaña nueva, haz clic en el vínculo http://127.0.0.1:8000 del resultado de la terminal.

10. En el menú desplegable Seleccionar un agente de la izquierda, selecciona adk_mcp_server.

11. Hazle la siguiente consulta al agente:

    Carga el contenido de https://example.com.

    Resultado:

    

    Esto es lo que sucede:

    • El agente del ADK (web_reader_mcp_client_agent) usa MCPToolset para conectarse a tu adk_server.py.
    • El servidor MCP recibirá la solicitud call_tool, ejecutará la herramienta load_web_page del ADK y devolverá el resultado.
    • Luego, el agente del ADK retransmitirá esta información. Debes ver los registros de la IU web de ADK (y su terminal) y los de tu terminal adk_server.py en la pestaña de la terminal de Cloud Shell donde se está ejecutando.

    Esto demuestra que las herramientas del ADK se pueden encapsular en un servidor MCP, lo que las hace accesibles a una amplia gama de clientes compatibles con el MCP, incluidos los agentes del ADK.

¡Felicitaciones!

Al final de este lab, aprendiste a integrar herramientas externas del Protocolo de contexto del modelo (MCP) en tus agentes del ADK con la clase MCPToolset. Descubriste cómo conectarte a un servidor MCP, usar sus herramientas en tu agente y exponer herramientas del ADK como load_web_page a través de un servidor MCP personalizado. Estas habilidades te permiten ampliar tus agentes del ADK con servicios externos potentes, lo que mejora tus flujos de trabajo de desarrollo web.

Última actualización del manual: 6 de octubre de 2025

Prueba más reciente del lab: 6 de octubre de 2025

Copyright 2020 Google LLC. All rights reserved. Google y el logotipo de Google son marcas de Google LLC. Los demás nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que estén asociados.