Tạo một Tác nhân ADK Thông tin tình báo về vị trí bằng máy chủ MCP cho BigQuery và Google Maps

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ xây dựng một tác nhân bằng ADK dựa trên Gemini 3.1 Pro. Tác nhân này sẽ được trang bị các công cụ từ hai máy chủ MCP từ xa (do Google lưu trữ) để truy cập an toàn vào BigQuery cho dữ liệu nhân khẩu học, giá cả và doanh số, cũng như Google Maps để phân tích và xác thực vị trí thực tế.

Tác nhân này điều phối các yêu cầu giữa người dùng và các dịch vụ của Google Cloud để giải quyết các vấn đề kinh doanh liên quan đến tập dữ liệu giả định về tiệm bánh.

Bạn sẽ thực hiện

Thiết lập dữ liệu: Tạo tập dữ liệu cơ bản về tiệm bánh trong BigQuery.
Phát triển Tác nhân: Xây dựng một tác nhân thông minh bằng Bộ công cụ phát triển tác nhân (ADK).
Tích hợp công cụ: Trang bị cho tác nhân các chức năng của BigQuery và Maps thông qua máy chủ MCP.
Phân tích thị trường: Tương tác với tác nhân để đánh giá xu hướng thị trường và mức độ bão hoà.

Bạn cần có

Một trình duyệt web như Chrome
Một dự án Google Cloud đã bật tính năng thanh toán hoặc một tài khoản Gmail.

Lớp học lập trình này dành cho các nhà phát triển ở mọi cấp độ, kể cả người mới bắt đầu. Bạn sẽ sử dụng giao diện dòng lệnh trong Google Cloud Shell và mã Python để phát triển ADK. Bạn không cần phải là chuyên gia về Python, nhưng việc hiểu biết cơ bản về cách đọc mã sẽ giúp bạn hiểu các khái niệm.

2. Trước khi bắt đầu

Tạo dự án Google Cloud

Trong Bảng điều khiển Google Cloud, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên đám mây của Google Cloud.

Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên đám mây. Tìm hiểu cách kiểm tra xem tính năng thanh toán đã được bật cho một dự án hay chưa.

Bắt đầu Cloud Shell

Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết.

Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud:

Sau khi kết nối với Cloud Shell, hãy chạy lệnh này để xác minh quá trình xác thực trong Cloud Shell:

gcloud auth list

Chạy lệnh sau để xác nhận rằng dự án của bạn được định cấu hình để sử dụng với gcloud:

gcloud config get project

Xác nhận rằng dự án đúng như dự kiến, sau đó chạy lệnh bên dưới để đặt mã dự án:

export PROJECT_ID=$(gcloud config get project)

3. Nhận mã

Nhân bản kho lưu trữ

Sao chép kho lưu trữ vào môi trường Cloud Shell:

git clone https://github.com/google/mcp.git

Chuyển đến thư mục bản minh hoạ:

cd mcp/examples/launchmybakery

Xác thực

Chạy lệnh sau để xác thực bằng tài khoản Google Cloud. Bạn phải thực hiện việc này để ADK có thể truy cập vào BigQuery.

gcloud auth application-default login

Làm theo lời nhắc để hoàn tất quy trình xác thực.

4. Định cấu hình môi trường và BigQuery

Chạy tập lệnh thiết lập

Chạy tập lệnh thiết lập môi trường. Tập lệnh này bật API BigQuery và Google Maps, đồng thời tạo một tệp .env có Mã dự án và Khoá API Maps.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Chạy tập lệnh thiết lập BigQuery. Tập lệnh này tự động hoá việc tạo bộ chứa Cloud Storage, tải dữ liệu lên và cung cấp tập dữ liệu và bảng BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Sau khi tập lệnh hoàn tất, tập dữ liệu mcp_bakery sẽ được tạo và điền các bảng sau:

demographics – dữ liệu điều tra dân số và đặc điểm dân số theo mã bưu chính.
bakery_prices – giá của đối thủ cạnh tranh và thông tin chi tiết về sản phẩm cho nhiều loại bánh nướng.
sales_history_weekly – hiệu suất bán hàng hằng tuần (số lượng và doanh thu) theo cửa hàng và sản phẩm.
foot_traffic – điểm số ước tính về lượng người ghé thăm cửa hàng thực tế theo mã bưu chính và thời gian trong ngày.

Xác minh rằng tập dữ liệu và bảng được tạo bằng cách truy cập vào bảng điều khiển BigQuery trong Dự án Google Cloud:

5. Cài đặt ADK

Bây giờ, khi cơ sở hạ tầng đã sẵn sàng, hãy tạo một môi trường Python ảo và cài đặt các gói cần thiết cho ADK.

Tạo môi trường ảo:

python3 -m venv .venv

Kích hoạt môi trường ảo:

source .venv/bin/activate

Cài đặt ADK:

pip install google-adk==1.28.0

Chuyển đến thư mục tác nhân:

cd adk_agent/

6. Kiểm tra ứng dụng ADK

Nhấp vào nút Mở trình chỉnh sửa trong Cloud Shell để mở Trình chỉnh sửa Cloud Shell và xem kho lưu trữ đã sao chép trong thư mục mcp/examples/launchmybakery.

Mã tác nhân đã được cung cấp trong thư mục adk_agent/. Hãy khám phá cấu trúc giải pháp:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

Các tệp chính trong mcp_bakery_app:

agent.py: Logic cốt lõi xác định tác nhân, các công cụ và mô hình của tác nhân (Gemini 3.1 Pro Preview).
tools.py: Chứa mọi định nghĩa công cụ tuỳ chỉnh.
.env: Chứa cấu hình dự án và các bí mật (như khoá API) do tập lệnh thiết lập tạo.

1. Khởi chạy Bộ công cụ MCP:

Bây giờ, hãy mở adk_agent/mcp_bakery_app/tools.py trong Trình chỉnh sửa để hiểu cách khởi chạy các bộ công cụ MCP.

Để cho phép tác nhân của chúng ta giao tiếp với BigQuery và Google Maps, chúng ta cần định cấu hình các ứng dụng Model Context Protocol (MCP).

Mã này thiết lập các kết nối bảo mật đến các máy chủ MCP từ xa của Google bằng StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

Bộ công cụ Maps: Định cấu hình kết nối đến máy chủ MCP Maps bằng Khoá API của bạn.
Bộ công cụ BigQuery: Hàm này định cấu hình kết nối đến máy chủ MCP BigQuery. Hàm này sử dụng google.auth để tự động truy xuất thông tin xác thực trên đám mây của bạn, tạo mã thông báo OAuth Bearer và chèn mã thông báo đó vào tiêu đề Uỷ quyền.

2. Định nghĩa tác nhân:

Bây giờ, hãy mở adk_agent/mcp_bakery_app/agent.py trong Trình chỉnh sửa để xem cách xác định tác nhân.

LlmAgent được khởi chạy bằng mô hình gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

Hướng dẫn hệ thống: Tác nhân được cung cấp các hướng dẫn cụ thể để kết hợp thông tin chi tiết từ cả BigQuery (cho dữ liệu) và Maps (cho phân tích vị trí).
Công cụ: Cả maps_toolset và bigquery_toolset đều được chỉ định cho tác nhân, giúp tác nhân có quyền truy cập vào các chức năng của cả hai dịch vụ.

Tác nhân tuân thủ các hướng dẫn và công cụ được xác định trong kho lưu trữ. Bạn có thể thoải mái thay đổi hướng dẫn để xem cách thay đổi đó ảnh hưởng đến hành vi của tác nhân.

7. Trò chuyện với tác nhân!

Quay lại cửa sổ dòng lệnh trong Cloud Shell và chạy lệnh này để chuyển đến thư mục adk_agent (nếu bạn chưa thực hiện việc này):

cd adk_agent/

Chạy lệnh sau để bắt đầu giao diện web ADK. Lệnh này sẽ khởi động một máy chủ web gọn nhẹ để lưu trữ ứng dụng trò chuyện:

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Sau khi máy chủ bắt đầu, bạn sẽ thấy nội dung sau trong Cloud Shell:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Bạn có 2 cách để truy cập vào giao diện người dùng ADK:

Cách 1: Nhấp vào đường liên kết cục bộ Nhấp vào đường liên kết http://127.0.0.1:8000 xuất hiện trong cửa sổ dòng lệnh Cloud Shell.

Cách 2: Sử dụng tính năng Xem trước trên web

Nhấp vào nút Xem trước trên web ở góc trên cùng bên phải của Cloud Shell.
Chọn Thay đổi cổng.
Nhập 8000 làm số cổng rồi nhấp vào Thay đổi và xem trước.

Ảnh chụp màn hình về cách mở giao diện người dùng ADK

Tương tác với tác nhân bằng cách đặt các câu hỏi sau trong giao diện người dùng web. Bạn sẽ thấy các công cụ có liên quan đang được gọi.

Tìm khu vực xung quanh (Macro): "Tôi muốn mở một tiệm bánh ở Los Angeles. Tìm mã bưu chính có điểm số lượng người ghé thăm cửa hàng thực tế vào buổi sáng cao nhất.

Tác nhân sẽ sử dụng các công cụ như get_table_info và execute_sql để truy vấn bảng foot_traffic trong BigQuery.

Xác thực vị trí (Micro): "Bạn có thể tìm kiếm "Tiệm bánh" trong mã bưu chính đó để xem liệu khu vực đó có bị bão hoà hay không?"

Tác nhân sẽ sử dụng các công cụ search places trong bộ công cụ Maps để trả lời câu hỏi này.

Mời quý vị tham khảo! Hãy xem các câu hỏi mẫu này để thấy tác nhân ADK hoạt động:

"Tôi đang muốn mở tiệm bánh thứ tư ở Los Angeles. Tôi cần một khu vực xung quanh có hoạt động sớm. Tìm mã bưu chính có điểm số lưu lượng người ghé thăm cửa hàng thực tế vào "buổi sáng" cao nhất.
"Bạn có thể tìm kiếm "Tiệm bánh" trong mã bưu chính đó để xem liệu khu vực đó có bị bão hoà hay không? Nếu có quá nhiều tiệm bánh, hãy kiểm tra các cửa hàng "Cà phê đặc sản" để tôi có thể đặt tiệm bánh của mình gần đó nhằm thu hút lượng người ghé thăm cửa hàng thực tế.
Được rồi và tôi muốn định vị tiệm bánh này là một thương hiệu cao cấp. Giá tối đa đang được tính cho một "Ổ bánh mì chua" ở khu vực LA Metro là bao nhiêu?"
Bây giờ, tôi muốn dự báo doanh thu cho tháng 12 năm 2025. Hãy xem lịch sử bán hàng của tôi và lấy dữ liệu từ cửa hàng hoạt động tốt nhất của tôi cho "Ổ bánh mì chua". Chạy hoạt động dự báo cho tháng 12 năm 2025 để ước tính số lượng tôi sẽ bán. Sau đó, tính tổng doanh thu dự kiến bằng cách sử dụng mức giá cao cấp mà chúng ta tìm thấy (hãy sử dụng 18 USD)
Mức giá đó sẽ đủ để trả tiền thuê nhà. Cuối cùng, hãy xác minh hoạt động hậu cần. Tìm "Restaurant Depot" gần nhất với khu vực được đề xuất và đảm bảo thời gian lái xe dưới 30 phút để bổ sung hàng hằng ngày."

Khi thử nghiệm xong tác nhân, bạn có thể chấm dứt giao diện web ADK bằng cách nhấn Ctrl+C trong cửa sổ dòng lệnh Cloud Shell.

8. Dọn dẹp

Để tránh bị tính phí liên tục vào tài khoản Google Cloud, hãy xoá các tài nguyên được tạo trong lớp học lập trình này.

Chạy tập lệnh dọn dẹp. Tập lệnh này sẽ xoá tập dữ liệu BigQuery, bộ chứa Cloud Storage và các khoá API được tạo trong quá trình thiết lập.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Xin chúc mừng

Hoàn thành nhiệm vụ! Bạn đã xây dựng thành công một Tác nhân vị trí thông minh bằng Bộ công cụ phát triển tác nhân (ADK).

Bằng cách thu hẹp khoảng cách giữa dữ liệu "doanh nghiệp" của bạn trong BigQuery và ngữ cảnh vị trí thực tế từ Google Maps, bạn đã tạo ra một công cụ mạnh mẽ có khả năng suy luận phức tạp về kinh doanh – tất cả đều dựa trên Giao thức ngữ cảnh mô hình (MCP) và Gemini.

Những gì bạn đã hoàn thành:

Cơ sở hạ tầng dưới dạng mã: Bạn đã cung cấp một ngăn xếp dữ liệu bằng các công cụ Google Cloud CLI.
Tích hợp MCP: Bạn đã kết nối một tác nhân AI với hai máy chủ MCP từ xa riêng biệt (BigQuery và Maps) mà không cần viết các trình bao bọc API phức tạp.
Suy luận hợp nhất: Bạn đã xây dựng một tác nhân duy nhất có khả năng kết hợp một cách chiến lược thông tin chi tiết từ hai miền khác nhau để giải quyết một vấn đề kinh doanh.