1. Giới thiệu
Tuần đầu tiên hỏi ai nói gì về các hoạt động. Tuần thứ hai đặt ra câu hỏi ai quyết định nội dung sẽ chạy tiếp theo. Tuần thứ ba hỏi những gì còn lại sau một lần chạy. Tuần này, cuộc trò chuyện kết thúc và câu hỏi đặt ra là điều gì sẽ tồn tại sau đó. Hoá ra loại nội dung sẽ quyết định nơi nội dung đó được lưu trữ.
Kho lưu trữ là nơi mà thung lũng xuất hiện khi có vấn đề xảy ra. Một tháp ghi lại mọi thứ và Vesper, người lưu trữ, tại bàn ở tầng trệt. Đèn lồng của bạn sẽ tắt vào ban đêm. Bạn hãy đi hỏi.
Cô ấy là người bạn đồng hành tốt. Một tháng sau, cô ấy cũng rất vui khi gặp bạn.
Bản ghi không phải là kỷ niệm.
Câu đó là toàn bộ nội dung của lớp học lập trình. Bạn sẽ leo lên chiếc thang này theo 4 bậc, mỗi bậc là một tầng của tháp:
rung | sàn nhà | những gì mà nó ghi nhớ | what keeps it |
1 | bàn làm việc và tầng 1 | lượt truy cập này |
|
2 | tầng 2, ngăn kéo của bạn | khách truy cập này | tiền tố |
3 | tầng 3, toà tháp | những gì đã nói | Ngân hàng bộ nhớ Vertex AI |
4 | tầng 4, mùa | toàn bộ thung lũng | BigQuery |
Mỗi nấc thang đều có được là do một điều gì đó đã rơi ra khỏi nấc thang bên dưới.
Bạn đã biết 5 cách quên của người lưu trữ, vì bạn đã từng gặp phải tất cả những cách này trong một cuộc gọi hỗ trợ:
những gì cô ấy nói | đã xảy ra lỗi | |
~~1~~ | ~~Bạn có thể cho tôi biết lại thông tin tham khảo đó không?~~ | ~~forgot within one conversation~~ – week three fixed this |
~~2~~ | ~~Tôi đã chuyển cuộc gọi cho bạn. Vui lòng bắt đầu lại từ đầu.~~ | ~~nhật ký đã bị xoá cùng với quy trình~~ – tuần thứ ba đã khắc phục vấn đề này |
3 | Chào bạn! Hôm nay tôi có thể giúp gì cho bạn? | cho người có trường hợp chưa được giải quyết từ tháng trước |
4 | Bạn có thể mô tả thiệt hại không? | lần trước cô ấy nhìn vào chiếc đèn lồng |
5 | Chúng tôi chưa từng thấy điều này trước đây. | 31 người đã hỏi trong mùa này |
Đường dây thứ ba là tuần này. Nó thất bại theo 3 cách khác nhau – một lượt truy cập mới (chương 2), một câu không có dòng nào trên phiếu (chương 3) và một kho lưu trữ chỉ tồn tại trong quy trình (chương 4) – và mỗi cách là một chương. Dòng thứ tư là dành cho bạn: look() trong archive/agent.py là nơi cô ấy đọc một dấu hiệu trên ảnh. Dòng 5 là chương 5 và không bắt buộc.
Bạn không cần tuần 1 đến tuần 3. Tác nhân là một mô hình có hướng dẫn và một số công cụ. Mọi thứ khác trong tuần này đều đã tự nói lên nhiều điều.
Bạn sẽ viết 3 dòng và mỗi dòng là một khái niệm về kỷ niệm:
đường kẻ | Định nghĩa |
| trạng thái được viết bằng mã, không phải bằng cuộc trò chuyện |
| tiền tố là một khoảng thời gian |
| chính sách thu hồi – trường này không được ghi nhớ |
Bạn có thể đọc thêm một dòng nữa – chính sách ghi, await ctx.add_events_to_memory(...) – và chương 3 là nơi bạn đọc những gì chính sách này làm trước khi viết dòng sử dụng chính sách đó.
Hai nấc còn lại không phải là nội dung chỉnh sửa: bạn xây dựng một tháp (Agent Engine lưu trữ Memory Bank) và cùng một mã kết nối với tháp đó, đồng thời bạn tải một kho dữ liệu (BigQuery), đặt một biểu đồ lên đó và giao cho cùng một tác nhân hai truy vấn được quản lý – một theo ý nghĩa, một theo mối kết nối.
Mỗi chương đều chạy cùng một vòng lặp và đây là vòng lặp mà bạn sẽ sử dụng trên các tác nhân của riêng mình: đọc mã → viết dòng → xem mã trong tháp. Không có gì bị hỏng ngay từ đầu, không có gì được khởi động lại và không có gì bị Ctrl+C: mọi nội dung chỉnh sửa đều được chọn trong tin nhắn tiếp theo và việc kết nối với tháp là một dòng trong tệp mà Archive đọc lại trên mọi yêu cầu. Tháp là một bản vẽ được vẽ lại: tháp đọc những tệp mà bạn chỉnh sửa và có 3 nút – 🌙 kết thúc ngày, 🗓 bắt đầu lượt truy cập tiếp theo, 🔥 quên bạn. Mọi thao tác khác bạn thực hiện trong mã và thiết bị đầu cuối.
Có hai nơi và chúng không bao giờ thay đổi: thẻ 1 là thiết bị đầu cuối, thẻ 2 là Kho lưu trữ. Bàn làm việc (adk web) xuất hiện đúng một lần, trong chương 1, để bạn xem trạng thái phiên thô, sau đó bạn sẽ không cần dùng đến nữa. Mỗi 👉 bên dưới đều cho biết loại nào. 👉💻 là thẻ 1, 👉🖥 là thẻ 2, 👉🔬 là băng ghế làm việc. 👉📖 là mở một tệp và đọc – không có gì thay đổi – và 👉✏️ là một loại bước chỉnh sửa. Bất cứ khi nào một bước yêu cầu bạn nói điều gì đó với Vesper, thông báo chính xác sẽ nằm trong khối ngay bên dưới bước đó – hãy sao chép thông báo đó nguyên trạng. Và một phần có tiêu đề kết thúc bằng – chỉ đọc sẽ không có gì để nhập, dán hoặc nhấp: mã trong phần đó đã có trong kho lưu trữ và đang chạy, được in để bạn đọc.
Câu ở trên cửa nhà Vesper là câu ở trên cùng. Câu kết thúc tuần này là câu kết của tuần thứ tư trong toàn bộ mùa:
Dữ kiện và lựa chọn ưu tiên thuộc về các cửa hàng khác nhau.
2. 🧰 Thiết lập
- Việc cần làm – chỉ vào một dự án hoặc dán một khoá, cài đặt và chứng minh rằng chuỗi công cụ hoạt động bình thường.
- Tại sao – không có gì được khởi động ở đây. Mọi máy chủ đều bắt đầu ngay trước bước cần đến máy chủ đó, vì vậy, khi một màn hình mở ra, bạn sẽ biết lệnh nào sở hữu màn hình đó.
- Cách thức – một tập lệnh tạo dự án, một tập lệnh cài đặt và hướng dẫn bạn sử dụng Vertex AI, đồng thời một tập lệnh kiểm tra trước khi bay đọc mã của bạn và cho bạn biết vị trí của bạn.
Mọi thứ trong lớp học này đều chạy trong Cloud Shell – Python, uv và gcloud đã được cài đặt ở đó, còn Gemini được truy cập thông qua Vertex AI bằng thông tin đăng nhập của riêng bạn. Không có khoá API ở bất kỳ đâu trong lớp học này và bạn không cần cài đặt bất cứ thứ gì trên máy tính xách tay.
Có một thứ mà phòng thí nghiệm này không thể cung cấp cho bạn: một dự án trên đám mây của Google có tính năng thanh toán. Bước 1 giúp bạn có được một tài khoản có thể thanh toán cho dự án; bước 4 biến tài khoản đó thành một dự án hoặc chọn dự án Agent Valley mà bạn đã tạo trong tuần 1, tuần 2 hoặc tuần 3. Hãy thực hiện theo thứ tự đó – mọi bước sau bước 4 đều đọc dự án mà bước 4 đã thiết lập.
1 · Tạo tài khoản có thông tin thanh toán (khoảng 1 phút)
🌐 Hãy làm việc này trước khi làm bất cứ việc gì khác. Đăng nhập bằng một Tài khoản Google đã bật tính năng thanh toán. Mọi tài khoản như vậy đều hoạt động. Nếu tài khoản của bạn không có, hãy bắt đầu dùng thử miễn phí. Việc này sẽ cung cấp cho bạn một tài khoản thanh toán, đây là tất cả những gì cần thiết cho bước 4.
2 · Mở Cloud Shell (khoảng 1 phút)
🌐 Nhấp vào Kích hoạt Cloud Shell ở đầu Cloud Console Google — đây là biểu tượng có hình dạng thiết bị đầu cuối trong tiêu đề.
🌐 Nhấp vào Open Editor (Mở trình chỉnh sửa) (biểu tượng thư mục mở có bút chì). Thao tác này sẽ mở Cloud Shell Editor với một trình khám phá tệp ở bên trái. Đây là nơi bạn làm việc bất cứ khi nào một bước được đánh dấu là 👉✏️.
🌐 Nếu bạn được nhắc uỷ quyền vào bất kỳ thời điểm nào trong hôm nay, hãy nhấp vào Uỷ quyền để tiếp tục.
🌐 Mở một thiết bị đầu cuối trong trình chỉnh sửa – đó là thẻ 1 và mọi bước 👉💻 đều chạy ở đó, trừ phi có quy định khác. Thẻ 2 là Kho lưu trữ và bạn mở thẻ này ở chương 1, ngay trước bước cần đến thẻ này. Nếu thiết bị đầu cuối chưa xuất hiện ở cuối màn hình, hãy mở thiết bị đầu cuối bằng cách chọn View → Terminal (Xem → Thiết bị đầu cuối):
🌐 Kiểm tra xem bạn đã đăng nhập bằng tài khoản nào – đó phải là tài khoản ở bước 1:
gcloud auth list
3. Nhận phòng thí nghiệm (khoảng 1 phút)
💻 Sao chép kho lưu trữ này – đây là kho lưu trữ của Archive, không phải của tuần 1, tuần 2 hay tuần 3:
cd ~
git clone https://github.com/cuppibla/agent-valley-archive
cd agent-valley-archive
4. Tạo dự án hoặc sử dụng lại dự án của tuần trước (khoảng 2 phút)
💻 Một tập lệnh sẽ tìm tài khoản thanh toán của bạn, tạo một dự án trên tài khoản đó và trỏ Cloud Shell đến dự án đó. Nếu bạn đã thực hiện tuần 1, tuần 2 hoặc tuần 3, thì hệ thống sẽ tìm thấy dự án Agent Valley trước tiên và đề nghị sử dụng lại dự án đó – hãy chọn có và bạn không cần phải nghĩ đến dự án có tính phí thứ hai:
cd ~/agent-valley-archive
./setup_project.sh
👀 Mong đợi một ✓ cho tài khoản thanh toán mà nó đã chọn, một ✓ cho dự án mà nó đã tạo hoặc sử dụng lại và một kết thúc như sau:
cd ~/agent-valley-archive
Project ready: agent-valley-4271
Next: ./setup_codelab.sh
agent-valley-4271 là mã dự án của bạn – mã dự án của bạn sẽ có các chữ số khác. Có 4 điều xảy ra trong đó:
billing | sẽ lấy tài khoản | |
project | tìm một dự án Agent Valley mà bạn đã sở hữu (của tuần 1, tuần 2 hoặc tuần 3) và đề nghị sử dụng lại dự án đó; nếu không, hãy tạo | |
chọn | ghi mã nhận dạng vào | |
waits | cho đến khi dự án thực sự được phép phân phát, trong tối đa 2 phút | |
🌐 Dự án đó hiện có trong bảng điều khiển – mã nhận dạng của dự án nằm trong thẻ Thông tin dự án trên Trang tổng quan:
5 · Cài đặt và trỏ đến Vertex AI (khoảng 3 phút)
💻 Cài đặt uv, xuất 3 biến gửi ADK đến Vertex AI và chạy thiết lập:
cd ~/agent-valley-archive
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
export GOOGLE_CLOUD_LOCATION=global
./setup_codelab.sh
$(gcloud config get project) có một giá trị cần trả về vì bước 4 đã đặt giá trị đó. Đó là lý do bước 4 được thực hiện trước.
setup_codelab.sh là hàm đẳng nhất – bạn có thể chạy lại bao nhiêu lần tuỳ ý. Thao tác này thực hiện 5 việc theo thứ tự:
api | đọc bước 4 của dự án đã chọn và bật | |
uv env |
| |
site | chạy | |
.env | ghi các biến mà phòng thí nghiệm đọc được – | |
kiểm tra mô hình | thực hiện một lệnh gọi thực đến Gemini, vì vậy, một dự án không tốt sẽ thất bại ngay tại thời điểm thiết lập, chứ không phải sau này trong một chương | |
6 · Chứng minh rằng đó là màu xanh lục (khoảng 1 phút)
💻 Chạy quy trình kiểm tra trước khi bay – mỗi dấu kiểm là một thông tin thực tế, chứ không phải là thông tin phỏng đoán:
cd ~/agent-valley-archive
uv run python scripts/preflight.py
👀 Giai đoạn kiểm tra trước khi bay sẽ đặt cho mô hình một câu hỏi để chứng minh rằng thông tin đăng nhập của bạn hoạt động, kiểm tra để đảm bảo các gói của Archive đã được đặt đúng vị trí, sau đó đọc mã của bạn và in thanh tiến trình của tuần này:
cd ~/agent-valley-archive
desk ▢ the slip · write_down writes nothing chapter 1 · EDIT ONE
floor 1 ✓ the file · SqliteSessionService chapter 1, read only
floor 2 ▢ the drawer · CASE = "case" chapter 2 · EDIT TWO
floor 3 ✓ what was said · closing time files the day chapter 3, read only
floor 3 ▢ the asking · recall never looks chapter 3 · EDIT THREE
floor 3 ▢ the tower · InMemoryMemoryService chapter 4 · built, not edited
floor 3 ✓ the rules · USER_PREFERENCES, LANTERN_CONTEXT chapter 4, read only
Ba mục đã được đánh dấu. Đó là những tin nhắn bạn chỉ đọc. Ba dòng là những dòng bạn viết; một dòng là tháp bạn xây. Chạy quy trình kiểm tra trước khi bay lại vào bất kỳ thời điểm nào trong phòng thí nghiệm và quy trình này sẽ cho bạn biết bạn đang ở đâu – quy trình này đọc các tệp của bạn chứ không phải danh sách kiểm tra.
3. Phiên, Trạng thái, SqliteSessionService
- What (Cái gì) – viết một dòng; khởi động băng ghế một lần và xem băng giấy điền vào; sau đó làm tương tự với tháp; sau đó đọc lý do tại sao băng giấy tồn tại qua đêm.
- Tại sao – điều đầu tiên cần biết về trí nhớ là không có gì được ghi nhớ một cách tự động. Có người viết nội dung đó.
- Cách thực hiện – một dòng trong
agent.py, sau đó không thay đổi gì khác.
CHỈNH SỬA MỘT
👉📖 Mở archive/agent.py và tìm write_down. Đọc đến 👉:
case = dict(tool_context.state.get(CASE, {}))
if case.get(field):
return {"already_written": {field: case[field]}}
case[field] = value
# 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
# "# " in front of the next line, then save — the slip is session state,
# and state is written by code, never by the conversation:
# tool_context.state[CASE] = case
return {"written": {field: value}}
Hàm này tạo biên nhận trong một từ điển cục bộ rồi trả về biên nhận đó – và một từ điển cục bộ sẽ kết thúc cùng với lệnh gọi. Chạy lệnh này như hiện tại và Vesper sẽ nghe thấy bạn một cách hoàn hảo: 4 lệnh gọi write_down sẽ kích hoạt, mỗi lệnh gọi sẽ trả lời "written" và trạng thái phiên vẫn trống vì không có gì đạt được trạng thái đó. Cô ấy đã nghe thấy bạn. Không có nội dung nào được viết.
👉✏️ Vẫn ở archive/agent.py, bên trong write_down: xoá # ở trước một dòng – # và dấu cách sau đó. Trước:
case[field] = value
# 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
# "# " in front of the next line, then save — the slip is session state,
# and state is written by code, never by the conversation:
# tool_context.state[CASE] = case
return {"written": {field: value}}
Sau:
case[field] = value
# 👉 EDIT ONE — chapter 1. She heard you. Nothing was written. Delete the
# "# " in front of the next line, then save — the slip is session state,
# and state is written by code, never by the conversation:
tool_context.state[CASE] = case
return {"written": {field: value}}
Lưu.
Phiếu này sẽ được điền thông tin
👉💻 Khởi động băng ghế dự bị. Đây là lần duy nhất bạn mở cửa sổ này trong phòng thí nghiệm – đây là cửa sổ duy nhất cho thấy trạng thái phiên dưới dạng JSON thô:
cd ~/agent-valley-archive
uv run adk web . --allow_origins="*"
👉🔬 Mở băng ghế dự bị bằng Web Preview → Preview on port 8000 (nút Web Preview là biểu tượng mắt trên cửa sổ ở trên cùng bên phải của Cloud Shell). Chọn lưu trữ, rồi trước khi bạn nhập nội dung, hãy nhấp vào Trạng thái trong bảng điều khiển bên trái.
👀 Trống. Chưa có ai nói gì.
👉🔬 Giờ thì hãy nói tất cả những điều này trong một tin nhắn:
Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.
👀 Bốn chip write_down sẽ kích hoạt – hãy nhấp vào một chip và đọc JSON: "written": {"no": "k7f2"}. Bây giờ, hãy nhấp lại vào Tiểu bang.
case {"no": "k7f2", "item": "lantern", "mark": "q7",
"symptom": "keeps going out at night"}
👀 Lúc trống, lúc đầy, tất cả trong một tin nhắn. Đó là những gì cô ấy nhớ được và kỷ niệm đó không xuất hiện một mình. Bạn đã viết dòng mã ghi dữ liệu đó. Đó là toàn bộ cơ chế: một hàm đơn giản ghi vào tool_context.state và một chỉ dẫn cho cô ấy biết phải sử dụng hàm này bất cứ khi nào khách truy cập nói điều gì đó phù hợp với một dòng trên tờ giấy.
👉🔬 Hỏi cô ấy:
What's my case number?
👀 k7f2. Cô ấy đọc thông tin trên tờ giấy. Nếu không có EDIT ONE, cô ấy sẽ yêu cầu bạn cung cấp thông tin này – dòng đầu tiên trong danh sách hỗ trợ, trong một cuộc trò chuyện.
Hai người bảo vệ là phiếu ghi dạng giấy: bốn dòng ngắn, mỗi dòng được viết một lần. Chúng quan trọng hơn bạn tưởng. Nếu không có những đoạn này, mô hình sẽ nhận ra rằng nó có thể đổ toàn bộ cuộc trò chuyện vào symptom, và chương 3 — chương mà toàn bộ nội dung là the slip has no line for that — sẽ lặng lẽ không còn đúng nữa. Hình dạng của một cửa hàng được thực thi bằng mã ghi hình dạng đó hoặc không được thực thi.
Bây giờ, hãy đi đến tháp
👉💻 Bạn đã hoàn thành phần thực hành trên băng ghế dự bị – hãy để phần này chạy hoặc đóng thẻ của phần này; phần còn lại của khoá học nằm trong Kho lưu trữ. Mở thẻ dòng lệnh thứ hai (thẻ 2 – Kho lưu trữ):
cd ~/agent-valley-archive
bash valley.sh
👉🖥 Mở Archive bằng Web Preview → Change port (Xem trước trên web → Thay đổi cổng), nhập 3440 rồi nhấp vào Change and Preview (Thay đổi và xem trước). 3440 không có trong danh sách nhanh của Web Preview (Xem trước trên web) – 8080 là giá trị mặc định – vì vậy, bạn phải đặt giá trị này theo cách thủ công một lần. Nhấn vào ▶ Bắt đầu, rồi nhấn vào Kho lưu trữ. Bạn đang ở ngoài cửa. Chọn người đến hỏi (tên và loài) rồi đi vào.
👀 Một toà nhà. Vesper đang ở bàn làm việc ở tầng trệt và đó là nơi bạn trò chuyện. Phía trên cô là tầng một, tầng hai, tầng ba và một gác mái tối tăm. Bốn bậc thang là bốn tầng. Linh thú của bạn đang ngồi ở tầng trệt, vì đó là nơi bạn đã leo lên. Cột bên cạnh bản vẽ cho biết từng tầng hiện có những gì – vẫn là 4 cửa hàng như trong bảng ở phần giới thiệu và theo cùng một thứ tự. Không có nút nào ở bên phải.
👉🖥 Dán 4 nội dung đó vào hộp bên dưới cuộc trò chuyện (chính xác là tin nhắn này) rồi nhấn Enter:
Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.
👀 Quan sát bàn. Phiếu này tự viết, từng dòng một – trên bản vẽ và đầy đủ dưới phiếu bên cạnh. Cùng một công cụ, cùng một trạng thái: tháp chỉ vẽ những gì write_down đã viết và sẽ tiếp tục làm như vậy trong phần còn lại của phòng thí nghiệm.
Cô ấy nhớ qua đêm – chỉ đọc
Nội dung bạn đã viết và nội dung đó là gì
đường kẻ | Định nghĩa | nơi nó tồn tại |
| trạng thái phiên – do mã viết, do chỉ dẫn đọc | không gian làm việc · |
| kho lưu trữ phiên – một lượt truy cập trong một tệp, chứ không phải trong một quy trình | tầng một · |
Thông báo này được tính là một lượt ghé thăm và vẫn còn hiệu lực sau giờ đóng cửa. Cookie này sẽ không tồn tại trong lần truy cập tiếp theo.
4. Tiểu bang của người dùng
- Điều gì – quay lại một tháng sau; tờ giấy đã biến mất. Năm nhân vật và nó theo dõi bạn.
- Lý do – một phiên hoạt động là một lượt truy cập. Lượt truy cập tiếp theo là một phiên mới và chưa từng thấy lượt truy cập trước đó.
- How (Thế nào) – 5 ký tự trong
state.py.
👉🖥 Nhấn 🗓 một tháng sau. Đó là một phiên mới cho cùng một khách truy cập – cách bắt đầu một cuộc trò chuyện mới trong tuần thứ ba.
Chào mừng bạn đến với Kho lưu trữ. Hôm nay tôi có thể giúp gì cho bạn?
👉🖥 Nhìn vào tháp. Tầng một có một cuốn sách khác – trong lần ghé thăm này. Ngăn kéo ở tầng 2 trống. Tờ giấy trên bàn đang trống.
👀 Lý do: thông tin về lượt truy cập được ghi vào trạng thái phiên và một phiên là lượt truy cập này. Thay đổi số lượt truy cập, thay đổi số phiên. Không có gì được chuyển sang vì không có gì được yêu cầu chuyển. Lần truy cập cuối cùng vẫn còn trong tệp – đó là cuốn sách đầu tiên của tầng một – nhưng phiếu mượn được viết theo một khoá chỉ tồn tại trong một lần truy cập.
CHỈNH SỬA HAI
👉✏️ Mở archive/state.py. Tìm 👉. Trước:
# 👉 EDIT TWO — chapter 2. Five characters. A key with no prefix lives for one
# visit; `user:` follows the visitor into every visit after this.
CASE = "case"
Sau:
CASE = "user:case"
Lưu. Không khởi động lại – Archive sẽ nhập lại mã của bạn trên mọi thông báo.
👉🖥 Dán lại 4 nội dung đó – chính xác là thông báo này:
Hi! My lantern keeps going out at night. My case number is k7f2, and there's a little q7 stamped on the base.
👉🖥 Sau đó, hãy nhấn lại vào 🗓 một tháng sau – vẫn là nút đó.
👀 Ngăn kéo ở tầng 2 có tên của bạn và 4 trường nằm bên trong. Mảnh giấy trên bàn vẫn là 4 dòng chữ đó – được rút ra từ ngăn kéo khi bạn bước vào. Linh thú của bạn đã lên một tầng. Cùng một khoá, mỗi lượt truy cập, một giá trị: đó là tiền tố đang thực hiện công việc của mình.
Tiền tố có hiệu lực trọn đời.
tiền tố | thời gian tồn tại | tầng nào |
(không có) | lượt truy cập này | không gian làm việc |
| mỗi lượt truy cập mà khách truy cập này thực hiện | tầng 2, ngăn kéo của bạn |
| mọi người, mãi mãi | một phần của tầng 4 |
| chỉ rẽ tại ngã tư này – thậm chí không bao giờ leo cầu thang | — |
Một bàn, bốn ngăn kéo. Chương này đề cập đến một trong số đó.
Giờ thì cô ấy đã biết bạn
👉🖥 Đây là một lượt truy cập hoàn toàn mới và bạn chưa nói gì trong lượt truy cập này. Hỏi cô ấy:
What did I bring in last time?
👀 Tôi có ghi lại rằng bạn đã mang theo một chiếc đèn lồng, mã hiệu k7f2. Đèn này được đánh dấu là q7 và bạn nói rằng đèn này thường xuyên bị tắt vào ban đêm. Mọi từ ngữ đều xuất phát từ ngăn kéo, chứ không phải cuộc trò chuyện – lượt truy cập này chỉ có một thông báo và thông báo đó không có tên. Đó là trạng thái ở cấp người dùng đang thực hiện công việc của mình: khoá user: sẽ xuất hiện trước khi khách truy cập nói một từ, trong mỗi lượt truy cập mà họ thực hiện.
Ngăn này chỉ chứa 4 dòng trên phiếu và không chứa gì khác. Những gì bạn nói mà không có dòng nào trên phiếu (những gì bạn đã thử, lý do bạn quan tâm, liệu bạn có muốn một phiếu mới hay không) sẽ không được ghi lại và một tháng sau sẽ biến mất. Ngăn kéo trải dài qua tháng. Một câu thì không. Chương 3 sẽ đề cập đến vấn đề này.
Nội dung bạn đã viết và nội dung đó là gì
đường kẻ | Định nghĩa | nơi nó tồn tại |
| tiền tố là một khoảng thời gian tồn tại – cùng một khoá, được giới hạn phạm vi cho khách truy cập thay vì lượt truy cập | tầng 2 · |
Một lần rung sẽ thông báo cho một khách truy cập. Ngăn này sẽ di chuyển theo bạn, nhưng cuộc trò chuyện thì không.
5. InMemoryMemoryService
- What (Cái gì) – đọc dòng ghi ngày, viết dòng hỏi; sau đó là một thời gian đóng cửa và một câu hỏi.
- Tại sao – phiếu này là một biểu mẫu. Biểu mẫu có các đường kẻ mà bạn đã cung cấp. Mọi người không nói theo dòng và việc ghi lại những gì họ nói chỉ là một nửa của việc ghi nhớ.
- Cách thực hiện – đọc
file; một dòng trongrecall; sau đó đọc một 🌙, một 🗓, một câu hỏi.
Những việc cô ấy làm trên đường về nhà – chỉ đọc
Không nhớ được tệp
Dòng đó sẽ đặt ngày lên kệ. Không có gì bị xoá khỏi video. Một kệ đầy thẻ cũng chẳng giúp ích gì nếu không ai xem – và khi mã được gửi đi, không ai xem: recall, nút chạy trước Vesper trên mọi câu hỏi, không yêu cầu tháp làm gì cả. Bộ nhớ mà bạn không thể nhớ lại đúng lúc không phải là ký ức mà là nhật ký. Nửa còn lại là phần bạn cần viết.
GIAI ĐOẠN 3 – đặt câu hỏi
👉📖 Trong archive/agent.py, hãy tìm recall – hàm ngay phía trên file. Đây là một nút hàm đơn giản chạy trước Vesper trên mọi câu hỏi – không phải mô hình quyết định thời điểm tìm kiếm, tức là những lần không tìm thấy thông tin cũng sẽ xuất hiện. Đọc đến 👉:
if query.strip():
try:
# 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
# the shelf and nobody is looking at them. Delete the "# " in front
# of the next line, then save:
# found = await ctx.search_memory(query)
pass
except ValueError:
# no memory service wired on this runner — degrade, do not crash
pass
👉✏️ Vẫn ở archive/agent.py, bên trong recall: xoá # ở trước một dòng – # và dấu cách sau đó. Trước:
try:
# 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
# the shelf and nobody is looking at them. Delete the "# " in front
# of the next line, then save:
# found = await ctx.search_memory(query)
pass
except ValueError:
Sau:
try:
# 👉 EDIT THREE — chapter 3. Filed is not remembered: the cards are on
# the shelf and nobody is looking at them. Delete the "# " in front
# of the next line, then save:
found = await ctx.search_memory(query)
pass
except ValueError:
Để pass ở nguyên vị trí – hiện tại, mã này không làm gì cả vì found đã là None ở trên.
Lưu. Không khởi động lại.
Hai dòng, hai chính sách và bạn đã viết một trong số đó. Chính sách ghi quyết định những gì được giữ lại và thời điểm (thời gian đóng cửa, cả ngày). Chính sách thu hồi quyết định thời điểm tìm kiếm và nội dung tìm kiếm (mọi câu hỏi, chính câu hỏi đó). ADK cung cấp cho bạn các động từ – add_events_to_memory, search_memory – và không liên quan đến chính sách. Đó là sự phân chia hợp lý và đó là lý do bạn phải viết yêu cầu.
Đến giờ đóng cửa
👉🖥 Nói 3 điều mà phiếu không có dòng nào. Một hoặc ba thông báo:
I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.
👉🖥 Sau đó, hãy nhấn vào 🌙 để kết thúc phiên hôm nay.
👀 Quan sát bàn. Ba thứ mà bạn nói nhấc khỏi tấm trượt và nổi lên, rồi hạ cánh xuống tầng 3. Trong các thẻ bên cạnh tháp, các thẻ được liệt kê – một thẻ cho mỗi tin nhắn bạn đã gửi, được đánh dấu bằng biểu tượng quote, các câu của bạn được ghi lại từng chữ và trong quá trình này ở phía trên. Đèn trên bàn vẫn sáng cho đến khi họ hạ cánh.
Một tháng sau, cô biết
👉🖥 Nhấn 🗓 một tháng sau rồi hỏi:
What have I already tried?
👀 Bạn đã thử treo cao hơn nhưng không có tác dụng. Cô ấy biết. Phiếu này không có dòng nào dành cho thông tin đó và chưa từng có, nên người rút thẻ không thể trả lời câu hỏi này; recall tìm thấy thẻ, viết thông tin đó vào ctx.state["recalled"] và hướng dẫn của cô ấy có nội dung như vậy. Chỉ có một dòng là khác biệt.
Và tất cả chỉ là trong đầu cô
Hãy xem các thẻ bên cạnh tháp: trong quy trình này. Hiện tại, bộ nhớ là InMemoryMemoryService – một từ điển bên trong bash valley.sh và tồn tại chính xác trong thời gian quy trình đó hoạt động. Tắt tháp tối nay và mở vào ngày mai: sách ở tầng một, ngăn kéo ở tầng hai và tầng ba tối om. Trường hợp này vẫn còn trong tệp. Những gì bạn nói đã được lưu lại trong quá trình đó và quá trình đó đã kết thúc.
Tính liên tục không phải là bộ nhớ.
Có hai điểm sai trong câu "tầng ba đang được xây dựng": câu này đang trong quá trình xây dựng và được diễn đạt bằng lời của bạn – một câu trích dẫn chứ không phải một dữ kiện. Chương tiếp theo sẽ khắc phục cả hai vấn đề này mà không cần mã.
Nội dung bạn đọc, nội dung bạn viết và nội dung đó là gì
đường kẻ | Định nghĩa | nơi nó tồn tại |
| chính sách ghi – cả ngày, vào thời gian đóng cửa | tầng 3 · dịch vụ bộ nhớ |
| chính sách thu hồi – mọi câu hỏi, trước khi cô ấy trả lời |
|
Rung động này sẽ ghi lại những gì đã nói và lưu trữ trong một từ điển bên trong một quy trình, bằng chính lời nói của bạn. Cả hai nửa đều sai và chương tiếp theo sẽ khắc phục cả hai mà không cần mã.
6. MemoryBank
- What (Điều gì) – một tập lệnh tạo Ngân hàng bộ nhớ; hai dòng bạn đã có bắt đầu ghi các dữ kiện vào đó và đọc lại các dữ kiện đó.
- Tại sao – dịch vụ bộ nhớ là một dịch vụ. Nơi lưu trữ là quyết định triển khai, chứ không phải quyết định của tác nhân – bạn có thể thay đổi nơi lưu trữ mà không cần tác động đến tác nhân.
- Cách thức – chạy
make_tower.py, nói 3 câu, nhấn 🌙, nhấn 🗓, đặt 1 câu hỏi. Sau đó, hãy xem xét hoạt động ghi và đọc ở chế độ chỉ đọc.
Xây tháp
Tầng 3 của chương 3 là một từ điển Python bên trong bash valley.sh. Memory Bank là phiên bản được quản lý của tầng đó: nó nằm trên một phiên bản Agent Engine trong dự án của bạn, nó lưu giữ facts (thông tin) được chắt lọc từ ngày thay vì các câu của bạn và tìm thấy chúng theo meaning (ý nghĩa) thay vì theo các từ dùng chung. Bạn không cần triển khai Vesper cho Agent Engine để sử dụng nó – một phiên bản không có gì được triển khai trên đó vẫn lưu trữ Memory Bank và đó là những gì tập lệnh xây dựng: một tháp không có người ở, chỉ có nhiệm vụ duy nhất là giữ các thẻ.
👉💻 Trong thẻ 1 (khoảng 1 phút):
cd ~/agent-valley-archive
uv run python scripts/make_tower.py
👀 Dự kiến:
building the tower in YOUR_PROJECT / us-central1 — about a minute...
built, with the two topics in archive/topics.py configured on it.
resource: projects/.../locations/us-central1/reasoningEngines/6792...
AGENT_ENGINE written to .env
Next — nothing to restart. The Archive reads .env on every message:
look at floor three — under the cards it now says Memory Bank.
(adk web, if you use it: --memory_service_uri "agentengine://projects/.../reasoningEngines/6792...")
Một lệnh gọi SDK, agent_engines.create() và một dòng được ghi vào .env. Lưu trữ sẽ đọc lại tệp đó trên mọi yêu cầu, vì vậy, bạn không cần phải khởi động lại.
Xem cách hoạt động
👉🖥 Nhìn vào tầng 3 – tháp sẽ tự vẽ lại trong vòng vài giây. Trong phần thẻ, giờ đây có dòng chữ Ngân hàng kỷ niệm và kệ trống: 3 câu trích dẫn trong chương 3 đang trong quá trình xử lý và đây không phải là quá trình đó. Đọc lại 3 câu, một tin nhắn hoặc 3 tin nhắn:
I read by it at night, so night is exactly when I need it.
I've tried hanging it higher. No change.
I don't want a new one — it was a gift.
👉🖥 Nhấn vào 🌙 đó là tất cả nội dung cho hôm nay. Giờ đóng cửa hiện mất khoảng 8 giây – tháp đang rút. Sau đó, hãy xem tầng 3.
👀 Các thẻ này không phải là câu của bạn. Họ nói những điều như Tôi dùng đèn lồng để đọc sách vào ban đêm, nhưng đèn thường xuyên bị tắt và Tôi đã thử treo đèn lồng cao hơn, mỗi câu đều được đánh dấu fact kèm theo ngày. Chưng cất. Nội dung được đưa vào là một cuộc trò chuyện. Những gì được đưa ra là sự thật.
👉🖥 Nhấn 🗓 một tháng sau – một lượt truy cập mới, nên không có nội dung nào bạn vừa nói trong cuộc trò chuyện nữa – rồi hỏi cô ấy câu hỏi này, một câu hỏi không có từ nào giống với các thẻ:
Should I just get a different lamp?
👀 Vì đây là quà tặng, nên bạn cho biết bạn không muốn thay thế đèn lồng và bạn đã thử treo đèn lồng cao hơn. Mọi lời nói của cô đều xuất phát từ tấm thẻ, và chỉ có tấm thẻ mới có thể cho cô biết: lần ghé thăm này chỉ cách đây một tin nhắn. Tìm kiếm tương tự. Tháp này so khớp nghĩa chứ không so khớp từ – câu hỏi có từ đèn và khác, thẻ có từ đèn lồng và thay thế. Và hiện tại, việc này không còn trong quy trình nữa: tắt tháp tối nay và các thẻ sẽ xuất hiện vào ngày mai, vì chúng nằm trên Agent Engine chứ không phải trong bash valley.sh.
Ghi và đã đọc – chỉ đọc
Quyền được lãng quên
👉🖥 Nhấn vào 🔥 quên tôi đi bên dưới hộp tin nhắn.
👀 Ba tầng tắt đèn và một tầng không tắt:
nội dung | sau 🔥 | |
tầng 3, các thẻ | những gì cô ấy ghi nhớ – thông tin thực tế mà Ngân hàng bộ nhớ thu thập được từ các lượt ghé thăm của bạn | đã hết — |
tầng 2, ngăn kéo |
| đã xóa |
không gian làm việc, tờ giấy | bản sao của trường hợp trong lần truy cập này | đã xóa |
tầng một, những cuốn sách | bản thân các lượt truy cập – một phiên trong | không thay đổi – số lượt truy cập không thay đổi |
Sổ sách là bản ghi: ghi lại lượt ghé thăm đã xảy ra, vào ngày nào và nội dung đã nói trong lượt ghé thăm đó. Các thẻ và ngăn kéo là ký ức: những gì cô ấy nhớ được về các lượt ghé thăm đó và mang theo vào lần ghé thăm tiếp theo. Yêu cầu được lãng quên là về ký ức – những thông tin thu thập được về một người và trạng thái đi kèm với người đó. Việc có xoá cả bản ghi lượt truy cập hay không là một quyết định riêng biệt, được đưa ra vì những lý do riêng biệt – nhật ký kiểm tra, nhật ký hỗ trợ – và phòng thí nghiệm này cố tình giữ lại bản ghi để bạn có thể thấy hai thứ này tách biệt với nhau: bản ghi và bộ nhớ không phải là một, và việc quên một thứ không ảnh hưởng đến thứ kia. Đó là câu nói trên cửa nhà Vesper, nhìn từ phía bên kia.
Hoạt động trừu tượng hoá bộ nhớ ADK có add_events_to_memory và search_memory. Không có nút xoá. Quên là một hành động quản trị, không phải hành động của tác nhân, vì vậy, hành động này nằm trong ứng dụng – archive/tower.py, memories.delete trên ứng dụng thô – nơi mô hình không thể vô tình truy cập vào. Việc một đặc vụ có thể quên hay không là điều bạn thiết kế, giống như việc đặc vụ có thể nhớ hay không.
Những gì bạn đã tạo và đọc, cũng như nội dung đó là gì
điều đó | Định nghĩa | nơi nó tồn tại |
| dịch vụ bộ nhớ, dưới dạng một dịch vụ: quyết định triển khai, bên ngoài tác nhân | Vertex AI Memory Bank trên Agent Engine |
| cùng một vị trí |
|
| những gì có thể được giữ lại, được quyết định tại thời điểm viết, không có trong câu lệnh |
|
🔥 → | quên là một thao tác ứng dụng; API bộ nhớ của ADK không có thao tác xoá |
|
Chuông này sẽ rung khi có người nói. Một ngày trôi qua, một sự thật xuất hiện – được chắt lọc thành những gì mà các chủ đề cho phép – và cuốn sách ở tầng một vẫn không hề di chuyển.
7. GraphRAG
Không bắt buộc.
- Nội dung – một tập lệnh tải dữ liệu trong quá khứ của thung lũng vào BigQuery, tạo các mục nhúng bên trong kho dữ liệu và đặt một biểu đồ lên các bảng mà không di chuyển hàng; sau đó, hai câu hỏi cho Vesper, người có hai truy vấn được quản lý cho việc này: một truy vấn cho những nội dung có âm thanh tương tự, một truy vấn cho những nội dung có liên quan.
- Tại sao – nghe có vẻ giống nhau không có nghĩa là có liên quan. Một vectơ tìm vị trí cần xem; một biểu đồ tìm những gì được đính kèm; và câu trả lời phải có đường dẫn mà câu trả lời đã đi qua.
- Cách thức –
bash scripts/season.sh, một lần. Mọi nội dung khác trong chương này đều chỉ có thể đọc.
Tháp của Vesper được thiết kế để bạn có thể nhìn thấy (app_name, user_id). Những người khác đến thăm không phải là ký ức của cô ấy và việc tìm kiếm kỹ hơn cũng không thay đổi được điều đó. Chúng thuộc về thung lũng và thung lũng giữ chúng trong một nhà kho. Có 31 du khách đến thăm nơi này vào mùa này vì một chiếc đèn lồng q7 bị tắt vào ban đêm và một trong số họ đã tìm ra nguyên nhân. Chương này tải kho dữ liệu đó và đưa cho cô ấy 2 truy vấn cố định vào kho dữ liệu.
Graph RAG
RAG là truy xuất, sau đó tạo: tìm bản ghi phù hợp, đưa cho mô hình và để mô hình trả lời dựa trên bản ghi đó. RAG thuần tuý truy xuất theo mức độ tương đồng – nhúng câu hỏi, kéo các bản ghi gần nhất. Câu lệnh này sẽ tìm những thứ nghe có vẻ giống câu hỏi và đó là nơi tháp của chương 4 dừng lại. Graph RAG thêm bước truy xuất thứ hai theo sau các cạnh – khoá mà kho đã có – từ bất kỳ điểm tương đồng nào được tìm thấy, đến bất kỳ điểm nào được đính kèm vào đó. Hai bước này trả lời các câu hỏi khác nhau và chương này sẽ giúp bạn đặt cả hai câu hỏi:
bị xì hơi | câu hỏi mà câu trả lời đó giải đáp | cách thức | trong chương này |
độ tương đồng | tôi nên tìm ở đâu? | nhúng câu hỏi, |
|
truy cập | cái gì được kết nối với cái đó? |
|
|
tạo | Tôi nên nói gì với khách truy cập? | mô hình, với đường dẫn là trích dẫn | câu trả lời của cô ấy |
Chạy ứng dụng
Mùa này được chuyển dưới dạng tệp CSV thuần tuý trong season/ – khách truy cập, mặt hàng, yêu cầu, bản sửa lỗi, mùa – theo cách mà hệ thống hỗ trợ sẽ xuất các tệp này. Một tập lệnh sẽ đưa họ vào nhà kho và đó là thứ duy nhất bạn chạy trong chương này.
👉💻 Trong thẻ 1 (khoảng 3 phút; thẻ này in từng bước khi thực hiện và dừng ở bước đầu tiên không thành công):
cd ~/agent-valley-archive
bash scripts/season.sh
👀 Khi kết thúc, tầng 4 của tháp sẽ sáng lên và chú thích bên cạnh sẽ là mở.
Những gì đã được tạo – chỉ đọc
Cách cô ấy đọc – chỉ đọc
Hỏi cô ấy
👉🖥 Tầng 4 đang mở cửa trong toà tháp. Hỏi cô ấy theo cách mà mọi khách truy cập sẽ làm:
Has anyone else had a q7 lantern go out at night?
👀 Cô ấy trả lời: 31 người khác... hầu hết đều nói ngọn lửa cháy nhỏ và tắt sau một giờ... Rái cá Marlow phát hiện ra rằng các sợi bấc được nhúng quá nông – và dòng cuối cùng trong câu trả lời của cô ấy là đường dẫn. Đây là kết quả của cô ấy – hãy đọc kết quả này, đừng gửi lại cho cô ấy:
mark q7 → 31 visits this season → 10 different things said → the wicks in the q7 batch were dipped too shallow — they drown in the oil and starve in an hour
Đường dẫn là trích dẫn. Mỗi bước nhảy trong đó là một cạnh trong đồ thị và một cạnh là một khoá, vì vậy, bất kỳ ai cũng có thể đi lại và nhận được cùng một số 31. Không ai có thể đi lại một điểm tương đồng. Nếu cô ấy nói rằng, ngay trước đường dẫn, các hàng đã quay lại thông qua 3 thao tác kết hợp vì dự án không có đặt trước đồ thị, thì đó là phiên bản dự án của bạn từ chối GRAPH_TABLE – các hàng và đường dẫn đều giống nhau.
👉🖥 Giờ hãy bỏ dấu này đi và gửi nội dung sau:
Has anyone else had a lantern that keeps dying once the sun is down?
👀 Cô ấy cũng đến được số 31 và đi cùng một đường. Điều thay đổi là con đường: season_search chạy trước, tìm thấy 5 khách truy cập có âm thanh giống nhau – mỗi người mang theo q7 – lấy dấu hiệu đó rồi mới đi bộ. Tương tự nhưng không liên quan; tương tự là nơi cần tìm.
Nội dung đã được tải và nội dung đó là gì
điều đó | Định nghĩa | nơi nó tồn tại |
| kho hàng: các cột có tên và loại |
|
| bước tương đồng – nơi cần xem xét |
|
| bước duyệt qua – những gì được kết nối; bảng trở thành các nút và mũi tên |
|
| con đường duy nhất mà cô ấy có thể đi; con đường đó là trích dẫn |
|
Vài chục khách truy cập không phải là lý do để mua một nhà kho. Những gì chương này dạy là hình dạng của truy vấn chứ không phải quy mô. Tăng đồ thị này lên 1.000 lần và MATCH không thay đổi theo ký tự.
8. Đóng
Ba đường ống, một tháp, một nhà kho – 4 tầng. Không có gì được khởi động lại.
bậc thang | những gì bạn đã làm | mặt hàng đã mua |
ONE |
| một lỗi xảy ra: trạng thái được viết bằng mã |
HAI |
| một ngăn kéo đi theo khách truy cập |
việc nộp |
| những gì đã nói, đã giữ |
BA |
| những gì đã được giữ lại, yêu cầu – không nhớ tệp đã được gửi |
toà tháp |
| một tháp chưng cất và sống sót qua đêm |
các quy tắc |
| chỉ những gì cần giữ lại |
mùa giải |
| lượt truy cập của mọi người khác, theo ý nghĩa và theo mối liên hệ |
Nội dung mà mỗi đoạn thay thế
ADK 2 | nội dung bạn sẽ viết thay thế | chi phí bạn phải trả |
| một dict bên cạnh vòng lặp trò chuyện, tự bạn chọn | mô hình không thể đọc được, và bạn viết sơ yếu lý lịch và khoá |
tiền tố | bảng người dùng và một thao tác kết hợp ở mỗi lượt | quyết định vị trí của một khoá, mỗi lần |
| một cron kết xuất bản chép lời và mô hình quyết định thời điểm tìm kiếm | nó chỉ đổ dữ liệu chứ không chắt lọc – và bạn không bao giờ thấy những lần nó không tìm được |
| một kho lưu trữ vectơ, một câu lệnh trích xuất, một tác vụ hợp nhất và "vui lòng không ghi nhớ thông tin bên lề" trong câu lệnh | ba dịch vụ và quy tắc này sẽ có hiệu lực cho đến khi mô hình cảm thấy khác |
| xuất, nhúng ở nơi khác, cơ sở dữ liệu đồ thị, công việc đồng bộ hoá và mô hình viết SQL | dữ liệu rời khỏi kho dữ liệu để được hiểu và bạn biết được những kết hợp mà dữ liệu đã đoán khi khách hàng thực hiện |
Ba câu hỏi, dừng lại ở câu trả lời có
- Ngày mai điều đó có còn quan trọng không? Không → không giữ lại nội dung nào. Nó chỉ tồn tại trong cuộc trò chuyện.
- Hàm có thể kiểm tra điều này không? Có → ngăn chứa. Mã viết nó, mọi lượt đều đọc nó và không câu nào có thể thay đổi nó.
- Nếu không → tháp. Được rút ra từ những gì đã nói, được tra cứu khi cần và được sửa đổi theo những gì nói tiếp theo.
Một câu
Bản ghi không phải là kỷ niệm. Ký ức là một bản ghi cộng với hai quyết định – nên giữ lại ký ức nào và nên xem lại ký ức nào – và loại ký ức đó sẽ quyết định ký ức đó được lưu trữ ở tầng nào.
Dữ kiện và lựa chọn ưu tiên thuộc về các cửa hàng khác nhau.
👀 Mọi tầng đều có ánh sáng. Linh thú của bạn ở trên cùng. Con dấu Archive nằm trong hộ chiếu, và tuần thứ năm mở ra Chợ đêm – nơi Nix điều hành sân khấu một cách công khai, theo thời gian thực và mọi thứ mà tháp biết đều đi cùng bạn.