Hướng dẫn Google ADK: Xây dựng tác nhân Logistics dùng máy chủ MCP

Trở ngại lớn nhất khi xây dựng các tác nhân AI tinh vi ngày nay không phải là mô hình, mà là tích hợp. Nếu bạn muốn một tác nhân truy cập mười công cụ doanh nghiệp khác nhau, thường bạn sẽ phải viết mười trình bao API khác nhau. Theo kinh nghiệm của tôi, điều này gây mệt mỏi vì trình bao và kéo theo gánh nặng bảo trì lớn. Mỗi lần API thay đổi, tác nhân của bạn lại hỏng.

Giải pháp nằm ở sự kết hợp giữa Google Agent Development Kit (ADK) và Model Context Protocol (MCP). Nếu ví AI như một người lao động, ADK là "bộ não" (điều phối logic và bộ nhớ), còn MCP là "đôi tay" (cách thức tiêu chuẩn để nhặt lên và dùng bất kỳ công cụ nào).

Trong hướng dẫn này, chúng ta sẽ xây dựng một tác nhân phục hồi logistics thực tế bằng ADK. Tác nhân sẽ:

1. Truy vấn BigQuery để lấy các đơn hàng bị trễ có mức ưu tiên cao. 
2. Tính quãng đường lái xe thực tế từ kho đến khách hàng bằng máy chủ Google Maps MCP. 
3. Đề xuất hành động khắc phục, chẳng hạn nâng cấp lên vận chuyển đường hàng không cho các lô hàng đường dài.

Tất cả diễn ra mà không cần viết một dòng mã API tùy chỉnh nào. Tác nhân tự động phát hiện và sử dụng công cụ.

Mới dùng Google Cloud? Tôi khuyến nghị bắt đầu với khóa học miễn phí Introduction to GCP để nắm về thanh toán, dự án và các dịch vụ cơ bản.

Google ADK là gì?

Google Agent Development Kit (ADK) là khung mã nguồn mở, ưu tiên code của Google dành cho xây dựng, kiểm thử và triển khai tác nhân AI. Trong khi các khung như LangChain tập trung vào chuỗi, ADK được xây cho thực thi. Nó cung cấp cấu trúc tiêu chuẩn về cách tác nhân suy nghĩ, dùng bộ công cụ và chạy trong môi trường sản xuất.

Các khái niệm chính:

• Tác nhân (Agents): Thực thể cốt lõi được xác định bởi mô hình (ví dụ: Gemini 2.0 Flash) và tập chỉ dẫn cụ thể.
• Bộ công cụ (Toolsets): Tập hợp năng lực. Thay vì định nghĩa công cụ thủ công, chúng ta trỏ ADK tới một máy chủ MCP, và nó tự động "học" các công cụ.
• Runner: Động cơ thực thi quản lý trạng thái hội thoại và vòng lặp "suy nghĩ - hành động - quan sát" lặp lại.

Cách tiếp cận ưu tiên code cho phép chúng ta dùng kiểm soát phiên bản, kiểm thử và CI/CD y hệt như phần mềm thông thường. Nó cũng tích hợp sâu với Google, nghĩa là các máy chủ MCP được quản lý hầu như không cần triển khai cho BigQuery hoặc Maps.

Để so sánh “bộ ba lớn” nhà cung cấp đám mây và dịch vụ của họ, hãy xem hướng dẫn AWS so với Azure so với Google Cloud.

Kiến trúc tích hợp và luồng logic của Google ADK

Tác nhân phục hồi logistics của chúng ta tuân theo một lộ trình lập luận rõ ràng để giải quyết vấn đề kinh doanh. Hiểu luồng này sẽ hữu ích khi bạn bắt đầu viết chỉ dẫn prompt sau này.

Vòng lặp lập luận gồm các bước:

1. Tác nhân gọi BigQuery MCP để tìm các hàng có status='Delayed' và priority='High'. 

2. Với mỗi đơn hàng trả về, tác nhân trích xuất địa chỉ kho và khách hàng. 

3. Tác nhân gọi Google Maps MCP cho từng đơn hàng để tính quãng đường lái xe. 

4. Tác nhân áp dụng logic kinh doanh (ví dụ: khoảng cách trên 500 dặm thì dùng vận chuyển hàng không) và trình bày bảng khuyến nghị bằng markdown.

Thiết lập các máy chủ MCP

Trước khi bắt đầu viết mã, chúng ta cần chuẩn bị hạ tầng đám mây bên dưới và sẵn sàng các máy chủ MCP. Theo kinh nghiệm của tôi, thiết lập quyền IAM đúng là phần quan trọng nhất giai đoạn này.

Bước 1: Khởi tạo Google Cloud CLI 

Hãy đảm bảo bạn đã cài Google Cloud CLI. Bắt đầu bằng cách mở terminal và chạy lệnh sau để liên kết môi trường cục bộ với tài khoản Google của bạn:

gcloud init

Sau khi chạy, một cửa sổ trình duyệt sẽ tự động mở. Bạn sẽ được nhắc đăng nhập bằng tài khoản Google. Sau khi đăng nhập, nhấp Allow để cấp quyền cho CLI quản lý tài nguyên của bạn. 

Quay lại terminal, nhắc lệnh sẽ yêu cầu bạn chọn dự án mặc định. Nếu bạn đã tạo rồi, hãy chọn ID dự án, hoặc tạo dự án mới ngay trong terminal.

Bước 2: Thiết lập thanh toán

Để sử dụng các dịch vụ API, bạn cần thiết lập thanh toán. Dù vậy, Google Cloud cung cấp 300 đô tín dụng miễn phí trong 90 ngày để thử các dịch vụ như Compute, GKE và Maps, và khoản tín dụng này thừa cho ví dụ trong hướng dẫn này. Bạn chỉ bị tính phí nếu bật trả theo mức dùng hoặc trả trước. Để thiết lập thanh toán:

1. Vào trang thanh toán Google Console và đăng nhập bằng tài khoản bạn dùng cho gcloud.

2. Tạo tài khoản thanh toán nếu bạn chưa có (cần thêm phương thức thanh toán, nhưng tín dụng miễn phí sẽ được áp dụng trước).

3. Liên kết tài khoản thanh toán với dự án của bạn: Billing → Link a project → chọn dự án của bạn, hoặc chạy:

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

Bước 3: Bật các API lõi và dịch vụ MCP

Tiếp theo, chúng ta cần bật các API sản phẩm chính. Chúng cho phép tác nhân truy cập các dịch vụ dữ liệu gốc như BigQuery và Maps.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.com

Giờ chúng ta phải bật Managed MCP Endpoints. Hãy coi chúng như các giao diện dịch thuật nằm trên các API thông thường. 

Trước hết, hãy lưu ID dự án và email tài khoản của bạn vào biến môi trường. Việc này giúp tránh phải gõ thủ công cho từng lệnh sau:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

Với các biến đã đặt, chạy các lệnh sau để bật tính năng MCP beta cho dự án của bạn. Các lệnh này yêu cầu Google chuẩn bị các endpoint MCP từ xa để tác nhân của bạn gọi:

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_ID

Bước 3: Cấu hình IAM và khóa Maps 

MCP dùng mô hình bảo mật "hai lớp". Bạn cần quyền để nói chuyện với chính máy chủ MCP và quyền riêng để truy cập dữ liệu thực (như các hàng trong bảng). Bạn có thể làm qua gcloud CLI hoặc giao diện Google Cloud Console.

Tùy chọn IAM A: Dùng gcloud CLI 

Để cấp quyền cho tài khoản của bạn sử dụng MCP và tương tác với BigQuery, chạy ba lệnh này:

# Quyền giao tiếp với MCP Translator
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Quyền chạy job BigQuery và xem dữ liệu
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"

Tùy chọn IAM B: Dùng Google Cloud Console (UI)

Nếu bạn thích giao diện trực quan, hãy làm theo các bước sau trên trình duyệt:

1. Vào trang IAM & Admin trong Google Cloud Console.
2. Tìm địa chỉ email của bạn trong danh sách và bấm biểu tượng Edit Member (bút chì).
3. Nhấp Add Another Role và tìm MCP Tool User.
4. Lặp lại để thêm BigQuery Data Viewer và BigQuery Job User.
5. Nhấp Save.

Tạo khóa API cho Maps

Cuối cùng, tạo khóa API cho Maps. Khác với BigQuery dùng thông tin đăng nhập của bạn, máy chủ Maps MCP dùng khóa này để tính phí và theo dõi hạn ngạch: 

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"

Bước 4: Xác thực máy chủ cục bộ bằng MCP Inspector

Trước khi viết Python, chúng ta nên kiểm tra nhanh bằng MCP Inspector. Chúng ta sẽ dùng lệnh npx, một công cụ đi kèm Node.js. 

Mục đích là cho phép bạn chạy một gói (như inspector) ngay lập tức mà không cần cài vĩnh viễn trên máy. Chạy lệnh này trong terminal:

npx @modelcontextprotocol/inspector

Điều này sẽ mở giao diện web trong trình duyệt (thường tại http://localhost:3000). Tôi đã chọn các tùy chọn cụ thể dưới đây để đảm bảo chúng ta đang kiểm thử phiên bản Remote Managed của máy chủ Google, không phải bản mock cục bộ:

1. Transport type: Streamable HTTP. Chúng ta chọn vì đây là giao thức tiêu chuẩn sản xuất Google dùng cho máy chủ đám mây được quản lý.

2. URL: Nhập https://mapstools.googleapis.com/mcp. Đây là "cửa trước" trực tiếp tới Maps MCP của Google.

3. Connection Type: via Proxy. Lựa chọn này rất quan trọng. Bằng cách chọn "Proxy", inspector sẽ dùng đăng nhập gcloud cục bộ của bạn để xử lý tự động mọi thủ tục bảo mật phức tạp.

4. Custom Headers: Thêm X-Goog-Api-Key và dán khóa của bạn từ Bước 3.

5. Bấm Connect.

Giờ bạn sẽ thấy trạng thái Connected màu xanh lá. Nhấp nút List Tools để xem danh sách mọi khả năng máy chủ cung cấp. Nếu bạn thấy compute_routes trong danh sách, hạ tầng của bạn đã được cấu hình hoàn hảo.

Để hiểu sâu hơn cách dùng BigQuery, Maps và các dịch vụ Google khác cho tác nhân của bạn, hãy xem hướng dẫn về Google MCP Servers.

Xây dựng tác nhân máy chủ MCP với Google ADK

Khi hạ tầng đã sẵn sàng, chúng ta chuyển sang môi trường phát triển cục bộ. Bắt đầu bằng cách tổ chức tệp dự án.

Bước 1: Thiết lập cấu trúc dự án và phụ thuộc

Để bắt đầu, hãy tạo một thư mục cho dự án và thiết lập môi trường ảo.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activate

Lệnh cuối dành cho người dùng macOS hoặc Linux; nếu bạn dùng Windows, hãy dùng .venv\Scripts\activate.

Tiếp theo, bạn có thể cài gói google-adk cùng các thư viện hỗ trợ.

pip install google-adk google-generativeai python-dotenv httpx  google-auth

Một việc nữa bạn cần làm là tạo tệp .env trong thư mục gốc để lưu PROJECT_ID và MAPS_API_KEY bạn đã tạo ở bước trước.

Bước 2: Cấu hình bộ công cụ MCP

Trong script tên tools.py, chúng ta không viết mã để "lấy dữ liệu". Thay vào đó, chúng ta viết mã để kết nối tới một máy chủ biết cách lấy dữ liệu. 

Tôi nhận thấy việc tách công cụ khỏi logic giúp dự án dễ gỡ lỗi hơn nhiều. Bởi vì chúng ta nói chuyện với các endpoint Google Cloud từ xa, chúng ta dùng StreamableHTTPConnectionParams để xử lý header xác thực.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
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())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )

Bước 3: Xác định nhiệm vụ của tác nhân

Giờ chúng ta xây "bộ não". Theo kinh nghiệm của tôi, dùng một trong các mô hình Gemini Flash là lựa chọn tốt nhất vì chúng cực nhanh trong việc gọi công cụ. 

Chúng ta cung cấp quy trình vận hành chuẩn cho tác nhân qua phần chỉ dẫn trong tệp agent.py. Lưu ý cách chúng ta dùng pipeline bốn bước rõ ràng để tránh tác nhân bị rối.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# We're giving the agent a very structured 'Instruction' set. 
# Think of this as the SOP (Standard Operating Procedure) for your agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # We simply drop our toolsets here. 
    # ADK handles the complexity of deciding which tool to call when.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)

Bước 4: Chạy vòng lặp của tác nhân 

Để chạy tác nhân, chúng ta dùng runner. Thành phần này theo dõi trạng thái hội thoại để tác nhân biết mình đã làm gì và cần làm gì tiếp theo.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # The Runner acts as the host for our agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Wrap the user input in the standard GenAI Content format
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # We use run_async to stream the 'events' (Thoughts and Tool Calls)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # We only want to print the text part of the response to the console
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)

Chuyện gì diễn ra phía sau hậu trường?

Khi bạn gọi runner.run_async, ADK bắt đầu một vòng lặp lặp lại:

1. Gemini nghĩ: "Tôi cần xem các đơn hàng bị trễ trước."

2. ADK hành động: Gọi công cụ execute_sql từ bộ công cụ BigQuery MCP của bạn.

3. Quan sát: Công cụ trả về dữ liệu đơn hàng.

4. Gemini nghĩ: "Giờ tôi cần khoảng cách cho hai đơn hàng này."

5. ADK hành động: Gọi công cụ Maps MCP hai lần.

6. Phản hồi cuối: Gemini thấy toàn bộ dữ liệu, áp dụng logic "500 dặm" của bạn và định dạng bảng.

Kiểm thử tác nhân Google ADK trong web console

Dù terminal rất hữu ích cho log, ADK có sẵn web console trực quan hóa quá trình lập luận nội bộ của tác nhân. Tôi thấy đây là công cụ hữu ích nhất để gỡ lỗi.

Khởi chạy giao diện bằng cách chạy adk web. Khi máy chủ khởi động, mở trình duyệt tới http://127.0.0.1:8000. Bạn sẽ thấy giao diện trò chuyện gọn gàng nơi bạn có thể gửi lệnh: "Identify high-priority delayed orders and suggest recovery shipping methods."

Phân tích vết thực thi

Bảng điều khiển ADK cung cấp "vết" minh bạch về cách chính xác tác nhân tương tác với hạ tầng đám mây của bạn.

Hãy phân tích từng bước:

1. Bắt tay công cụ: Lưu ý các biểu tượng execute_sql và compute_routes. Trong vết, tia sét biểu thị một lần gọi công cụ. Tác nhân không chỉ đoán; nó đã thực sự kết nối tới máy chủ BigQuery MCP để chạy một truy vấn SQL cụ thể trên bảng đơn hàng của bạn.

2. Logic tuần tự: Vết cho thấy trình tự thao tác rõ ràng. Đầu tiên, nó lấy dữ liệu qua BigQuery (dấu kiểm đầu tiên). Khi đã có địa chỉ kho và khách hàng, bạn sẽ thấy nhiều lần gọi compute_routes. Tác nhân đang "lặp" thông minh qua các đơn hàng bị trễ để lấy dữ liệu khoảng cách thực từ máy chủ Maps MCP.

3. Tổng hợp cuối: Phần cuối của vết hiển thị phản hồi cuối cùng.

Xem dữ liệu:

• ORD-101: Khoảng cách 380 dặm.
• ORD-103: Khoảng cách 352 dặm.

Vì chúng ta đã đưa cho tác nhân logic: "Nếu khoảng cách > 500 dặm, đề xuất Air Shipping, ngược lại Regional Express Ground," tác nhân đã áp dụng đúng quy tắc kinh doanh này cho cả hai đơn và định dạng chúng thành một bảng Markdown đẹp.

Kết luận

Chúng ta vừa xây dựng một tác nhân Logistics hoạt động được mà không viết một dòng mã API tùy chỉnh nào cho BigQuery hay Google Maps. Bằng cách dùng ADK và MCP, chúng ta đã tạo nên kiến trúc mô-đun, an toàn và ưu tiên nhà phát triển.

Tương lai của AI không chỉ là chatbot biết nói, mà là các tác nhân biết hành động. Với những công cụ này, chúng ta đang tiến gần hơn tới thực tế đó.

Hướng dẫn này có thể là điểm khởi đầu tuyệt vời cho việc bạn thử nghiệm với Google ADK và máy chủ MCP: 

• Thay BigQuery bằng một tập dữ liệu khác (hoặc thậm chí một máy chủ MCP SQLite cục bộ) để thấy việc đổi nguồn dữ liệu dễ thế nào.
• Thay Maps bằng máy chủ MCP khác (ví dụ GKE để kiểm tra sức khỏe cụm) để chứng minh tính cắm-là-chạy.
• Thêm nhiều logic kinh doanh trong prompt (so sánh chi phí, soạn email) và thử trực tiếp trong ADK web UI.

Nếu bạn muốn tìm hiểu thêm về điều phối tác nhân, tôi rất khuyến nghị đăng ký lộ trình nghề nghiệp Associate AI Engineer for Developers.