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.0 Pro. Nhân viên này sẽ được trang bị các công cụ từ 2 máy chủ MCP từ xa (do Google lưu trữ) để truy cập an toàn vào BigQuery nhằm lấy dữ liệu về 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 đ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 của tiệm bánh giả đị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ộ phát triển tác nhân (ADK).
- Tích hợp các 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 trợ lý để đánh giá xu hướng và mức độ bão hoà của thị trường.
Bạn cần có
- Một trình duyệt web như Chrome
- Một dự án trê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 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 kiến thức 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 một dự án trên Google Cloud
- Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.
Khởi động 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 Google Cloud:
- Sau khi kết nối với Cloud Shell, hãy chạy lệnh này để xác minh thông tin xác thực của bạn 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 dự án đúng như mong đợi, sau đó chạy lệnh bên dưới để đặt mã dự án:
export PROJECT_ID=$(gcloud config get project)
3. Nhận mã
Sao chép 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 của bạn. Đây là điều kiện bắt buộc để ADK 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 cho phép BigQuery và Google Maps API, đồng thời tạo một tệp
.envcó mã dự án và khoá Maps API.
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 tạo vùng chứa Cloud Storage, tải dữ liệu lên và cung cấp tập dữ liệu cũng như 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 sẵn các bảng sau:
- nhân khẩu học – 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á và thông tin chi tiết về sản phẩm của đối thủ cạnh tranh 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 trên Google Cloud:
5. Cài đặt ADK
Giờ đây, 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
- 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ở Cloud Shell Editor và xem kho lưu trữ được sao chép trong thư mục mcp/examples/launchmybakery.
Mã nhân viên hỗ trợ đã có trong thư mục adk_agent/. Hãy cùng tìm hiểu 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.0 Pro Preview).tools.py: Chứa mọi định nghĩa về công cụ tuỳ chỉnh..env: Chứa cấu hình dự án và các mã bí mật (chẳng hạn 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 để tìm hiểu cách khởi chạy bộ công cụ MCP.
Để cho phép tác nhân của chúng tôi giao tiếp với BigQuery và Google Maps, chúng ta cần định cấu hình các ứng dụng Giao thức ngữ cảnh mô hình (MCP).
Mã này thiết lập các kết nối bảo mật đến máy chủ MCP từ xa của Google bằng cách sử dụ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 với máy chủ MCP của 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 với máy chủ MCP của BigQuery. Thư viện này sử dụng google.auth để tự động truy xuất thông tin xác thực Cloud 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 về 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-pro-preview.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3-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 cho hệ thống: Trợ lý được đưa ra hướng dẫn cụ thể để kết hợp thông tin chi tiết từ cả BigQuery (đối với dữ liệu) và Maps (đối với phân tích vị trí).
- Công cụ: Cả
maps_toolsetvà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 chỉ dẫn để xem chỉ dẫn đó ảnh hưởng đến hành vi của trợ lý ảo như thế nào.
7. Trò chuyện với trợ lý ảo của bạn!
Quay lại cửa sổ dòng lệnh trong Cloud Shell rồi chạy lệnh sau để chuyển đến thư mục adk_agent:
cd adk_agent
Chạy lệnh sau để khởi động giao diện web ADK. Lệnh này sẽ khởi động một máy chủ web đơn giản để lưu trữ ứng dụng trò chuyện:
adk web
Sau khi máy chủ khởi động, bạn có thể trò chuyện với trợ lý ảo bằng cách nhấp vào URL được cung cấp để chạy Giao diện web ADK.
Tương tác với Trợ lý bằng cách đặt các câu hỏi sau. Bạn sẽ thấy các công cụ có liên quan đang được gọi.
- Tìm hiểu về khu vực lân cận (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ưu lượng người đi bộ cao nhất vào buổi sáng".
Tác nhân nên 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í (Vi mô): "Bạn có thể tìm kiếm "Tiệm bánh" theo mã bưu chính đó để xem liệu khu vực đó có quá nhiều tiệm bánh hay không?"
Nhân viên hỗ trợ nên 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.
Hãy thử ngay! Hãy xem những câu hỏi mẫu này để thấy cách hoạt động của nhân viên hỗ trợ ADK:
- "Tôi đang muốn mở tiệm bánh thứ tư ở Los Angeles. Tôi cần một khu dân cư có hoạt động sớm. Tìm mã bưu chính có "điểm số lưu lượng người đi bộ vào buổi sáng" cao nhất.
- "Bạn có thể tìm kiếm "Tiệm bánh" theo mã bưu chính đó để xem liệu thị trường đã bão hoà hay chưa? Nếu có quá nhiều, hãy tìm các quán "Cà phê đặc sản" để tôi có thể đặt mình gần đó nhằm thu hút khách vãng lai."
- "Được rồi, tôi muốn định vị thương hiệu này là một thương hiệu cao cấp. Giá tối đa cho một "Ổ bánh mì bột chua" ở khu vực đô thị Los Angeles là bao nhiêu?"
- "Bây giờ, tôi muốn xem dự đoán doanh thu cho tháng 12 năm 2025. Xem nhật ký bán hàng của tôi và lấy dữ liệu từ cửa hàng hoạt động hiệu quả nhất của tôi cho "Ổ bánh mì bột chua". Chạy dự báo cho tháng 12 năm 2025 để ước tính số lượng tôi sẽ bán. Sau đó, hãy tính tổng doanh thu dự kiến bằng cách sử dụng mức giá thấp hơn một chút so với mức giá cao cấp mà chúng tôi tìm được (giả sử là 18 đô la)"
- "Số tiền đó sẽ đủ để tôi trả tiền thuê nhà. Cuối cùng, hãy xác minh thông tin về 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 ngày."
8. Dọn dẹp
Để tránh các khoản phí phát sinh cho tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã tạo trong Codelab 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, vùng 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 đã tạo thành công một Location Intelligence Agent bằng Agent Development Kit (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à bối 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 kinh doanh phức tạp – tất cả đều được hỗ trợ bởi Giao thức bối cảnh mô hình (MCP) và Gemini.
Những gì bạn đã đạt được:
- 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 2 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.
- Lý luận hợp nhất: Bạn đã tạo một trợ lý 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.