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 Kit de desarrollo de agentes (ADK) con las herramientas que proporcionan los servidores MCP existentes para mejorar tus flujos de trabajo del ADK. Además, descubrirá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 MCP

Configuración y requisitos

Antes de hacer clic en el botón Comenzar lab

Lee estas instrucciones. Los labs cuentan con un temporizador que no se puede pausar. El temporizador, que comienza a funcionar cuando haces clic en Comenzar lab, indica por cuánto tiempo tendrás a tu disposición los recursos de Google Cloud.

Este lab práctico te permitirá realizar las actividades correspondientes en un entorno de nube real, no en uno de simulación o demostración. Para ello, se te proporcionan credenciales temporales nuevas que utilizarás para acceder a Google Cloud durante todo el lab.

Para completar este lab, necesitarás lo siguiente:

• Acceso a un navegador de Internet estándar. Se recomienda el navegador Chrome.

• Tiempo para completar el lab (recuerda que, una vez que comienzas un lab, no puedes pausarlo).

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. En la consola de Google Cloud, haz 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. Haz clic en el ícono de Abrir editor () en la parte superior del panel para ver los archivos.
6. En la parte superior del menú de navegación de la izquierda, haz clic en el ícono de Explorer () para abrir el explorador de archivos.
7. Haz clic en el botón Open folder.
8. En el diálogo Open Folder que se abre, haz clic en OK para seleccionar la carpeta principal de tu cuenta de estudiante de Qwiklabs.
9. 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.
10. Durante el resto del 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

En esta sección, ejecutarás los siguientes comandos en la terminal de Cloud Shell.

1. Ejecuta el siguiente comando en la terminal de Cloud Shell para copiar el directorio del proyecto desde Cloud Storage:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. Ejecuta los siguientes comandos para instalar el Kit de desarrollo de agentes (ADK) y otras dependencias necesarias para ejecutar las aplicaciones de ejemplo:

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.22.1 -r adk_mcp_tools/requirements.txt

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

Tarea 2: Usa el servidor MCP de Google Maps con agentes del ADK (el ADK como cliente MCP) en la IU para desarrolladores del ADK

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): Cuando creas 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

El servidor MCP de Google Maps requiere una clave de API para comunicarse con los servicios de Google Maps. En este paso, generarás una nueva clave de API llamada GOOGLE_MAPS_API_KEY y la restringirás a las APIs de Directions y Routes por motivos de seguridad.

1. Ve a la pestaña del navegador de la consola de Google Cloud (no al 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.

5. En Nombre, escribe GOOGLE_MAPS_API_KEY.

6. En APIs a las que se puede acceder con esta clave, selecciona las siguientes APIs:

   • API de Directions
   • API de Routes

7. Haz clic en Crear.

   El diálogo Se creó la clave de API mostrará la clave de API que acabas de crear. Asegúrate de copiar y guardar esta clave de forma local para usarla más adelante en el lab.

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

   

Define tu agente con un MCPToolset para Google Maps

Ahora configurarás tu agente para que use las herramientas de Google Maps. Si agregas MCPToolset, permites que el agente descubra y llame de forma dinámica a las APIs de Google Maps cuando sea necesario.

1. Pega el siguiente comando en un documento de texto sin formato en tu computadora 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=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. Copia y pega el comando actualizado en la terminal de Cloud Shell y ejecútalo para escribir un archivo .env, que proporciona los detalles de autenticación para este directorio de agente.

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

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

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

5. Navega al directorio adk_mcp_tools/google_maps_mcp_agent.

6. Abre agent.py y agrega el siguiente código después del comentario ## Add the MCPToolset (en una línea nueva después de la línea 53) para configurar la conexión del agente al servidor MCP de Google Maps:

   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. Guarda el archivo.

8. 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 --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   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)

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

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

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

    

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

    

    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.

    

    En la pestaña Evento, 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.

13. Cuando termines de hacerle preguntas a este agente, cierra la pestaña del navegador de la IU de desarrollo.

14. 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 la clave de API e 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 personalizado. 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 al Editor de Cloud Shell y selecciona el directorio adk_mcp_tools/adk_mcp_server.

2. Abre el archivo de Python llamado adk_server.py. Este archivo contiene la lógica de tu servidor MCP personalizado. Revisa el código para comprender cómo encapsula y expone la herramienta del ADK.

   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

1. Abre agent.py en el directorio adk_mcp_server.

2. En la línea 31, actualiza el valor de PATH_TO_YOUR_MCP_SERVER_SCRIPT con la siguiente ruta de acceso para que el agente pueda conectarse a tu secuencia de comandos del servidor personalizado:

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

3. A continuación, agrega el siguiente código en la línea 55, es decir, después de donde dice ## Add the MCPToolset below: 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 usa MCPToolset para conectarse a tu secuencia de comandos adk_server.py.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

4. Guarda el archivo.

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

   

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

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

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents Nota: Se agregó `PATH` a este comando para restablecerlo, ya que la nueva terminal de Cloud Shell puede mostrar un error si ejecutaste el resto del comando sin él. Por lo general, se trataría de un error de "no se encontró adk web".

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. En el menú desplegable Seleccionar un agente de la izquierda, selecciona adk_mcp_server.

10. Dale la siguiente instrucción al agente:

    Carga el contenido de http://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 recibe la solicitud call_tool, ejecuta la herramienta load_web_page del ADK y devuelve el resultado.
    • Luego, el agente del ADK retransmite 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!

En este lab, aprendiste a integrar herramientas externas del Protocolo de contexto del modelo (MCP) en tus agentes del Kit de desarrollo de agentes (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: 21 de abril de 2026

Prueba más reciente del lab: 21 de abril de 2026

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