1. Giới thiệu

1. Thách thức
Trong các tình huống ứng phó thiên tai, việc điều phối những người sống sót có kỹ năng, nguồn lực và nhu cầu khác nhau ở nhiều địa điểm đòi hỏi phải có khả năng tìm kiếm và quản lý dữ liệu thông minh. Hội thảo này hướng dẫn bạn cách xây dựng một hệ thống AI chính thức kết hợp:
- 🗄️ Cơ sở dữ liệu đồ thị (Spanner): Lưu trữ các mối quan hệ phức tạp giữa người sống sót, kỹ năng và tài nguyên
- 🔍 Tìm kiếm dựa trên AI: Tìm kiếm kết hợp ngữ nghĩa + từ khoá bằng cách sử dụng tính năng nhúng
- 📸 Xử lý đa phương thức: Trích xuất dữ liệu có cấu trúc từ hình ảnh, văn bản và video
- 🤖 Điều phối nhiều tác nhân: Điều phối các tác nhân chuyên biệt cho quy trình công việc phức tạp
- 🧠 Bộ nhớ dài hạn: Cá nhân hoá bằng Vertex AI Memory Bank

2. Sản phẩm bạn sẽ tạo ra
Cơ sở dữ liệu đồ thị mạng lưới cứu trợ với:
- 🗺️ Biểu đồ trực quan 3D tương tác về mối quan hệ giữa những người sống sót
- 🔍 Tìm kiếm thông minh (từ khoá, ngữ nghĩa và kết hợp)
- 📸 Quy trình tải lên đa phương thức (trích xuất thực thể từ hình ảnh/video)
- 🤖 Hệ thống nhiều tác nhân để điều phối các nhiệm vụ phức tạp
- 🧠 Tích hợp Ngân hàng bộ nhớ để tương tác theo cách phù hợp với từng người dùng
3. Công nghệ cốt lõi
Thành phần | Công nghệ | Mục đích |
Cơ sở dữ liệu | Biểu đồ Cloud Spanner | Lưu trữ các nút (người sống sót, kỹ năng) và cạnh (mối quan hệ) |
Tìm kiếm bằng AI | Gemini + Embeddings | Hiểu ngữ nghĩa + tìm kiếm tương đồng |
Khung tác nhân | ADK (Bộ công cụ phát triển tác nhân) | Điều phối quy trình công việc dựa trên AI |
Bộ nhớ | Vertex AI Memory Bank | Lưu trữ lựa chọn ưu tiên của người dùng trong thời gian dài |
Giao diện người dùng | React + Three.js | Hình ảnh trực quan hoá biểu đồ 3D tương tác |
2. 🛠️ Chuẩn bị môi trường (Bỏ qua nếu bạn đang tham gia Hội thảo)
Phần một: Bật tài khoản thanh toán
Để chạy lớp học lập trình này, bạn cần có một tài khoản thanh toán có một số tín dụng. Hãy sử dụng tín dụng trong biểu ngữ ở đầu lớp học lập trình này để bắt đầu. Nếu đã kết nối với một tài khoản thanh toán, bạn có thể bỏ qua bước này.
Phần hai: Môi trường mở
- 👉 Nhấp vào đường liên kết này để chuyển thẳng đến Trình chỉnh sửa Cloud Shell
- 👉 Nếu bạn đượ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 cửa sổ dòng lệnh không xuất hiện ở cuối màn hình, hãy mở cửa sổ đó:
- Nhấp vào Xem
- Nhấp vào Terminal (Thiết bị đầu cuối)

- 👉💻 Trong dòng lệnh, 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/gca-americas/way-back-home.git
Phần 3: Tạo dự án mới
👉💻 Trong dòng lệnh, hãy đặt tập lệnh khởi tạo thành tệp thực thi và chạy tập lệnh đó:
cd ~/way-back-home/level_2
./init.sh
3. 🛠️ Thiết lập môi trường
1. Mở Cloud Shell
Trong cửa sổ dòng lệnh Trình chỉnh sửa Cloud Shell, nếu cửa sổ dòng lệnh không xuất hiện ở cuối màn hình, hãy mở cửa sổ đó:
- Nhấp vào Xem
- Nhấp vào Terminal (Thiết bị đầu cuối)

2. Định cấu hình dự án
👉💻 Trong dòng lệnh, hãy đặt mã dự án:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Bật các API bắt buộc (quá trình này mất khoảng 2-3 phút):
gcloud services enable compute.googleapis.com \
aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
spanner.googleapis.com \
storage.googleapis.com
3. Chạy tập lệnh thiết lập
👉💻 Thực thi tập lệnh thiết lập:
cd ~/way-back-home/level_2
./setup.sh
Thao tác này sẽ tạo .env cho bạn. Trong cloudshell, hãy mở dự án way_back_home. Trong thư mục level_2, bạn có thể thấy tệp .env được tạo cho bạn. Nếu không tìm thấy, bạn có thể nhấp vào View -> Toggle Hidden File để xem. 
4. Tải dữ liệu mẫu
👉💻 Chuyển đến phần phụ trợ và cài đặt các phần phụ thuộc:
cd ~/way-back-home/level_2/backend
uv sync
👉💻 Tải dữ liệu ban đầu về người sống sót:
uv run python ~/way-back-home/level_2/backend/setup_data.py
Điều này tạo ra:
- Phiên bản Spanner (
survivor-network) - Cơ sở dữ liệu (
graph-db) - Tất cả bảng nút và cạnh
- Biểu đồ thuộc tính để truy vấn Kết quả dự kiến:
============================================================
SUCCESS! Database setup complete.
============================================================
Instance: survivor-network
Database: graph-db
Graph: SurvivorGraph
Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome
Nếu nhấp vào đường liên kết sau Access your database at trong kết quả, bạn có thể mở Spanner trong Google Cloud Console.

Và bạn sẽ thấy Spanner tại Google Cloud Console!

4. 🚀 Trực quan hoá dữ liệu đồ thị trong Spanner Studio
Hướng dẫn này giúp bạn trực quan hoá và tương tác với dữ liệu biểu đồ Survivor Network ngay trong Google Cloud Console bằng Spanner Studio. Đây là một cách hiệu quả để xác minh dữ liệu và tìm hiểu cấu trúc đồ thị trước khi xây dựng tác nhân AI.
1. Truy cập vào Spanner Studio
- Trong bước cuối cùng, hãy nhớ nhấp vào đường liên kết và mở Spanner Studio.

2. Tìm hiểu cấu trúc biểu đồ ("Bức tranh toàn cảnh")
Hãy coi tập dữ liệu Survivor Network như một câu đố logic hoặc một Trạng thái trò chơi:
Thực thể | Vai trò trong hệ thống | Phép loại suy |
Survivors | Tác nhân/người chơi | Người chơi |
Quần xã sinh vật | Vị trí của họ | Vùng trên bản đồ |
Kỹ năng | Những việc họ có thể làm | Khả năng |
Nhu cầu | Thiếu (Khủng hoảng) | Nhiệm vụ |
Tài nguyên | Vật phẩm tìm thấy trong thế giới | Loot |
Mục tiêu: Nhiệm vụ của tác nhân AI là kết nối Kỹ năng (Giải pháp) với Nhu cầu (Vấn đề), có tính đến Quần xã sinh vật (Các quy định ràng buộc về vị trí).
🔗 Cạnh (Mối quan hệ):
SurvivorInBiome: Theo dõi vị tríSurvivorHasSkill: Danh sách các khả năngSurvivorHasNeed: Danh sách các vấn đề đang xảy raSurvivorFoundResource: Kho hàngSurvivorCanHelp: Mối quan hệ được suy luận (AI tính toán mối quan hệ này!)
3. Truy vấn biểu đồ
Hãy chạy một vài truy vấn để xem "Câu chuyện" trong dữ liệu.
Biểu đồ Spanner sử dụng GQL (Ngôn ngữ truy vấn biểu đồ). Để chạy một truy vấn, hãy sử dụng GRAPH SurvivorNetwork, theo sau là mẫu khớp của bạn.
👉 Truy vấn 1: Danh sách toàn cầu (Ai ở đâu?) Đây là nền tảng của bạn – việc hiểu rõ vị trí là yếu tố quan trọng đối với các hoạt động cứu hộ.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result
Kết quả sẽ có dạng như sau: 
👉 Câu hỏi 2: Ma trận kỹ năng (Năng lực) Giờ bạn đã biết vị trí của mọi người, hãy tìm hiểu năng lực của họ.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result
Kết quả sẽ có dạng như sau: 
👉 Câu hỏi 3: Ai đang gặp khủng hoảng? ("Bảng nhiệm vụ") Xem những người sống sót cần trợ giúp và những gì họ cần.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result
Kết quả sẽ có dạng như sau: 
🔎 [Không bắt buộc] Kết nối – Ai có thể giúp ai?
Đây là lúc biểu đồ phát huy sức mạnh! Truy vấn này tìm những người sống sót có kỹ năng có thể đáp ứng nhu cầu của những người sống sót khác.
GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result
Kết quả sẽ có dạng như sau: 
aside positive What This Query Does:
Thay vì chỉ cho thấy "Sơ cứu vết bỏng" (điều này đã rõ ràng trong giản đồ), truy vấn này sẽ tìm:
- Bác sĩ Elena Frost (có kiến thức y khoa) → có thể điều trị → Thuyền trưởng Tanaka (bị bỏng)
- David Chen (có kỹ năng Sơ cứu) → có thể điều trị cho → Trung uý Park (bị bong gân mắt cá chân)
Lý do tính năng này hiệu quả:
Việc tác nhân AI sẽ làm:
Khi người dùng hỏi "Ai có thể điều trị vết bỏng?", tác nhân sẽ:
- Chạy một truy vấn biểu đồ tương tự
- Kết quả: "Bác sĩ Frost có kiến thức y khoa và có thể giúp Thuyền trưởng Tanaka"
- Người dùng không cần biết về các bảng hoặc mối quan hệ trung gian!
5. 🚀 Nhúng dựa trên AI trong Spanner
1. Tại sao nên sử dụng mục nhúng? (Không có hành động, chỉ có thể đọc)
Trong tình huống sinh tồn, thời gian là yếu tố then chốt. Khi một người sống sót báo cáo tình huống khẩn cấp, chẳng hạn như I need someone who can treat burns hoặc Looking for a medic, họ không thể lãng phí thời gian để đoán tên chính xác của kỹ năng trong cơ sở dữ liệu.
Tình huống thực tế: Người sống sót: Captain Tanaka has burns—we need medical help NOW!
Tìm kiếm từ khoá truyền thống cho "medic" → 0 kết quả ❌
Tìm kiếm ngữ nghĩa bằng các mục nhúng → Tìm thấy "Đào tạo y tế", "Sơ cứu" ✅
Đây chính xác là những gì nhân viên hỗ trợ cần: khả năng tìm kiếm thông minh, giống như con người, hiểu được ý định chứ không chỉ từ khoá.
2. Tạo mô hình nhúng

Bây giờ, hãy tạo một mô hình chuyển đổi văn bản thành các mục nhúng bằng text-embedding-004 của Google.
👉 Trong Spanner Studio, hãy chạy SQL này (thay thế $YOUR_PROJECT_ID bằng mã dự án thực tế của bạn):
‼️ Trong trình chỉnh sửa Cloud Shell, hãy mở File -> Open Folder -> way-back-home/level_2 để xem toàn bộ dự án.

👉 Chạy truy vấn này trong Spanner Studio bằng cách sao chép và dán truy vấn bên dưới, sau đó nhấp vào nút Chạy:
CREATE OR REPLACE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);
Tác dụng:
- Tạo một mô hình ảo trong Spanner (không lưu trữ trọng số mô hình trên thiết bị)
- Trỏ đến
text-embedding-004của Google trên Vertex AI - Xác định hợp đồng: Đầu vào là văn bản, đầu ra là một mảng số thực 768 chiều
Tại sao nên chọn "LỰA CHỌN LÀM VIỆC TỪ XA"?
- Spanner không tự chạy mô hình
- Gemini sẽ gọi Vertex AI thông qua API khi bạn sử dụng
ML.PREDICT - Không cần ETL: Không cần xuất dữ liệu sang Python, xử lý rồi nhập lại
Nhấp vào nút Run, sau khi thành công, bạn có thể thấy kết quả như bên dưới:

3. Thêm cột nhúng
👉 Thêm một cột để lưu trữ các mục nhúng:
ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;
Nhấp vào nút Run, sau khi thành công, bạn có thể thấy kết quả như bên dưới:

4. Tạo dữ liệu nhúng
👉 Sử dụng AI để tạo các mục nhúng vectơ cho từng kỹ năng:
UPDATE Skills
SET skill_embedding = (
SELECT embeddings.values
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT name AS content)
)
)
WHERE skill_embedding IS NULL;
Nhấp vào nút Run, sau khi thành công, bạn có thể thấy kết quả như bên dưới:

Điều gì xảy ra: Mỗi tên kỹ năng (ví dụ: "sơ cứu") được chuyển đổi thành một vectơ 768 chiều đại diện cho ý nghĩa ngữ nghĩa của kỹ năng đó.
5. Xác minh dữ liệu nhúng
👉 Kiểm tra để đảm bảo các mục nhúng đã được tạo:
SELECT
skill_id,
name,
ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;
Kết quả đầu ra dự kiến:

6. Thử nghiệm tính năng Tìm kiếm ngữ nghĩa
Bây giờ, chúng ta sẽ kiểm thử trường hợp sử dụng chính xác trong tình huống của mình: tìm kỹ năng y tế bằng từ khoá "medic" (y tế).
👉 Tìm các kỹ năng tương tự như "medic":
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
s.name AS skill_name,
s.category,
COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;
- Chuyển đổi cụm từ tìm kiếm "bác sĩ" của người dùng thành một mục nhúng
- Lưu trữ trong bảng tạm thời
query_embedding
Kết quả dự kiến (khoảng cách càng nhỏ = càng giống nhau):

7. Tạo mô hình Gemini để phân tích

👉 Tạo tệp đối chiếu mô hình AI tạo sinh (thay thế $YOUR_PROJECT_ID bằng mã dự án thực tế của bạn):
CREATE OR REPLACE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
default_batch_size = 1
);
Sự khác biệt so với mô hình nhúng:
- Nhúng: Văn bản → Vectơ (để tìm kiếm theo độ tương đồng)
- Gemini: Văn bản → Văn bản do AI tạo (để suy luận/phân tích)

8. Dùng Gemini để phân tích khả năng tương thích
👉 Phân tích các cặp người sống sót để tìm ra sự tương thích với nhiệm vụ:
WITH PairData AS (
SELECT
s1.name AS Name_A,
s2.name AS Name_B,
CONCAT(
"Assess compatibility of these two survivors for a resource-gathering mission. ",
"Survivor 1: ", s1.name, ". ",
"Survivor 2: ", s2.name, ". ",
"Give a score from 1-10 and a 1-sentence reason."
) AS prompt
FROM Survivors s1
JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
LIMIT 1
)
SELECT
Name_A,
Name_B,
content AS ai_assessment
FROM ML.PREDICT(
MODEL GeminiPro,
(SELECT Name_A, Name_B, prompt FROM PairData)
);
Kết quả đầu ra dự kiến:
Name_A | Name_B | ai_assessment
----------------|-------------------|----------------
"David Chen" | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."
6. 🚀 Xây dựng tác nhân Graph RAG bằng tính năng tìm kiếm kết hợp
1. Tổng quan về cấu trúc hệ thống
Phần này xây dựng một hệ thống tìm kiếm đa phương thức giúp nhân viên hỗ trợ của bạn linh hoạt xử lý nhiều loại truy vấn. Hệ thống này có 3 lớp: Lớp tác nhân, Lớp công cụ, Lớp dịch vụ.

Tại sao lại có 3 lớp?
- Tách biệt các mối quan ngại: Tác nhân tập trung vào ý định, công cụ tập trung vào giao diện, dịch vụ tập trung vào việc triển khai
- Tính linh hoạt: Tác nhân có thể buộc sử dụng các phương thức cụ thể hoặc cho phép AI tự động định tuyến
- Tối ưu hoá: Có thể bỏ qua quy trình phân tích tốn kém bằng AI khi đã biết phương thức
Trong phần này, bạn sẽ chủ yếu triển khai tính năng tìm kiếm ngữ nghĩa (RAG) – tìm kết quả theo ý nghĩa chứ không chỉ theo từ khoá. Sau đó, chúng tôi sẽ giải thích cách tìm kiếm kết hợp kết hợp nhiều phương thức.
2. Triển khai dịch vụ RAG
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py
Tìm bình luận # TODO: REPLACE_SQL
Thay thế toàn bộ dòng này bằng đoạn mã sau:
# This is your working query from the successful run!
sql = """
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT @query AS content)
)
)
SELECT
s.survivor_id,
s.name AS survivor_name,
s.biome,
sk.skill_id,
sk.name AS skill_name,
sk.category,
COSINE_DISTANCE(
sk.skill_embedding,
(SELECT val FROM query_embedding)
) AS distance
FROM Survivors s
JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
JOIN Skills sk ON shs.skill_id = sk.skill_id
WHERE sk.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT @limit
"""
3. Định nghĩa về công cụ tìm kiếm ngữ nghĩa
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py
Trong hybrid_search_tools.py, hãy tìm nhận xét # TODO: REPLACE_SEMANTIC_SEARCH_TOOL
👉Thay thế toàn bộ dòng này bằng đoạn mã sau:
async def semantic_search(query: str, limit: int = 10) -> str:
"""
Force semantic (RAG) search using embeddings.
Use this when you specifically want to find things by MEANING,
not just matching keywords. Great for:
- Finding conceptually similar items
- Handling vague or abstract queries
- When exact terms are unknown
Example: "healing abilities" will find "first aid", "surgery",
"herbalism" even though no keywords match exactly.
Args:
query: What you're looking for (describe the concept)
limit: Maximum results
Returns:
Semantically similar results ranked by relevance
"""
try:
service = _get_service()
result = service.smart_search(
query,
force_method=SearchMethod.RAG,
limit=limit
)
return _format_results(
result["results"],
result["analysis"],
show_analysis=True
)
except Exception as e:
return f"Error in semantic search: {str(e)}"
Khi tác nhân sử dụng:
- Cụm từ tìm kiếm yêu cầu sự tương đồng ("tìm nội dung tương tự như X")
- Cụm từ tìm kiếm mang tính khái niệm ("khả năng chữa lành")
- Khi việc hiểu ý nghĩa là rất quan trọng
4. Hướng dẫn ra quyết định cho nhân viên hỗ trợ (Hướng dẫn)
Trong phần định nghĩa tác nhân, hãy sao chép và dán phần liên quan đến tính năng tìm kiếm ngữ nghĩa vào phần hướng dẫn.
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Tác nhân sử dụng hướng dẫn này để chọn công cụ phù hợp:
👉Trong tệp agent.py, hãy tìm nhận xét # TODO: REPLACE_SEARCH_LOGIC, Thay thế toàn bộ dòng này bằng mã sau:
- `semantic_search`: Force RAG/embedding search
Use for: "Find similar to X", conceptual queries, unknown terminology
Example: "Find skills related to healing"
👉Tìm chú thích # TODO: ADD_SEARCH_TOOLThay thế toàn bộ dòng này bằng mã sau:
semantic_search, # Force RAG
5. Tìm hiểu cách hoạt động của tính năng Tìm kiếm kết hợp (Chỉ đọc, không cần làm gì)
Trong các bước từ 2 đến 4, bạn đã triển khai tìm kiếm ngữ nghĩa (RAG), phương thức tìm kiếm cốt lõi giúp tìm kết quả theo ý nghĩa. Nhưng có thể bạn đã nhận thấy hệ thống này được gọi là "Tìm kiếm kết hợp". Sau đây là cách các thành phần này kết hợp với nhau:
Cách hoạt động của tính năng Hợp nhất kết hợp:
Trong tệp way-back-home/level_2/backend/services/hybrid_search_service.py, khi hybrid_search() được gọi, dịch vụ sẽ chạy CẢ HAI lượt tìm kiếm và hợp nhất kết quả:
# Location: backend/services/hybrid_search_service.py
rank_kw = keyword_ranks.get(surv_id, float('inf'))
rank_rag = rag_ranks.get(surv_id, float('inf'))
rrf_score = 0.0
if rank_kw != float('inf'):
rrf_score += 1.0 / (K + rank_kw)
if rank_rag != float('inf'):
rrf_score += 1.0 / (K + rank_rag)
combined_score = rrf_score
Trong lớp học lập trình này, bạn đã triển khai thành phần tìm kiếm ngữ nghĩa (RAG), đây là nền tảng. Các phương thức từ khoá và kết hợp đã được triển khai trong dịch vụ – nhân viên hỗ trợ của bạn có thể sử dụng cả ba phương thức!
Xin chúc mừng! Bạn đã hoàn tất thành công Tác nhân RAG đồ thị bằng tính năng tìm kiếm kết hợp!
7. 🚀 Thử nghiệm tác nhân bằng ADK Web
Cách dễ nhất để kiểm thử tác nhân là sử dụng lệnh adk web. Lệnh này sẽ khởi chạy tác nhân bằng giao diện trò chuyện tích hợp sẵn.
1. Chạy tác nhân
👉💻 Chuyển đến thư mục phụ trợ (nơi xác định tác nhân của bạn) và chạy Giao diện web:
cd ~/way-back-home/level_2/backend
uv run adk web
Lệnh này khởi động tác nhân được xác định trong
agent/agent.py
và mở giao diện web để kiểm thử.
👉 Mở URL:
Lệnh này sẽ xuất ra một URL cục bộ (thường là http://127.0.0.1:8000 hoặc tương tự). Mở đường liên kết này trong trình duyệt.

Sau khi nhấp vào URL, bạn sẽ thấy Giao diện người dùng web ADK. Nhớ chọn "tác nhân" ở góc trên cùng bên trái.

2. Thử nghiệm các tính năng tìm kiếm
Tác nhân này được thiết kế để định tuyến các truy vấn của bạn một cách thông minh. Hãy thử nhập các câu lệnh sau vào cửa sổ trò chuyện để xem các phương thức tìm kiếm khác nhau hoạt động.
🧬 A. Graph RAG (Tìm kiếm ngữ nghĩa)
Tìm các mục dựa trên ý nghĩa và khái niệm, ngay cả khi từ khoá không khớp.
Cụm từ tìm kiếm thử nghiệm: (Chọn một trong các cụm từ bên dưới)
Who can help with injuries?
What abilities are related to survival?
Những điểm cần chú ý:
- Lý do phải đề cập đến tính năng tìm kiếm Ngữ nghĩa hoặc RAG.
- Bạn sẽ thấy các kết quả có liên quan về mặt khái niệm (ví dụ: "Phẫu thuật" khi hỏi về "Sơ cứu").
- Kết quả sẽ có biểu tượng 🧬.
B. Tìm kiếm kết hợp
Kết hợp bộ lọc từ khoá với khả năng hiểu ngữ nghĩa cho các truy vấn phức tạp.
Cụm từ tìm kiếm thử nghiệm:(Chọn một trong các cụm từ bên dưới)
Find someone who can fly a plane in the volcanic area
Who has healing abilities in the FOSSILIZED?
Who has healing abilities in the mountains?
Những điểm cần chú ý:
- Lý do phải đề cập đến tính năng tìm kiếm Kết hợp.
- Kết quả phải khớp với CẢ HAI tiêu chí (khái niệm + vị trí/danh mục).
- Kết quả tìm được bằng cả hai phương thức sẽ có biểu tượng 🔀 và được xếp hạng cao nhất.
👉💻 Khi bạn thử nghiệm xong, hãy kết thúc quy trình bằng cách nhấn Ctrl+C trong dòng lệnh.
8. 🚀 Chạy toàn bộ ứng dụng
Tổng quan về cấu trúc Full Stack

Thêm SessionService và Runner
👉💻 Trong dòng lệnh, hãy mở tệp chat.py trong Trình chỉnh sửa Cloud Shell bằng cách chạy lệnh sau (đảm bảo bạn đã nhấn tổ hợp phím "ctrl+C" để kết thúc quy trình trước đó trước khi tiếp tục):
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉Trong tệp chat.py, hãy tìm nhận xét # TODO: REPLACE_INMEMORY_SERVICES, Thay thế toàn bộ dòng này bằng mã sau:
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService()
👉Trong tệp chat.py, hãy tìm nhận xét # TODO: REPLACE_RUNNER, Thay thế toàn bộ dòng này bằng mã sau:
runner = Runner(
agent=root_agent,
session_service=session_service,
memory_service=memory_service,
app_name="survivor-network"
)
1. Bắt đầu đăng ký
Nếu thiết bị đầu cuối trước đó vẫn đang chạy, hãy kết thúc bằng cách nhấn Ctrl+C.
👉💻 Khởi động ứng dụng:
cd ~/way-back-home/level_2/
./start_app.sh
Khi khởi động thành công phần phụ trợ, bạn sẽ thấy Local: http://localhost:5173/" như bên dưới: 
👉 Nhấp vào Local: http://localhost:5173/ trong dòng lệnh.

2. Thử nghiệm tính năng Tìm kiếm ngữ nghĩa
Cụm từ tìm kiếm:
Find skills similar to healing

Điều gì xảy ra:
- Tác nhân nhận ra yêu cầu về sự tương đồng
- Tạo vectơ nhúng cho "healing" (chữa lành)
- Sử dụng khoảng cách cosin để tìm các kỹ năng tương tự về mặt ngữ nghĩa
- Trả về: sơ cứu (mặc dù tên không khớp với "chữa lành")
3. Thử nghiệm tính năng Tìm kiếm kết hợp
Cụm từ tìm kiếm:
Find medical skills in the mountains
Điều gì xảy ra:
- Thành phần từ khoá: Lọc theo
category='medical' - Thành phần ngữ nghĩa: Nhúng "y tế" và xếp hạng theo mức độ tương đồng
- Hợp nhất: Kết hợp các kết quả, ưu tiên những kết quả tìm được bằng cả hai phương thức 🔀
Truy vấn (không bắt buộc):
Who is good at survival and in the forest?
Điều gì xảy ra:
- Kết quả tìm kiếm từ khoá:
biome='forest' - Kết quả tìm kiếm theo ngữ nghĩa: các kỹ năng tương tự như "sinh tồn"
- Kết hợp cả hai để có kết quả tốt nhất
👉💻 Khi bạn kiểm thử xong, hãy kết thúc quá trình này trong dòng lệnh bằng cách nhấn tổ hợp phím Ctrl+C.
4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location
👉💻 Chạy tập lệnh hoàn thành:
cd ~/way-back-home/level_2
./set_level_2.sh
Bây giờ, hãy mở waybackhome.dev và bạn sẽ thấy vị trí của mình đã được cập nhật. Chúc mừng bạn đã hoàn thành cấp độ 2!

9. ☕️ [Không bắt buộc] Quy trình đa phương thức (Chỉ đọc) — Lớp công cụ
Tại sao chúng ta cần một quy trình đa phương thức?
Mạng lưới sinh tồn không chỉ có văn bản. Những người sống sót tại hiện trường gửi dữ liệu phi cấu trúc trực tiếp qua cuộc trò chuyện:
- 📸 Hình ảnh: Ảnh chụp tài nguyên, mối nguy hiểm hoặc thiết bị
- 🎥 Video: Báo cáo trạng thái hoặc thông báo khẩn cấp
- 📄 Văn bản: Ghi chú hoặc nhật ký thực địa
Chúng tôi đang xử lý những tệp nào?
Không giống như bước trước (chúng ta tìm kiếm dữ liệu hiện có), ở bước này, chúng ta xử lý Tệp do người dùng tải lên. Giao diện chat.py xử lý tệp đính kèm một cách linh động:
Nguồn | Nội dung | Mục tiêu |
Tệp đính kèm của người dùng | Hình ảnh/Video/Văn bản | Thông tin cần thêm vào biểu đồ |
Bối cảnh trò chuyện | "Đây là ảnh chụp đồ dùng" | Ý định và thông tin chi tiết bổ sung |
Phương pháp theo kế hoạch: Quy trình tác nhân tuần tự
Chúng tôi sử dụng một Tác nhân tuần tự (multimedia_agent.py) để liên kết các tác nhân chuyên biệt với nhau:

Giá trị này được xác định trong backend/agent/multimedia_agent.py dưới dạng SequentialAgent.
Lớp công cụ cung cấp các chức năng mà tác nhân có thể gọi. Công cụ xử lý "cách thức" – tải tệp lên, trích xuất thực thể và lưu vào cơ sở dữ liệu.
1. Mở tệp Công cụ
👉💻 Mở tệp level_2/backend/agent/tools/extraction_tools.py hoặc nhập lệnh sau vào dòng lệnh. Mở một cửa sổ dòng lệnh mới. Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py
2. Triển khai công cụ upload_media
Công cụ này tải một tệp trên máy lên Google Cloud Storage.
👉 Trong def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]:, đoạn mã sau đây cho biết cách tải tệp lên GCS và phát hiện loại tệp:
"""
Upload media file to GCS and detect its type.
Args:
file_path: Path to the local file
survivor_id: Optional survivor ID to associate with upload
Returns:
Dict with gcs_uri, media_type, and status
"""
try:
if not file_path:
return {"status": "error", "error": "No file path provided"}
# Strip quotes if present
file_path = file_path.strip().strip("'").strip('"')
if not os.path.exists(file_path):
return {"status": "error", "error": f"File not found: {file_path}"}
gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
return {
"status": "success",
"gcs_uri": gcs_uri,
"signed_url": signed_url,
"media_type": media_type.value,
"file_name": os.path.basename(file_path),
"survivor_id": survivor_id
}
except Exception as e:
logger.error(f"Upload failed: {e}")
return {"status": "error", "error": str(e)}
3. Triển khai công cụ extract_from_media
Công cụ này là một bộ định tuyến — công cụ này kiểm tra media_type và gửi đến trình trích xuất chính xác (văn bản, hình ảnh hoặc video).
👉 Trong async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]:, đoạn mã sau đây trình bày cách trích xuất thực thể và mối quan hệ từ nội dung nghe nhìn đã tải lên.
"""
Extract entities and relationships from uploaded media.
Args:
gcs_uri: GCS URI of the uploaded file
media_type: Type of media (text/image/video)
signed_url: Optional signed URL for public/temporary access
Returns:
Dict with extraction results
"""
try:
if not gcs_uri:
return {"status": "error", "error": "No GCS URI provided"}
# Select appropriate extractor
if media_type == MediaType.TEXT.value or media_type == "text":
result = await text_extractor.extract(gcs_uri)
elif media_type == MediaType.IMAGE.value or media_type == "image":
result = await image_extractor.extract(gcs_uri)
elif media_type == MediaType.VIDEO.value or media_type == "video":
result = await video_extractor.extract(gcs_uri)
else:
return {"status": "error", "error": f"Unsupported media type: {media_type}"}
# Inject signed URL into broadcast info if present
if signed_url:
if not result.broadcast_info:
result.broadcast_info = {}
result.broadcast_info['thumbnail_url'] = signed_url
return {
"status": "success",
"extraction_result": result.to_dict(), # Return valid JSON dict instead of object
"summary": result.summary,
"entities_count": len(result.entities),
"relationships_count": len(result.relationships),
"entities": [e.to_dict() for e in result.entities],
"relationships": [r.to_dict() for r in result.relationships]
}
except Exception as e:
logger.error(f"Extraction failed: {e}")
return {"status": "error", "error": str(e)}
Thông tin chi tiết quan trọng về cách triển khai:
- Đầu vào đa phương thức: Chúng ta truyền cả câu lệnh văn bản (
_get_extraction_prompt()) và đối tượng hình ảnh đếngenerate_content. - Kết quả có cấu trúc:
response_mime_type="application/json"đảm bảo LLM trả về JSON hợp lệ, điều này rất quan trọng đối với quy trình. - Liên kết thực thể hình ảnh: Câu lệnh bao gồm các thực thể đã biết để Gemini có thể nhận diện các ký tự cụ thể.
4. Triển khai công cụ save_to_spanner
Công cụ này lưu trữ các thực thể và mối quan hệ đã trích xuất vào Spanner Graph DB.
👉 Trong def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]:, đoạn mã sau đây cho biết cách lưu các thực thể và mối quan hệ đã trích xuất vào Cơ sở dữ liệu biểu đồ Spanner.
"""
Save extracted entities and relationships to Spanner Graph DB.
Args:
extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
survivor_id: Optional survivor ID to associate with the broadcast
Returns:
Dict with save statistics
"""
try:
# Handle if extraction_result is passed as the wrapper dict from extract_from_media
result_obj = extraction_result
if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
result_obj = extraction_result['extraction_result']
# If result_obj is a dict (from to_dict()), reconstruct it
if isinstance(result_obj, dict):
from extractors.base_extractor import ExtractionResult
result_obj = ExtractionResult.from_dict(result_obj)
if not result_obj:
return {"status": "error", "error": "No extraction result provided"}
stats = spanner_service.save_extraction_result(result_obj, survivor_id)
return {
"status": "success",
"entities_created": stats['entities_created'],
"entities_existing": stats['entities_found_existing'],
"relationships_created": stats['relationships_created'],
"broadcast_id": stats['broadcast_id'],
"errors": stats['errors'] if stats['errors'] else None
}
except Exception as e:
logger.error(f"Spanner save failed: {e}")
return {"status": "error", "error": str(e)}
Bằng cách cung cấp cho tác nhân các công cụ cấp cao, chúng tôi đảm bảo tính toàn vẹn của dữ liệu đồng thời tận dụng khả năng suy luận của tác nhân.
5. Cập nhật dịch vụ GCS
GCSService xử lý việc tải tệp thực tế lên Google Cloud Storage.
👉💻 Mở tệp level_2/backend/services/gcs_service.py hoặc bạn có thể nhập vào dòng lệnh để mở tệp trong Trình chỉnh sửa Cloud Shell:
cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py
👉 Trong def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]:, đoạn mã sau đây cho biết cách lưu các thực thể và mối quan hệ đã trích xuất vào Cơ sở dữ liệu biểu đồ Spanner.
blob = self.bucket.blob(blob_name)
blob.upload_from_filename(file_path)
Bằng cách trừu tượng hoá việc này thành một dịch vụ, Tác nhân không cần biết về bộ chứa GCS, tên blob hoặc cách tạo URL đã ký. Nó chỉ yêu cầu "tải lên".
6. Tại sao quy trình làm việc dựa trên tác nhân > Phương pháp truyền thống?
Lợi thế của tác nhân:
Tính năng | Quy trình xử lý theo lô | Dựa trên sự kiện | Quy trình làm việc dựa trên tác nhân |
Độ phức tạp | Thấp (1 tập lệnh) | Cao (hơn 5 dịch vụ) | Thấp (1 tệp Python: |
Quản lý trạng thái | Biến toàn cục | Cứng (tách rời) | Hợp nhất (Trạng thái tác nhân) |
Xử lý lỗi | Sự cố | Nhật ký không có âm thanh | Tương tác ("Tôi không đọc được tệp đó") |
Ý kiến phản hồi của người dùng | Bản in trên bảng điều khiển | Cần thăm dò ý kiến | Tức thì (Một phần của cuộc trò chuyện) |
Khả năng thích ứng | Logic cố định | Hàm cứng nhắc | Thông minh (LLM quyết định bước tiếp theo) |
Nhận biết bối cảnh | Không có | Không có | Đầy đủ (Biết ý định của người dùng) |
Tầm quan trọng: Bằng cách sử dụng multimedia_agent.py (một SequentialAgent có 4 tác nhân phụ: Tải lên → Trích xuất → Lưu → Tóm tắt), chúng ta thay thế cơ sở hạ tầng phức tạp VÀ các tập lệnh dễ hỏng bằng logic ứng dụng thông minh, có khả năng trò chuyện.
10. ☕️ [Không bắt buộc] Quy trình đa phương thức (Chỉ đọc) — Lớp tác nhân
Lớp tác nhân xác định trí tuệ – các tác nhân sử dụng công cụ để hoàn thành nhiệm vụ. Mỗi tác nhân có một vai trò cụ thể và truyền bối cảnh cho tác nhân tiếp theo. Dưới đây là sơ đồ cấu trúc của hệ thống nhiều tác nhân.

1. Mở tệp tác nhân
👉💻 Mở tệp level_2/backend/agent/multimedia_agent.py hoặc nhập lệnh sau vào dòng lệnh. Mở một cửa sổ dòng lệnh mới. Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
2. Xác định tác nhân tải lên
Tác nhân này trích xuất đường dẫn tệp từ tin nhắn của người dùng và tải tệp đó lên GCS.
👉Trong tệp multimedia_agent.py, với đoạn mã sau, tệp này sẽ tạo upload_agent tải lên GCS:
upload_agent = LlmAgent(
name="UploadAgent",
model="gemini-2.5-flash",
instruction="""Extract the file path from the user's message and upload it.
Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.
Return the upload result with gcs_uri and media_type.""",
tools=[upload_media],
output_key="upload_result"
)
3. Xác định Tác nhân trích xuất
Tác nhân này "nhìn thấy" nội dung nghe nhìn đã tải lên và trích xuất dữ liệu có cấu trúc bằng Gemini Vision.
👉Trong tệp multimedia_agent.py, đoạn mã sau đây sẽ tạo extraction_agent để trích xuất thông tin từ nội dung nghe nhìn đã tải lên:
extraction_agent = LlmAgent(
name="ExtractionAgent",
model="gemini-2.5-flash",
instruction="""Extract information from the uploaded media.
Previous step result: {upload_result}
Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].
Return the extraction results including entities and relationships found.""",
tools=[extract_from_media],
output_key="extraction_result"
)
Hãy lưu ý cách instruction tham chiếu đến {upload_result} — đây là cách trạng thái được truyền giữa các tác nhân trong ADK.
4. Xác định Tác nhân Spanner
Tác nhân này lưu các thực thể và mối quan hệ đã trích xuất vào cơ sở dữ liệu đồ thị.
👉Trong tệp multimedia_agent.py, với đoạn mã sau, tệp này sẽ tạo spanner_agent để lưu thông tin đã trích xuất vào cơ sở dữ liệu:
spanner_agent = LlmAgent(
name="SpannerAgent",
model="gemini-2.5-flash",
instruction="""Save the extracted information to the database.
Upload result: {upload_result}
Extraction result: {extraction_result}
Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.
Return the save statistics.""",
tools=[save_to_spanner],
output_key="spanner_result"
)
Tác nhân này nhận bối cảnh từ cả hai bước trước (upload_result và extraction_result).
5. Xác định Tác nhân tóm tắt
Tác nhân này tổng hợp kết quả từ tất cả các bước trước đó thành một câu trả lời thân thiện với người dùng.
👉Trong tệp multimedia_agent.py, đoạn mã sau đây xác định câu lệnh cho summary_agent để tóm tắt kết quả:
USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""
summary_instruction = f"""Provide a user-friendly summary of the media processing.
Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}
Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}
Be concise but informative."""
Tác nhân này không cần công cụ, mà chỉ đọc bối cảnh được chia sẻ và tạo một bản tóm tắt rõ ràng cho người dùng.
🧠 Tóm tắt về cấu trúc
Lớp | Tệp | Trách nhiệm |
Công cụ |
| Cách thực hiện — Tải lên, trích xuất, lưu |
Tác nhân |
| What — Sắp xếp quy trình |
11. 🚀 Quy trình xử lý dữ liệu đa phương thức — Điều phối
Cốt lõi của hệ thống mới là MultimediaExtractionPipeline được xác định trong backend/agent/multimedia_agent.py. Ứng dụng này sử dụng mẫu Tác nhân tuần tự trong ADK (Bộ công cụ phát triển tác nhân).
1. Tại sao nên sử dụng quảng cáo tuần tự?
Quá trình xử lý tệp tải lên là một chuỗi phụ thuộc tuyến tính:
- Bạn không thể trích xuất dữ liệu cho đến khi có tệp (Tải lên).
- Bạn không thể lưu dữ liệu cho đến khi trích xuất dữ liệu (Trích xuất).
- Bạn không thể tóm tắt cho đến khi có kết quả (Lưu).
SequentialAgent là lựa chọn hoàn hảo cho việc này. Hàm này truyền kết quả đầu ra của một tác nhân dưới dạng ngữ cảnh/dữ liệu đầu vào cho tác nhân tiếp theo.
2. Định nghĩa về tác nhân
Hãy xem cách quy trình được tập hợp ở cuối multimedia_agent.py: 👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
Nút này nhận dữ liệu đầu vào từ cả hai bước trước đó. Tìm nhận xét # TODO: REPLACE_ORCHESTRATION. Thay thế toàn bộ dòng này bằng đoạn mã sau:
sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]
3. Kết nối với Tác nhân gốc
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Tìm nhận xét # TODO: REPLACE_ADD_SUBAGENT. Thay thế toàn bộ dòng này bằng đoạn mã sau:
sub_agents=[multimedia_agent],
Đối tượng duy nhất này kết hợp hiệu quả bốn "chuyên gia" thành một thực thể có thể gọi.
4. Luồng dữ liệu giữa các tác nhân
Mỗi tác nhân lưu trữ kết quả đầu ra của mình trong một bối cảnh dùng chung mà các tác nhân tiếp theo có thể truy cập:

5. Mở ứng dụng (bỏ qua nếu ứng dụng vẫn đang chạy)
👉💻 Khởi động ứng dụng:
cd ~/way-back-home/level_2/
./start_app.sh
👉 Nhấp vào Local: http://localhost:5173/ trong dòng lệnh.
6. Tải hình ảnh thử nghiệm lên
👉 Trong giao diện trò chuyện, hãy chọn một bức ảnh bất kỳ tại đây rồi tải lên giao diện người dùng:
Trong giao diện trò chuyện, hãy cho tác nhân biết bối cảnh cụ thể của bạn:
Here is the survivor note
Sau đó, hãy đính kèm hình ảnh tại đây.


👉💻 Trong dòng lệnh, khi bạn kiểm thử xong, hãy nhấn "Ctrl+C" để kết thúc quy trình.
6. Xác minh việc tải dữ liệu đa phương thức lên bộ chứa GCS
- Mở Google Cloud Console Storage.
- Chọn "bộ chứa" trong bộ nhớ trên đám mây

- Chọn bộ chứa của bạn rồi nhấp vào
media.

- Xem hình ảnh bạn đã tải lên tại đây.

7. Xác minh tính năng tải đa phương thức lên trong Spanner (Không bắt buộc)
Dưới đây là kết quả mẫu trong giao diện người dùng cho test_photo1.
- Mở Google Cloud Console Spanner.
- Chọn phiên bản:
Survivor Network - Chọn cơ sở dữ liệu của bạn:
graph-db - Trong thanh bên trái, hãy nhấp vào Spanner Studio
👉 Trong Spanner Studio, hãy truy vấn dữ liệu mới:
SELECT
s.name AS Survivor,
s.role AS Role,
b.name AS Biome,
r.name AS FoundResource,
s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;
Chúng ta có thể xác minh bằng cách xem kết quả bên dưới:

12. ☕️ [Không bắt buộc] Ngân hàng bộ nhớ có Công cụ tác nhân
1. Cách hoạt động của tính năng Bộ nhớ
Hệ thống sử dụng phương pháp bộ nhớ kép để xử lý cả bối cảnh tức thời và quá trình học tập dài hạn.

2. Chủ đề kỷ niệm là gì?
Chủ đề bộ nhớ xác định danh mục thông tin mà tác nhân nên ghi nhớ trong các cuộc trò chuyện. Hãy coi các không gian tên này như trang tổ chức tệp cho nhiều loại lựa chọn ưu tiên của người dùng.
2 chủ đề của chúng ta:
search_preferences: Cách người dùng muốn tìm kiếm- Họ thích tìm kiếm theo từ khoá hay tìm kiếm theo ngữ nghĩa?
- Họ thường tìm kiếm những kỹ năng/quần xã sinh vật nào?
- Ví dụ về thông tin ghi nhớ: "Người dùng thích tìm kiếm theo ngữ nghĩa về các kỹ năng y tế"
urgent_needs_context: Những cuộc khủng hoảng mà họ đang theo dõi- Họ đang giám sát những tài nguyên nào?
- Họ lo lắng cho những người sống sót nào?
- Ví dụ về thông tin ghi nhớ: "Người dùng đang theo dõi tình trạng thiếu thuốc ở Trại phía Bắc"
3. Thiết lập chủ đề cho kỷ niệm
Chủ đề bộ nhớ tuỳ chỉnh xác định những gì tác nhân nên ghi nhớ. Các chế độ này được định cấu hình khi triển khai Công cụ tác nhân.
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py
Thao tác này sẽ mở ~/way-back-home/level_2/backend/deploy_agent.py trong trình chỉnh sửa.
Chúng ta xác định các đối tượng MemoryTopic có cấu trúc để hướng dẫn LLM về thông tin cần trích xuất và lưu.
👉Trong tệp deploy_agent.py, hãy thay thế # TODO: SET_UP_TOPIC bằng nội dung sau:
# backend/deploy_agent.py
custom_topics = [
# Topic 1: Survivor Search Preferences
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="search_preferences",
description="""Extract the user's preferences for how they search for survivors. Include:
- Preferred search methods (keyword, semantic, direct lookup)
- Common filters used (biome, role, status)
- Specific skills they value or frequently look for
- Geographic areas of interest (e.g., "forest biome", "mountain outpost")
Example: "User prefers semantic search for finding similar skills."
Example: "User frequently checks for survivors in the Swamp Biome."
""",
)
),
# Topic 2: Urgent Needs Context
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="urgent_needs_context",
description="""Track the user's focus on urgent needs and resource shortages. Include:
- Specific resources they are monitoring (food, medicine, ammo)
- Critical situations they are tracking
- Survivors they are particularly concerned about
Example: "User is monitoring the medicine shortage in the Northern Camp."
Example: "User is looking for a doctor for the injured survivors."
""",
)
)
]
4. Tích hợp tác nhân
Mã tác nhân phải nhận biết được Ngân hàng bộ nhớ để lưu và truy xuất thông tin.
👉💻 Trong dòng lệnh, hãy mở tệp trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
Thao tác này sẽ mở ~/way-back-home/level_2/backend/agent/agent.py trong trình chỉnh sửa.
Tạo tác nhân
Khi tạo tác nhân, chúng ta truyền after_agent_callback để đảm bảo các phiên được lưu vào bộ nhớ sau khi tương tác. Hàm add_session_to_memory chạy không đồng bộ để tránh làm chậm phản hồi của cuộc trò chuyện.
👉Trong tệp agent.py, hãy tìm nhận xét # TODO: REPLACE_ADD_SESSION_MEMORY, Thay thế toàn bộ dòng này bằng mã sau:
async def add_session_to_memory(
callback_context: CallbackContext
) -> Optional[types.Content]:
"""Automatically save completed sessions to memory bank in the background"""
if hasattr(callback_context, "_invocation_context"):
invocation_context = callback_context._invocation_context
if invocation_context.memory_service:
# Use create_task to run this in the background without blocking the response
asyncio.create_task(
invocation_context.memory_service.add_session_to_memory(
invocation_context.session
)
)
logger.info("Scheduled session save to memory bank in background")
Lưu ở chế độ nền
👉Trong tệp agent.py, hãy tìm nhận xét # TODO: REPLACE_ADD_MEMORY_BANK_TOOL, Thay thế toàn bộ dòng này bằng mã sau:
if USE_MEMORY_BANK:
agent_tools.append(PreloadMemoryTool())
👉Trong tệp agent.py, hãy tìm nhận xét # TODO: REPLACE_ADD_CALLBACK, Thay thế toàn bộ dòng này bằng mã sau:
after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None
Thiết lập Vertex AI Session Service
👉💻 Trong dòng lệnh, hãy mở tệp chat.py trong Trình chỉnh sửa Cloud Shell bằng cách chạy:
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉Trong tệp chat.py, hãy tìm nhận xét # TODO: REPLACE_VERTEXAI_SERVICES, Thay thế toàn bộ dòng này bằng mã 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
)
13. ☕️ [Không bắt buộc] Đính kèm tác nhân với Công cụ tác nhân
1. Thiết lập và triển khai
Trước khi thử nghiệm các tính năng bộ nhớ, bạn cần triển khai tác nhân có các chủ đề bộ nhớ mới và đảm bảo môi trường của bạn được định cấu hình chính xác.
Chúng tôi đã cung cấp một tập lệnh tiện lợi để xử lý quy trình này.
Chạy tập lệnh triển khai
👉💻 Trong dòng lệnh, hãy chạy tập lệnh triển khai:
cd ~/way-back-home/level_2
./deploy_and_update_env.sh
Tập lệnh này thực hiện những thao tác sau:
- Chạy
backend/deploy_agent.pyđể đăng ký tác nhân và chủ đề bộ nhớ với Vertex AI. - Ghi lại Mã nhận dạng công cụ của nhân viên hỗ trợ mới.
- Tự động cập nhật tệp
.envcủa bạn bằngAGENT_ENGINE_ID. - Đảm bảo bạn đã đặt
USE_MEMORY_BANK=TRUEtrong tệp.env.
[!IMPORTANT] Nếu thay đổi custom_topics trong deploy_agent.py, bạn phải chạy lại tập lệnh này để cập nhật Công cụ tác nhân.
Xác minh ngân hàng bộ nhớ
Giờ đây, bạn có thể xác minh rằng ngân hàng bộ nhớ đang hoạt động bằng cách dạy cho tác nhân một lựa chọn ưu tiên và kiểm tra xem lựa chọn đó có được lưu giữ qua các phiên hay không.
Bước 1. Mở ứng dụng
Mở lại Ứng dụng bằng cách làm theo hướng dẫn bên dưới: Nếu thiết bị đầu cuối trước đó vẫn đang chạy, hãy kết thúc bằng cách nhấn Ctrls+C.
👉💻 Khởi động ứng dụng:
cd ~/way-back-home/level_2/
./start_app.sh
👉 Nhấp vào Local: http://localhost:5173/ trong dòng lệnh.
Bước 2. Thử nghiệm Ngân hàng bộ nhớ bằng văn bản
Trong giao diện trò chuyện, hãy cho tác nhân biết bối cảnh cụ thể của bạn:
"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."
👉 Chờ khoảng 30 giây để kỷ niệm được xử lý ở chế độ nền.
Bước 3. Bắt đầu một phiên mới
Làm mới trang để xoá nhật ký trò chuyện hiện tại (bộ nhớ ngắn hạn).
Đặt câu hỏi dựa trên bối cảnh bạn đã cung cấp trước đó:
"What kind of missions am I interested in?"
Câu trả lời dự kiến:
"Dựa trên các cuộc trò chuyện trước đây của bạn, bạn quan tâm đến:
- Nhiệm vụ cứu hộ y tế
- Hoạt động trên núi/ở độ cao lớn
- Kỹ năng cần thiết: sơ cứu, leo núi
Bạn có muốn tôi tìm những người sống sót đáp ứng các tiêu chí này không?"
Bước 4. Kiểm thử bằng tính năng tải hình ảnh lên
Tải một hình ảnh lên rồi hỏi:
remember this
Bạn có thể chọn bất kỳ ảnh nào ở đây hoặc ảnh của riêng bạn rồi tải lên giao diện người dùng:
Bước 5. Xác minh trong Vertex AI Agent Engine
Chuyển đến Google Cloud Console Agent Engine
- Hãy nhớ chọn dự án trong bộ chọn dự án ở trên cùng bên trái:

- Xác minh công cụ tác nhân mà bạn vừa triển khai bằng lệnh trước đó
use_memory_bank.sh:
Nhấp vào công cụ tác nhân mà bạn vừa tạo. - Nhấp vào thẻ
Memoriestrong tác nhân đã triển khai này để xem tất cả bộ nhớ tại đây.
👉💻 Khi bạn kiểm thử xong, trong dòng lệnh, hãy nhấp vào "Ctrl + C" để kết thúc quy trình.
🎉 Xin chúc mừng! Bạn vừa đính kèm kho lưu trữ bộ nhớ vào tác nhân của mình!
14. ☕️ [Không bắt buộc] Triển khai lên Cloud Run
1. Chạy tập lệnh triển khai
👉💻 Chạy tập lệnh triển khai:
cd ~/way-back-home/level_2
./deploy_cloud_run.sh
Sau khi triển khai thành công, bạn sẽ có URL. Đây là URL đã triển khai cho bạn! 
👉💻 Trước khi lấy URL, hãy cấp quyền bằng cách chạy lệnh:
source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker
Chuyển đến URL đã triển khai và bạn sẽ thấy ứng dụng của mình hoạt động tại đó!
2. Tìm hiểu về quy trình xây dựng
Tệp cloudbuild.yaml xác định các bước tuần tự sau:
- Backend Build (Bản dựng phần phụ trợ): Tạo hình ảnh Docker từ
backend/Dockerfile. - Backend Deploy: Triển khai vùng chứa phụ trợ cho Cloud Run.
- Capture URL (Ghi lại URL): Lấy URL phụ trợ mới.
- Bản dựng giao diện người dùng:
- Cài đặt các phần phụ thuộc.
- Tạo ứng dụng React, chèn
VITE_API_URL=.
- Frontend Image: Tạo hình ảnh Docker từ
frontend/Dockerfile(đóng gói các thành phần tĩnh). - Frontend Deploy (Triển khai giao diện người dùng): Triển khai vùng chứa giao diện người dùng.
3. Xác minh quá trình triển khai
Sau khi quá trình tạo bản dựng hoàn tất (kiểm tra đường liên kết đến nhật ký do tập lệnh cung cấp), bạn có thể xác minh:
- Chuyển đến Cloud Run Console.
- Tìm dịch vụ
survivor-frontend. - Nhấp vào URL để mở ứng dụng.
- Thực hiện cụm từ tìm kiếm để đảm bảo giao diện người dùng có thể giao tiếp với phần phụ trợ.
(KHÔNG BẮT BUỘC) 4. Triển khai thủ công
Nếu bạn muốn chạy các lệnh theo cách thủ công hoặc muốn hiểu rõ hơn về quy trình này, thì sau đây là cách sử dụng trực tiếp cloudbuild.yaml.
Đang viết cloudbuild.yaml
Tệp cloudbuild.yaml cho Google Cloud Build biết các bước cần thực hiện.
- steps: Danh sách các hành động tuần tự. Mỗi bước chạy trong một vùng chứa (ví dụ:
docker,gcloud,node,bash). - substitutions: Các biến có thể được truyền vào thời điểm tạo bản dựng (ví dụ:
$_REGION). - workspace: Thư mục dùng chung nơi các bước có thể chia sẻ tệp (như cách chúng ta chia sẻ
backend_url.txt).
Chạy quá trình triển khai
Để triển khai theo cách thủ công mà không cần tập lệnh, hãy sử dụng lệnh gcloud builds submit. Bạn PHẢI truyền các biến thay thế bắt buộc.
# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1
gcloud builds submit --config cloudbuild.yaml \
--project "$PROJECT_ID" \
--substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"
15. Kết luận
1. Sản phẩm bạn đã tạo
✅ Cơ sở dữ liệu đồ thị: Spanner với các nút (người sống sót, kỹ năng) và cạnh (mối quan hệ)
✅ Tìm kiếm bằng AI: Tìm kiếm theo từ khoá, ngữ nghĩa và kết hợp với các mục nhúng
✅ Quy trình đa phương thức: Trích xuất thực thể từ hình ảnh/video bằng Gemini
✅ Hệ thống đa tác nhân: Quy trình làm việc phối hợp với ADK
✅ Ngân hàng bộ nhớ: Cá nhân hoá dài hạn bằng Vertex AI
✅ Triển khai chính thức: Cloud Run + Công cụ tác nhân
2. Tóm tắt về cấu trúc

3. Kiến thức quan trọng cần ghi nhớ
- Graph RAG: Kết hợp cấu trúc cơ sở dữ liệu đồ thị với các vectơ nhúng ngữ nghĩa để tìm kiếm thông minh
- Mô hình nhiều tác nhân: Quy trình tuần tự cho các quy trình công việc phức tạp, nhiều bước
- AI đa phương thức: Trích xuất dữ liệu có cấu trúc từ nội dung nghe nhìn không có cấu trúc (hình ảnh/video)
- Tác nhân có trạng thái: Ngân hàng bộ nhớ cho phép cá nhân hoá trên nhiều phiên
4. Nội dung hội thảo
- Level0: Xác định danh tính
- Level1: Vị trí chính xác
- Level2 This One: Xây dựng tác nhân AI đa phương thức bằng Graph RAG, ADK và Ngân hàng bộ nhớ
- Level3: Xây dựng tác nhân truyền trực tuyến hai chiều ADK
- Level4: Hệ thống nhiều tác nhân hai chiều trực tiếp
- Level5: Kiến trúc hướng sự kiện với Google ADK, A2A và Kafka