1. Giới thiệu
Ngăn xếp tác nhân hiện đại
Để xây dựng một tác nhân AI cấp sản xuất, bạn cần nhiều thứ hơn là chỉ một mô hình ngôn ngữ lớn (LLM). Mặc dù LLM cung cấp khả năng suy luận, nhưng một tác nhân mạnh mẽ cần tương tác với thế giới bên ngoài, quản lý trạng thái trò chuyện và ghi nhớ các lựa chọn ưu tiên của người dùng theo thời gian.
Trong hội thảo này, bạn sẽ tìm hiểu cách thiết kế và xây dựng một hệ thống toàn diện dựa trên 3 công nghệ nền tảng:
- Khả năng kết nối (MCP): Để cấp cho trợ lý ảo quyền truy cập vào các công cụ và dữ liệu cục bộ.
- Điều phối (ADK): Để quản lý vòng lặp suy luận và trạng thái của tác nhân.
- Bộ nhớ (Ngân hàng bộ nhớ): Để cung cấp ngữ cảnh dài hạn, phù hợp với từng người dùng.
Khái niệm cốt lõi
Thành phần | Chức năng |
Giao thức bối cảnh mô hình (MCP) | Một tiêu chuẩn phổ quát kết nối các mô hình AI với các hệ thống bên ngoài (cơ sở dữ liệu, hệ thống tệp, API) mà không cần tích hợp tuỳ chỉnh. |
Agent Development Kit (ADK) | Một khung hình cung cấp môi trường thời gian chạy cho các tác nhân, quản lý vòng lặp sự kiện, chuyển đổi trạng thái và thực thi công cụ. |
Dịch vụ phiên | Xử lý trí nhớ ngắn hạn. Tính năng này giữ nguyên bối cảnh của cuộc trò chuyện (ví dụ: "Người dùng vừa hỏi gì?") nhưng sẽ bị xoá khi phiên kết thúc. |
Vertex AI Memory Bank | Xử lý trí nhớ dài hạn. Nó duy trì các dữ kiện và lựa chọn ưu tiên dành riêng cho người dùng (ví dụ: "Người dùng thích Python") vô thời hạn, cho phép tác nhân cá nhân hoá các lượt tương tác trong tương lai. |
Vertex AI Agent Engine | Dịch vụ cơ sở hạ tầng được quản lý, lưu trữ các thành phần logic và bộ nhớ của tác nhân ở quy mô lớn. |
Sản phẩm bạn sẽ tạo ra
Để minh hoạ những khái niệm này, bạn sẽ tạo một Trợ lý thiết kế cho kỳ nghỉ. Tác nhân này có thể tiếp nhận các yêu cầu cấp cao của người dùng và tự động điều phối các công cụ Python cục bộ để tạo mã và hình ảnh được cá nhân hoá.
Bạn sẽ trải qua 3 giai đoạn:
- Lớp công cụ: Tạo một máy chủ MCP để hiển thị các hàm Python cục bộ cho AI.
- Lớp tác nhân: Sử dụng ADK để tạo một tác nhân lập kế hoạch và thực thi quy trình công việc nhiều bước.
- Lớp bộ nhớ: Tích hợp Ngân hàng bộ nhớ để cho phép tác nhân tìm hiểu và ghi nhớ các lựa chọn ưu tiên về phong cách của người dùng.
2. Thiết lập
Để hỗ trợ các tác nhân AI của chúng tôi, chúng tôi cần hai thứ: một Dự án Google Cloud để cung cấp nền tảng.
Phần 1: Bật tài khoản thanh toán
- Để nhận tài khoản thanh toán có khoản tín dụng 5 đô la, bạn cần phải có tài khoản này để triển khai. Đảm bảo bạn đã đăng nhập vào tài khoản gmail.
Phần 2: Môi trường mở
- 👉 Nhấp vào đường liên kết này để chuyển trực tiếp đến Cloud Shell Editor
- 👉 Nếu được nhắc uỷ quyền vào bất kỳ thời điểm nào trong ngày hôm nay, hãy nhấp vào Uỷ quyền để tiếp tục.
- 👉 Nếu thiết bị đầu cuối không xuất hiện ở cuối màn hình, hãy mở thiết bị đầu cuối:
- Nhấp vào Xem
- Nhấp vào Terminal (Thiết bị đầu cuối)
- 👉💻 Trong thiết bị đầu cuối, hãy xác minh rằng bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:
gcloud auth list - 👉💻 Sao chép dự án khởi động từ GitHub:
git clone https://github.com/cuppibla/holiday_workshop - 👉💻 Chạy tập lệnh thiết lập trong thư mục dự án.
cd ~/holiday_workshop ./init.sh - 👉💻 Đặt mã dự án cần thiết:
gcloud config set project $(cat ~/project_id.txt) --quiet
Phần 3: Thiết lập quyền
- 👉💻 Bật các API bắt buộc bằng lệnh sau. Việc này có thể mất vài phút.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 Cấp các quyền cần thiết bằng cách chạy các lệnh sau trong thiết bị đầu cuối:
. ~/holiday_workshop/set_env.sh
Xin lưu ý rằng một tệp .env sẽ được tạo cho bạn. Thẻ này cho biết thông tin dự án của bạn.
3. Tăng sức mạnh bằng MCP
Khoảnh khắc "USB-C" đối với AI
Hãy tưởng tượng nếu mỗi lần mua chuột mới, bạn đều phải hàn nó vào bo mạch chủ. Đó là trạng thái của các công cụ AI cho đến gần đây. Nhà phát triển phải viết "mã kết nối" tuỳ chỉnh để kết nối LLM với cơ sở dữ liệu, hệ thống tệp hoặc API.
Nhập Giao thức ngữ cảnh mô hình (MCP). Hãy coi MCP như cổng USB-C cho các ứng dụng AI. Đây là một cách chuẩn hoá để kết nối các mô hình AI với các nguồn dữ liệu và công cụ.
Nếu tạo máy chủ MCP cho các công cụ của mình một lần, bạn có thể cắm máy chủ đó vào Gemini CLI, một IDE hoặc bất kỳ ứng dụng nào khác tuân thủ MCP mà không cần thay đổi một dòng mã nào.
Sản phẩm bạn sẽ tạo ra
Trong lớp học lập trình này, bạn sẽ tạo một Trợ lý thiết kế cho kỳ nghỉ có khả năng:
- Kết nối với môi trường cục bộ (công cụ của studio) bằng MCP.
- Quản lý bối cảnh trò chuyện một cách đáng tin cậy bằng Bộ phát triển tác nhân (ADK).
- Ghi nhớ các lựa chọn ưu tiên của bạn (ví dụ: "Tôi thích mã Python") trong nhiều phiên bằng Vertex AI Memory Bank.
Xây dựng logic máy chủ
Chúng tôi đã chuẩn bị môi trường, nhưng logic máy chủ chưa hoàn chỉnh. Chúng ta cần triển khai 4 công cụ cụ thể mà Agent sẽ sử dụng để tạo thiệp chúc mừng.
Phần 1: Mở cấu trúc máy chủ
Chúng ta sẽ làm việc trong thư mục 01-MCP-Files-Testing/01-starter.
- Trong thiết bị đầu cuối Cloud Shell, hãy đảm bảo rằng bạn đang ở đúng thư mục:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - Mở tệp trong Cloud Shell Editor bằng cách chạy:
cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
Bạn sẽ thấy mã chuẩn (thiết lập máy chủ MCP, xử lý các kết nối và khởi tạo ứng dụng Vertex AI) đã được thực hiện. Tuy nhiên, 4 chức năng cốt lõi hiện là các phần giữ chỗ trống.
Phần 2: Triển khai Trình tạo cảnh theo chủ đề ngày lễ
Trước tiên, chúng ta cần một công cụ ghi nhận mối quan tâm của người dùng (ví dụ: "chim") và biến câu lệnh đó thành một câu lệnh chi tiết, phong phú, được tối ưu hoá để tạo hình ảnh.
Tìm nhận xét #REPLACE_GENERATE_HOLIDAY_SCENE bên trong hàm generate_holiday_scene.
Thay thế toàn bộ dòng này bằng đoạn mã sau:
prompt = (
f"""
Create a cozy, high-fidelity 3D render of a winter holiday scene.
The scene should be warm and inviting with soft cinematic lighting.
Seamlessly integrate the following specific theme/interest into the
holiday decor or landscape: {interest}.
The style should be whimsical but detailed.
Aspect Ratio: 16:9 Landscape.
"""
)
generate_image(prompt, "16:9", "static/generated_scene.png")
return "Done! Saved at generated_scene.png"
Phần 3: Triển khai kết quả ảnh cuối cùng
Cuối cùng, chúng tôi muốn đảm bảo ánh sáng và phong cách trông chân thực và mang không khí lễ hội.
Tìm bình luận #REPLACE_GENERATE_FINAL_PHOTO.
Thay thế toàn bộ dòng này bằng đoạn mã sau để thực hiện quá trình chuyển và kết xuất kiểu cuối cùng:
prompt = (
"""
Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
Lighting: Warm, glowing ambient light from a fire below (out of frame).
Background: Softly blurred (bokeh) pine garland and twinkling lights.
Foreground Composition:
1. A wooden picture frame containing the [attached selfie image].
The face in the photo must be clearly visible.
2. A folded holiday greeting card standing upright next to the frame.
The front of the card displays the [attached holiday scene image] as a print.
Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
"""
)
generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
return "Done! Saved at generated_final_photo.png"
Thiết lập môi trường
Giờ đây, khi mã đã được đặt đúng vị trí, chúng ta cần đảm bảo các phần phụ thuộc đã được cài đặt. Chúng ta sẽ dùng uv, một trình quản lý dự án và gói Python nhanh.
👉💻 Trong cửa sổ dòng lệnh, hãy chạy lệnh sau để thêm FastMCP làm phần phụ thuộc của dự án:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp
Bạn sẽ thấy một phần phụ thuộc mới fastmcp>=2.13.3 được thêm vào tệp ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml.
4. Kiểm thử bằng Gemini CLI cho máy chủ MCP
Giờ đây, khi mã máy chủ đã hoàn tất, làm cách nào để kiểm thử mã này?
Thông thường, việc kiểm thử một máy chủ phụ trợ yêu cầu bạn phải tạo giao diện người dùng chính hoặc viết các yêu cầu curl phức tạp. Tuy nhiên, ở đây, chúng ta có thể sử dụng Gemini CLI.
Điều này cực kỳ hữu ích cho quá trình phát triển vì nó tách biệt logic. Bạn có thể xác minh rằng mô hình hiểu các công cụ của bạn và gọi chúng một cách chính xác trước khi bạn lo lắng về việc xây dựng giao diện web hoặc khung tác nhân.
Kết nối và chạy
Chúng ta sẽ yêu cầu Gemini CLI quản lý máy chủ bằng lệnh mcp add.
Trong thiết bị đầu cuối, hãy chạy:
gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
add holidays: Chúng tôi đặt biệt hiệu cho máy chủ của mình ("holidays").uv run ...: Chúng tôi đã cung cấp lệnh rõ ràng để khởi động máy chủ Python mà chúng tôi vừa sửa đổi.
Cùng sáng tạo nhé!
Bây giờ, hãy bắt đầu phiên trò chuyện:
gemini
Hãy thử câu lệnh sau để kiểm tra xem Gemini có thể "nhìn thấy" các công cụ mới của bạn hay không. Xin lưu ý rằng bạn có thể cần cho phép Gemini CLI sử dụng công cụ ngày lễ của chúng tôi.
- 👉 Người dùng:
"I want to create a festive holiday photo. I like birds a lot." - Gemini:
*Thinking...* *Calling tool: generate_holiday_scene(interest='birds')* Done! Saved at generated_scene.png - 👉 Người dùng:
"Great! Now generate a knitting pattern for a sweater with reindeer on it." - Gemini:
*Thinking...* *Calling tool: generate_sweater_pattern(motif='reindeer')* Done! Saved at generated_pattern.png
Xem lại hình ảnh
- Kết thúc Gemini CLI bằng cách nhấn
Control+C. - Kiểm tra hình ảnh được tạo trong thư mục của bạn:
~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.
Xem ảnh của bạn tại đây: 
Kết luận và các bước tiếp theo
Xin chúc mừng! Bạn đã tạo thành công một máy chủ MCP đang hoạt động. Giờ đây, bạn đã có một bộ "công cụ AI" có thể hoạt động để tạo các mẫu, ghép hình ảnh và tinh chỉnh cảnh.
Tuy nhiên, bạn có nhận thấy điều gì trong bài kiểm tra ở trên không? Bạn phải thúc đẩy quy trình này. Bạn phải yêu cầu cảnh, sau đó yêu cầu mẫu, sau đó yêu cầu kết hợp chúng.
Mặc dù Gemini rất thông minh, nhưng đối với quy trình sản xuất phức tạp (trong đó chúng ta cần tạo một mẫu trước khi có thể đưa mẫu đó lên áo len và xử lý lỗi nếu quá trình tạo hình ảnh không thành công), chúng ta cần có nhiều quyền kiểm soát hơn. Chúng tôi muốn có một hệ thống chuyên dụng có thể lập kế hoạch, phê bình công việc của chính mình và quản lý trạng thái của tấm thiệp chúc mừng mà không cần chúng tôi hướng dẫn từng bước.
Trong phần tiếp theo, chúng ta sẽ sắp xếp lại mớ hỗn độn này. Chúng tôi sẽ triển khai Bộ công cụ phát triển tác nhân (ADK) để xây dựng một Tác nhân có cấu trúc, điều phối các công cụ MCP này thành một quy trình sản xuất hoàn hảo.
5. Lập trình theo cảm hứng cho một tác nhân ADK
Chúng tôi có một bộ công cụ đang hoạt động (máy chủ MCP của chúng tôi), nhưng hiện tại, chúng tôi là bên thực hiện tất cả các công việc nặng nhọc – cho Gemini biết chính xác công cụ nào cần gọi và thời điểm nào.
Trong phần này, chúng ta sẽ xây dựng một tác nhân AI: một hệ thống có thể suy luận, lập kế hoạch và tự động thực hiện các nhiệm vụ nhiều bước. Để làm việc này, chúng ta sẽ sử dụng Bộ công cụ phát triển tác nhân (ADK).
Tác nhân là gì?
Nếu các công cụ MCP là "bàn tay" (thực hiện công việc), thì Agent là "bộ não". Một tác nhân sử dụng LLM để hiểu ý định của người dùng ("Tạo cho tôi một tấm thiệp chúc mừng ngày lễ"), chia ý định đó thành các bước ("Trước tiên, tôi cần một cảnh, sau đó là một mẫu...") và quyết định sử dụng công cụ nào để đạt được mục tiêu.
ADK là gì?
Bộ công cụ phát triển (ADK) dành cho tác nhân là một khung của Google giúp bạn dễ dàng xây dựng các tác nhân này. Nền tảng này xử lý các "công việc" phức tạp, chẳng hạn như quản lý nhật ký trò chuyện, kết nối với các công cụ và chuyển đổi giữa các mô hình khác nhau, nhờ đó bạn có thể tập trung vào tính cách và logic của ứng dụng.
Lập trình theo cảm hứng dựa trên bối cảnh
Một mẫu phổ biến là sử dụng một câu lệnh duy nhất và đồ sộ để tạo mã. Tuy nhiên, khi xây dựng các ứng dụng phức tạp, bạn nên coi AI là một đối tác duy trì ngữ cảnh theo thời gian.
Chúng ta sẽ sử dụng các tính năng Bộ nhớ của Gemini CLI để thiết lập giai đoạn trước khi viết một dòng mã.
1. Chuẩn bị môi trường
Mở cửa sổ dòng lệnh rồi chuyển đến thư mục khởi động:
cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter
Bắt đầu Gemini CLI:
gemini
2. Quản lý bối cảnh và bộ nhớ
Khi tạo mã rung, AI cần biết ai là người tạo và nội dung mà người đó biết. Gemini CLI cho phép chúng ta quản lý việc này một cách rõ ràng.
/memory show: Nhập nội dung này để xem những thông tin mà AI hiện biết về dự án và phiên của bạn./memory add: Sử dụng thông tin này để cung cấp kiến thức cơ bản mà AI cần ghi nhớ trong suốt cuộc trò chuyện.
Hãy bắt đầu bằng cách xác định tính cách của đối tác lập trình. Chạy lệnh sau trong Gemini CLI:
/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."
Gemini hiện đã hiểu rõ vai trò của mình. Bối cảnh này sẽ ảnh hưởng đến mọi phản hồi tiếp theo, đảm bảo mã tuân thủ ADK có chất lượng cao.
3. Bước 1: Lập trình cảm xúc cho tác nhân cơ bản
Thay vì cố gắng tạo toàn bộ hệ thống cùng một lúc, hãy bắt đầu bằng bộ khung. Chúng tôi muốn thiết lập cấu trúc tệp và tính cách cơ bản của trợ lý ảo.
Nhập câu lệnh sau vào Gemini CLI:
Let's start by building the basic agent structure.
Please create a file structure for a `root_agent`.
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant".
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.
Gemini sẽ tạo cấu trúc tệp và mã Python ban đầu. Hãy xem xét để đảm bảo thông tin đó chính xác, sau đó áp dụng/chấp nhận các thay đổi.
4. Bước 2: Thêm máy chủ MCP (Công cụ)
Giờ đây, khi đã có một tác nhân cơ bản, chúng ta cần cung cấp cho tác nhân này "các thao tác". Chúng ta cần kết nối tác nhân với máy chủ MCP mà chúng ta đã tạo trong phòng thí nghiệm trước.
Nhập câu lệnh sau vào Gemini CLI:
Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.
Giờ đây, Gemini sẽ tái cấu trúc agent.py hiện có của bạn để thêm các định nghĩa về công cụ và logic kết nối.
Lưu ý: Nếu muốn kiểm tra công việc của mình hoặc nếu mã được tạo không hoạt động như dự kiến, bạn có thể so sánh các tệp của mình với giải pháp tham chiếu trong: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution
6. Chạy Giao diện web của nhân viên hỗ trợ
ADK đi kèm với một giao diện kiểm thử tích hợp sẵn có tên là adk web. Thao tác này sẽ tạo ra một giao diện người dùng trò chuyện đơn giản để chúng ta có thể trò chuyện ngay với trợ lý ảo.
- Nếu bạn vẫn đang mở GeminiCLI, hãy nhấn
control+Cđể đóng. Bây giờ, trong thiết bị đầu cuối(nằm trong thư mụcsolution, bạn có thể chuyển đếnstarterđể kiểm thử mã bằng cách chạyuv run adk webtrong thư mụcstarter), hãy chạy:cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - Cloud Shell sẽ cảnh báo bạn rằng một dịch vụ đang chạy trên cổng 8000. Nhấp vào "Web Preview" (Xem trước trên web) -> "Preview on port 8000" (Xem trước trên cổng 8000).
Kiểm thử Nhân viên hỗ trợ
Lúc này, bạn sẽ thấy giao diện trò chuyện. Hãy xem liệu Agent của chúng ta có tuân theo hướng dẫn mới và truy cập đúng các công cụ MCP hay không.
Hãy thử những câu lệnh sau:
- "Chào bạn! Bạn là ai?"
- (Dự kiến sẽ nhận được phản hồi nhiệt tình và mang không khí lễ hội).
- "Tôi cần một phông nền cho thiệp chúc mừng ngày lễ. Hãy tạo một ngôi làng phủ đầy tuyết."
- (Nhân viên hỗ trợ nên gọi cho
generate_holiday_scene. Hãy lưu ý cách nó tự động áp dụng kiểu "dễ thương/hoạt hình" được xác định trong hướng dẫn hệ thống).
- (Nhân viên hỗ trợ nên gọi cho
- "Tạo một mẫu áo len có những lát bánh pizza nhỏ trên đó."
- (Nhân viên hỗ trợ nên gọi đến số điện thoại
generate_sweater_pattern).
- (Nhân viên hỗ trợ nên gọi đến số điện thoại
Bạn có thể xem hình ảnh được tạo tại đây:
Nhấn Control+C để thoát nếu bạn đã kiểm tra xong.
Kết luận và các bước tiếp theo
Giờ đây, bạn đã "Vibe-Coded" thành công một Google ADK Agent bằng cách tiếp cận dựa trên bối cảnh!
- Chúng tôi thiết lập Bối cảnh: Chúng tôi đã sử dụng
/memory addđể xác định một nhân vật chuyên gia. - Chúng tôi đã xây dựng Iteratively: Chúng tôi tạo bộ khung trước, sau đó thêm các kết nối công cụ.
Bản xem trước web ADK tích hợp rất phù hợp để kiểm thử, nhưng đối với sản phẩm cuối cùng, chúng tôi muốn có một trải nghiệm tuỳ chỉnh, mang thương hiệu riêng. Trong phần tiếp theo, chúng ta sẽ tích hợp Agent này vào một giao diện người dùng web tuỳ chỉnh.
7. Kết nối ADK với giao diện người dùng
Giờ đây, khi đã có một định nghĩa về Agent, chúng ta cần chạy định nghĩa đó. Đây là nơi Runner và Session Service xuất hiện.
Triển khai
- 👉 Nhập nội dung sau vào lệnh:
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pytrong trình chỉnh sửa của bạn. - Thay thế
# TODO: Create Session Servicebằng nội dung sau:from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService() - Thay thế
# TODO: Initialize Runnerbằng nội dung sau:runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
- Xem dòng 158 tại
~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(không cần làm gì): Nếu bạn thắc mắc về cách ứng dụng nhận được phản hồi cuối cùng? Dưới đây là vòng lặp sự kiện do trình chạy cung cấp:async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=content )
Tìm hiểu chuyên sâu: Kiến trúc và việc triển khai
Chúng tôi đang sử dụng FastAPI để cung cấp tác nhân này.
- Tại sao nên chọn FastAPI?: Các tác nhân thường bị giới hạn về I/O (chờ các LLM). Bản chất không đồng bộ của FastAPI xử lý vấn đề này một cách hoàn hảo.
- Không trạng thái: Lưu ý rằng điểm cuối API của chúng tôi là không trạng thái. Chúng tôi không lưu các biến trong phạm vi toàn cục. Chúng tôi dựa vào
session_idvàSessionServiceđể khôi phục trạng thái cho từng yêu cầu. Điều này có nghĩa là bạn có thể triển khai ứng dụng này lên Cloud Run (Không máy chủ) và mở rộng quy mô đến 0!
8. Thử ứng dụng bằng tính năng thông minh của tác nhân
- 👉💻 Nhập nội dung sau vào lệnh:
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pytrong trình chỉnh sửa của bạn. - Bạn sẽ thấy kết quả như bên dưới:
👉👉 Nhớ nhấp vào http://localhost:5173/hoặc mở một cửa sổ mới rồi nhậphttp://localhost:5173/. - Sau đó, bạn sẽ thấy trang web có giao diện trò chuyện:
- Thử nghiệm bằng cách tải một hình ảnh lên(có thể là bạn hoặc thú cưng của bạn)
- 👉 Sau đó, hãy hỏi
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👉💻 Sau khi hoàn tất kiểm thử, hãy nhấn
control+Ctrong thiết bị đầu cuối để kết thúc quy trình.
Nếu không thấy mọi thứ hoạt động như mong đợi, bạn có thể chuyển đến ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution và chạy ./start_app.sh, sau đó thực hiện các bước tương tự như trên.
9. Vertex AI Memory Bank
Trí nhớ ngắn hạn và trí nhớ dài hạn
- Bối cảnh ngắn hạn: "Tôi vừa nói gì?" (Nhật ký phiên). Thông tin này sẽ bị mất khi cửa sổ trò chuyện đóng.
- Trí nhớ dài hạn: "Ngôn ngữ lập trình yêu thích của tôi là gì?" (Lựa chọn ưu tiên của người dùng). Việc này sẽ diễn ra vĩnh viễn.
Vertex AI Memory Bank cung cấp bộ nhớ dài hạn này. Nhờ đó, tác nhân có thể lưu trữ và truy xuất thông tin được cá nhân hoá về người dùng.
Phiên so với Ngân hàng bộ nhớ
- Phiên (
VertexAiSessionService): Đây là Nhật ký. Tệp này lưu trữ chuỗi thô, theo trình tự thời gian của mọi thông báo, lệnh gọi công cụ và sự kiện (AppendEvent,ListEvents). Tệp này cung cấp thông tin chính xác về những gì đã xảy ra. - Ngân hàng trí nhớ (
VertexAiMemoryBankService): Đây là Kiến thức. Nó lưu trữ các thông tin thực tế tổng hợp, dài hạn (GenerateMemories,RetrieveMemories). Nó được giới hạn trong mộtuser_idcụ thể, đảm bảo quyền riêng tư và sự tách biệt.
- 👉💻 Nhập nội dung sau vào lệnh:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.pytrong trình chỉnh sửa của bạn. - Tìm
# TODO: Create Vertex AI Session Service & Memory Bank Service, thay thế toàn bộ dòng bằng nội dung sau:session_service = VertexAiSessionService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID ) memory_service = VertexAiMemoryBankService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID )
- 👉💻 Nhập nội dung sau vào lệnh:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pytrong trình chỉnh sửa của bạn. - Thay thế
# TODO: Set Up Configurationbằng nội dung sau:# Basic configuration types MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig SimilaritySearchConfig = ( types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig ) GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig # Advanced configuration types CustomizationConfig = types.MemoryBankCustomizationConfig MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample ConversationSource = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource ) ConversationSourceEvent = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent ) ExampleGeneratedMemory = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory )
- 👉 Trong cùng một tệp:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Tìm# TODO: Set up topic, thay thế toàn bộ dòng bằng nội dung sau:custom_topics = [ # Topic 1: Sweater Preference MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="sweater_preference", description="""Extract the user's preferences for sweater styles, patterns, and designs. Include: - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.) - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted) - Color preferences (red, green, navy, pastel, etc.) - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft) - Themes (retro, modern, ugly christmas sweater, elegant) Example: "User wants a retro style sweater with a pixelated reindeer pattern." Example: "User prefers dark blue colors and hates itchy wool." """, ) ), # Topic 2: Personal Context MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="personal_context", description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include: - Hobbies and activities (skiing, reading, gaming, cooking, etc.) - Pets (type, breed, name, color) - Job or profession if relevant to their style - General interests (sci-fi, nature, vintage, tech) - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach) Example: "User has a golden retriever named Max." Example: "User loves skiing and wants a snowy mountain background." Example: "User is a software engineer who likes cyberpunk aesthetics." """, ) ) ] - 👉 Trong cùng một tệp:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Tìm# TODO: Create Agent Engine, thay thế toàn bộ dòng bằng nội dung sau:agent_engine = client.agent_engines.create( config={ "display_name": AGENT_DISPLAY_NAME, "context_spec": { "memory_bank_config": { "generation_config": { "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash" }, "customization_configs": [customization_config] } }, } )
Tại sao không chỉ dùng Lệnh?
Bạn có thể hỏi: "Tại sao chúng ta không dán nhật ký của người dùng vào câu lệnh?"
- Giới hạn kích thước: Cửa sổ ngữ cảnh có kích thước lớn nhưng không phải là vô hạn. Bạn không thể lưu trữ 5 năm nhật ký.
- Chi phí: Việc xử lý 1 triệu mã thông báo cho mỗi "Xin chào" sẽ tốn rất nhiều chi phí.
- Tập trung: Ngân hàng bộ nhớ đóng vai trò là một Công cụ tìm kiếm cho tác nhân của bạn. Công cụ này chỉ truy xuất những thông tin có liên quan.
- 👉💻 Nhập nội dung sau vào lệnh:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pytrong trình chỉnh sửa của bạn. - Trong tệp:
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyThay thế# TODO: Add PreloadMemoryToolbằng nội dung sau:if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool và add_session_to_memory
Trong agent.py, bạn sẽ thấy 2 thành phần chính:
PreloadMemoryTool: Đây là một công cụ cho phép nhân viên hỗ trợ "tự tìm kiếm thông tin trên Google". Nếu người dùng hỏi một câu mơ hồ như "Lấy cho tôi cà phê như mọi khi", thì trợ lý có thể dùng công cụ này để truy vấn Ngân hàng bộ nhớ về "các lựa chọn ưu tiên về cà phê" trước khi trả lời.add_session_to_memory: Đây là một lệnh gọi lại ở chế độ nền.- Tại sao lại dùng Async? Việc lưu trữ bộ nhớ mất thời gian (tóm tắt cuộc trò chuyện, trích xuất dữ kiện). Chúng tôi không muốn người dùng phải chờ đợi điều này. Chúng ta sẽ chạy ứng dụng này ở chế độ nền (
add_session_to_memory) bằng cách sử dụngafter_agent_callback.
- Tại sao lại dùng Async? Việc lưu trữ bộ nhớ mất thời gian (tóm tắt cuộc trò chuyện, trích xuất dữ kiện). Chúng tôi không muốn người dùng phải chờ đợi điều này. Chúng ta sẽ chạy ứng dụng này ở chế độ nền (
10. Ngân hàng bộ nhớ đang hoạt động
- 👉💻 Nhập nội dung sau vào lệnh:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
Kiểm tra tệp ~/holiday_workshop/.env, bạn sẽ thấy (không cần làm gì cả)USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👉💻 Kiểm thử bộ nhớ bằng giao diện người dùng ứng dụng. Nhập nội dung sau vào lệnh:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/hoặc mở một cửa sổ mới rồi nhậphttp://localhost:5173/.Xin lưu ý rằngUvicorn running on http://0.0.0.0:8000chỉ là máy chủ phụ trợ, không phải đường liên kết thực tế mà chúng ta muốn nhấp vào.Giờ đây, giao diện trò chuyện trên trang web đã trở thành trợ lý được cá nhân hoá của bạn! - 👉Kiểm tra bộ nhớ. Nếu bạn nhập trong giao diện người dùng:
I want a sweater that matches my dog. He's a golden retriever.I'm a programmer, so I want something geeky. Maybe a matrix style?I like snowflake sweater pattern
Trợ lý sẽ xác định đây là một lựa chọn ưu tiên và lưu trữ lựa chọn đó trong Ngân hàng bộ nhớ.
Tuần tới(hoặc bất cứ lúc nào bạn khởi động lại ứng dụng bằng cách nhấn Control+C và ./start_app.sh), nếu bạn hỏi:
what is my preference on sweater pattern?
Tác nhân sẽ truy vấn Ngân hàng bộ nhớ, xem lựa chọn ưu tiên của bạn và tạo mẫu áo len mà không cần bạn yêu cầu. 
- Xác minh trong Vertex AI Agent Engine bằng cách chuyển đến Google Cloud Console Agent Engine
- Nhớ chọn dự án trong bộ chọn dự án ở trên cùng bên trái:
- Và xác minh công cụ nhân viên hỗ trợ mà bạn vừa triển khai từ lệnh trước đó
use_memory_bank.sh
Nhấp vào công cụ nhân viên hỗ trợ mà bạn vừa tạo.
- Nhớ chọn dự án trong bộ chọn dự án ở trên cùng bên trái:
- Nhấp vào thẻ
Memoriestrong tác nhân đã triển khai này, bạn có thể xem tất cả bộ nhớ tại đây.
Xin chúc mừng! Bạn vừa đính kèm bộ nhớ vào tác nhân của mình!
11. Kết luận
Tóm tắt
Bạn đã thiết kế và xây dựng thành công một hệ thống dựa trên tác nhân hoàn chỉnh.
- Khả năng kết nối: Bạn đã sử dụng MCP để chuẩn hoá cách mà trợ lý của bạn truy cập vào các công cụ cục bộ.
- Điều phối: Bạn đã sử dụng ADK để quản lý vòng lặp suy luận phức tạp cần thiết cho các tác vụ nhiều bước.
- Cá nhân hoá: Bạn đã sử dụng Memory Bank để tạo một lớp học liên tục, có khả năng học hỏi và ghi nhớ bối cảnh của người dùng.
Các bước tiếp theo
- Tạo MCP Server của riêng bạn: Tạo một máy chủ cho API hoặc cơ sở dữ liệu nội bộ của bạn.
- Khám phá các mẫu ADK: Tìm hiểu về "Vòng lặp suy luận" và "Điều phối" trong tài liệu ADK.
- Triển khai: Chuyển tác nhân của bạn từ một tập lệnh cục bộ sang một dịch vụ sản xuất trên Cloud Run.