Bài phát biểu chính tại Hội nghị Google cho nhà phát triển năm 2026: Gỡ lỗi cho các tác nhân ở quy mô lớn

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách gỡ lỗi các tác nhân AI chạy trên Google Cloud. Bạn sẽ triển khai một tác nhân mô phỏng cho Thời gian chạy tác nhân, sử dụng Cloud Observability để phát hiện vấn đề, đồng thời sử dụng Gemini Cloud Assist và Antigravity IDE để xác định nguyên nhân gốc rễ và khắc phục lỗi theo thời gian thực.

Tiền đề của bản minh hoạ này là chúng ta vừa thêm ADK EventCompaction vào Trình mô phỏng tác nhân. Điều này cho phép Trình mô phỏng định kỳ tóm tắt quy trình làm việc của mình bằng Gemini, giảm tổng ngữ cảnh được gửi đến mô hình ở mỗi lượt, nhờ đó cải thiện chất lượng phản hồi và giảm tổng chi phí. Nhưng chúng ta sẽ biết rằng có một lỗi trong EventCompactionConfig, gây ra lỗi trong tác nhân! Lớp học lập trình này hướng dẫn cách chúng ta tìm thấy loại vấn đề đó và nhanh chóng khắc phục.

Bạn sẽ thực hiện

• Triển khai Marathon Simulator Agent vào Agent Runtime.
• Thiết lập Cảnh báo của Cloud Monitoring để phát hiện lỗi của tác nhân.
• Điều tra lỗi bằng Cloud Trace và Gemini Cloud Assist.
• Tìm ra nguyên nhân gốc và vá tác nhân bằng Antigravity và MCP.

Lưu ý: Gemini Cloud Assist hiện đang ở chế độ Xem trước riêng tư. Bạn không cần được đưa vào danh sách cho phép để Cloud Assist chạy lớp học lập trình này. Tất cả các bước của Cloud Assist đều được tách biệt với bước 8 (Không bắt buộc): Sử dụng tính năng Điều tra của Cloud Assist – bỏ qua trang này nếu bạn chưa truy cập được Cloud Assist!

Bạn cần có

• Một trình duyệt web như Chrome.
• Tài khoản Google
• Antigravity (Hỗ trợ Mac, Linux và Windows)
• Python 3.13 trở lên.
• uv (Trình quản lý gói Python)

Thời lượng ước tính: 45 phút

Chi phí ước tính: Dưới 5 USD

2. Trước khi bắt đầu

Tạo một dự án trên Google Cloud

1. Trong Google Cloud Console, hãy chọn hoặc tạo một dự án trên Google Cloud.
2. Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud.

Thiết lập môi trường

Mở Antigravity rồi đăng nhập. Sau đó, mở Terminal bằng cách nhấn cmd-shift-P (hoặc ctrl-shift-P), rồi nhập "Create New Terminal" (Tạo cửa sổ dòng lệnh mới).

1. Từ Terminal, hãy xác thực bằng Google Cloud:

gcloud auth login
gcloud auth application-default login

2. Đặt mã dự án:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

Bật API

Chạy lệnh sau để bật các Cloud API cần thiết của Google Cloud:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

Nếu bạn được đưa vào danh sách cho phép sử dụng Gemini Cloud Assist (Bản xem trước riêng tư), hãy bật các API bổ sung sau:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. Thiết lập Trình mô phỏng

Ở bước này, bạn sẽ sao chép kho lưu trữ minh hoạ và định cấu hình các biến môi trường cho Trình mô phỏng tác nhân.

Sao chép Kho lưu trữ

Sao chép kho lưu trữ next-26-keynotes và chuyển đến thư mục minh hoạ:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

Định cấu hình các biến môi trường

Simulator Agent sử dụng tệp .env để định cấu hình.

Tìm tệp sample.env ở bên trái cửa sổ Antigravity (Explorer):

Mở sample.env rồi cập nhật trường GCP_PROJECT_ID bằng mã dự án thực tế của bạn trên Google Cloud. Tệp này sẽ có dạng như sau:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

Chúng tôi đang bật các hoạt động tích hợp OpenTelemetry để ghi lại các dấu vết chi tiết về lệnh gọi công cụ và quy trình suy luận của tác nhân.

4. Triển khai Trình mô phỏng đến Thời gian chạy tác nhân

Bây giờ, bạn sẽ triển khai tác nhân đến Thời gian chạy tác nhân bằng Bộ công cụ phát triển tác nhân (ADK).

Cài đặt các phần phụ thuộc

uv sync

Triển khai cho Thời gian chạy của tác nhân

1. Chạy lệnh adk deploy. Bước này đóng gói tác nhân của bạn và triển khai tác nhân đó lên Google Cloud (Thời gian chạy tác nhân).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Quá trình này có thể mất tới 5 phút để chạy. Cuối cùng, bạn sẽ thấy kết quả như sau:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

Ghi lại mã nhận dạng Thời gian chạy của tác nhân đã tạo. Bạn sẽ cần thông tin này sau!

2. Trên trình duyệt web, hãy mở bảng điều khiển Agent Runtime. Bạn sẽ thấy simulator_agent đang chạy trên Thời gian chạy của tác nhân, với tính năng thu thập dữ liệu đo từ xa được bật.

5. Thiết lập chính sách cảnh báo

Để tự động phát hiện lỗi Agent Runtime, bạn sẽ tạo một cảnh báo dựa trên nhật ký trong Google Cloud Console.

1. Chuyển đến bảng điều khiển Cloud Monitoring – Cảnh báo.

2. Nhấp vào Chỉnh sửa kênh thông báo. Di chuyển xuống loại Email, sau đó tạo một kênh thông báo qua email để gửi đến email cá nhân của bạn. Nhấp vào Lưu.

3. Quay lại trang tổng quan Cảnh báo rồi nhấp vào Tạo chính sách.
4. Ở bên phải màn hình, hãy nhấp vào Tạo cảnh báo dựa trên nhật ký.

5. Bạn sẽ được chuyển hướng đến Log Explorer (Trình khám phá nhật ký). Dán truy vấn nhật ký sau đây, thay thế bằng mã dự án của bạn.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

Truy vấn nhật ký này tìm kiếm nhật ký Lỗi trong tác nhân Agent Runtime, trong đó ReasoningEngine là tên API cơ bản cho Agent Runtime.

6. Nhấp vào Run Query (Chạy truy vấn). Bạn sẽ chưa thấy nhật ký nào xuất hiện – điều này là bình thường.
7. Nhấp vào Thao tác trong thanh công cụ kết quả, rồi nhấp vào Tạo cảnh báo nhật ký.

8. Định cấu hình cảnh báo dựa trên nhật ký. Đặt tên cho cảnh báo (bất kỳ tên nào), sau đó đặt mức độ nghiêm trọng thành Lỗi.

9. Nhấp vào Tiếp theo cho phần "Đặt tần suất thông báo" (giữ nguyên chế độ cài đặt mặc định).

10. Đối với Ai sẽ nhận được thông báo?, hãy đặt cảnh báo để kích hoạt kênh thông báo qua email mà bạn vừa thiết lập (ví dụ: My Email).
11. Nhấp vào Lưu.

6. Kích hoạt sự cố

Bây giờ, khi tác nhân đã được triển khai và giám sát, hãy thử gọi mô phỏng marathon theo cách gây ra lỗi.

1. Trong Google Cloud Console, hãy chuyển đến bảng điều khiển Thời gian chạy của tác nhân.
2. Nhấp vào simulator_agent.
3. Trên thanh công cụ phía trên cùng, hãy nhấp vào Playground (Sân chơi). Thao tác này sẽ bắt đầu một phiên mới với tác nhân ADK.

4. Trong cửa sổ trò chuyện của phiên, hãy nhập Test Simulation rồi nhấn phím enter để gửi câu lệnh.

Thao tác này sẽ bắt đầu mô phỏng cuộc chạy marathon, theo dõi hàng nghìn vận động viên chạy mô phỏng trên tuyến đường đã lên kế hoạch. Bạn sẽ thấy nhiều lệnh gọi công cụ đến get_runner_telemetry và analyze_medical_risk, vì quá trình mô phỏng đánh giá nhiều "khu vực" của cuộc đua.

Sau vài phút, bạn sẽ thấy tác nhân dừng chạy và trả về không có phản hồi.

5. Trong vòng một phút, bạn sẽ thấy một email xuất hiện trong hộp thư đến, thông báo cho bạn về một Sự cố mới trong tác nhân.

Nhấp vào Xem sự cố để mở bảng điều khiển Cloud Monitoring. Chuyển đến trang tiếp theo để điều tra vấn đề trong Bảng điều khiển.

7. Điều tra sự cố trong Bảng điều khiển

1. Xem sự cố trong bảng điều khiển Cloud Monitoring. Bạn sẽ thấy nhật ký lỗi xuất phát từ Simulator Agent.

Ở chế độ xem này, bạn khó có thể biết chính xác thời điểm mà Trợ lý gặp lỗi. Để xem các lệnh gọi công cụ cơ bản và quy trình suy luận của tác nhân, chúng ta sẽ xem xét Traces (Dấu vết) của tác nhân.

2. Mở lại bảng điều khiển Agent Runtime. Nhấp vào simulator_agent, sau đó mở thẻ Traces (Dấu vết).

3. Nhấp vào dấu vết gần đây nhất trong danh sách. Sau đó, ở trên cùng bên phải, hãy nhấp vào Dòng thời gian. Bạn sẽ thấy một chế độ xem dấu vết có các "khoảng" riêng lẻ. Một khoảng thời gian đại diện cho một lệnh gọi mô hình hoặc lệnh gọi công cụ trong quy trình làm việc của tác nhân.

4. Nhấp vào khoảng thời gian cuối cùng trong chế độ xem dấu vết. Đèn sẽ có màu đỏ.
5. Nhấp vào Stacktrace. Bạn sẽ thấy nhật ký lỗi liên quan đến một lệnh gọi mô hình Gemini API. Cụ thể là lỗi 400: Invalid Argument. Điều này báo hiệu một vấn đề ở cấp yêu cầu với tải trọng mà Trình mô phỏng tác nhân đã gửi đến Gemini API.

8. [Không bắt buộc] Sử dụng tính năng Điều tra bằng Cloud Assist để gỡ lỗi

Chỉ làm theo các bước này nếu bạn được đưa vào danh sách cho phép sử dụng Gemini Cloud Assist (Bản dùng thử riêng tư). Nếu không, hãy chuyển sang trang tiếp theo.

1. Trong khoảng thời gian thất bại, hãy nhấp vào Nhật ký và sự kiện. Tìm nhật ký "Ngoại lệ" có nút lấp lánh bên cạnh. Sau đó, hãy nhấp vào Điều tra nhật ký.

2. Thao tác này sẽ bắt đầu quá trình Điều tra bằng Cloud Assist từ một thanh bên ở bên phải màn hình. Quá trình này sẽ mất khoảng 3 đến 5 phút để tải.

3. Sau khi hoàn tất, hãy mở cuộc điều tra.

4. Xem Bản tóm tắt thông tin điều tra.

5. Di chuyển xuống để xem Giả thuyết. Gemini Cloud Assist phải xác định được dòng cụ thể trong tệp agent.py của Simulator Agent đang gây ra lỗi 400 của Gemini API.

Hãy tìm hiểu sâu hơn bằng cách mở mã nguồn của tác nhân và sử dụng Antigravity để tìm ra nguyên nhân gốc rễ của vấn đề. Chuyển sang trang tiếp theo.

9. Sử dụng Antigravity để tìm ra nguyên nhân gốc rễ và vá vấn đề

1. Mở lại Antigravity.
2. Mở Agent Manager (Trình quản lý tác nhân) ở trên cùng bên phải màn hình.

3. Đảm bảo bạn đã đặt mô hình thành Gemini 3 Flash và chế độ Lập kế hoạch.

4. Nhập câu lệnh sau rồi nhấn phím enter.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

Bạn sẽ thấy Antigravity kiểm tra mã trong agent.py và tìm kiếm các vấn đề liên quan trên GitHub:

Nguyên nhân gốc rễ của lỗi 400 Gemini API là do chúng tôi đang vượt quá giới hạn mã thông báo ngữ cảnh đầu vào của Gemini 3 Flash là khoảng 1 triệu. Nguyên nhân là do chúng ta không kích hoạt EventCompaction đủ thường xuyên để tóm tắt hiệu quả các phản hồi lớn từ lệnh gọi công cụ Simulator Agents.

Để khắc phục vấn đề này, Antigravity nên đề xuất thêm một tham số token_threshold vào EventsCompactionConfig để nén bối cảnh định kỳ trong mỗi lệnh gọi sau khi đạt đến một số lượng token nhất định.

Điều này phù hợp với bản sửa lỗi được đề xuất trong vấn đề này trên GitHub.

Áp dụng bản sửa lỗi cho agent.py.

Xác thực rằng bạn thấy nội dung tương tự như sau:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

Điều quan trọng là bạn phải đặt token_threshold và event_retention_size!

10. Triển khai lại và xác thực bản sửa lỗi

Giờ đây, khi đã áp dụng bản sửa lỗi token_threshold cho EventCompactionConfig của tác nhân ADK, chúng ta có thể triển khai lại Trình mô phỏng tác nhân cho Thời gian chạy tác nhân.

1. Mở Antigravity –> New Terminal (Thiết bị đầu cuối mới).
2. Đặt các biến môi trường. AGENT_RUNTIME_ID phải là Tên tài nguyên đầy đủ của simulator_agent. Bạn có thể tìm thấy thông tin này trong bảng điều khiển Thời gian chạy của tác nhân – danh sách tác nhân.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. Triển khai lại tác nhân:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

Quá trình này sẽ mất vài phút để chạy. Sau khi thực hiện thành công, bạn sẽ thấy:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. Mở bảng điều khiển Agent Runtime. Mở lại simulator_agent. Nhấp vào Playground
5. Nhập câu lệnh tương tự: Test Simulation – sau đó nhấn phím enter.
6. Quá trình mô phỏng Marathon đầy đủ ở phần phụ trợ sẽ mất vài phút để chạy. Bạn sẽ thấy nhiều lệnh gọi công cụ. Cuối cùng, bạn sẽ thấy một phản hồi như sau:

Điều này cho biết trình mô phỏng đã chạy thành công! ✅

7. Mở khung hiển thị Dấu vết cho phiên ADK đó.
8. Bạn sẽ thấy tất cả các khoảng thời gian "màu xanh dương" mà không có lỗi màu đỏ. Lưu ý rằng tổng số token của các phiên vượt quá hạn mức 1 triệu token ngữ cảnh của Gemini API. Không sao cả, vì giờ đây EventCompaction đang chạy đủ thường xuyên trong mỗi lệnh gọi để tránh vượt quá giới hạn ngữ cảnh tổng thể cho các lệnh gọi mô hình riêng lẻ.

🎊 Hoan hô! Chúng tôi đã vá lỗi trong tác nhân Trình mô phỏng!

11. Dọn dẹp

Để tránh bị tính phí vào tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã tạo trong lớp học lập trình này.

Xoá Ứng dụng thời gian chạy của tác nhân

Bạn có thể xoá phiên bản Reasoning Engine thông qua bảng điều khiển hoặc bằng cách sử dụng lệnh gcloud (nếu có tên tài nguyên). Để đơn giản hoá, hãy sử dụng bảng điều khiển:

1. Chuyển đến trang Thời gian chạy của tác nhân.
2. Chọn simulator_agent –> nhấp vào nút ba dấu chấm ở bên phải.
3. Nhấp vào Xóa.

Xoá Chính sách giám sát trên đám mây

1. Chuyển đến bảng điều khiển Cloud Monitoring -> Cảnh báo.
2. Di chuyển xuống phần Chính sách, sau đó nhấp vào nút có dấu ba chấm để Xoá chính sách.

12. 🎊 Xin chúc mừng!

Xin chúc mừng! Bạn vừa gỡ lỗi thành công một tác nhân AI trên Google Cloud.

Kiến thức bạn học được

• Cách triển khai các tác nhân đến Thời gian chạy tác nhân.
• Cách phát hiện lỗi bằng Thông báo của Cloud Monitoring.
• Cách khám phá các Sự cố đang hoạt động bằng Cloud Logging và chế độ xem dấu vết của Thời gian chạy của tác nhân.
• Cách điều tra lỗi bằng Gemini Cloud Assist.
• Cách sử dụng Antigravity để tìm ra nguyên nhân gốc rễ và vá các lỗi của tác nhân.
• Cách tinh chỉnh Tính năng nén sự kiện ADK để xử lý các lượt của tác nhân chạy trong thời gian dài và có nhiều công cụ.

Các bước tiếp theo

• Tìm hiểu thêm về Thời gian chạy của tác nhân.
• Tìm hiểu thêm về Agent Development Kit.
• Tìm hiểu thêm về Cảnh báo trong Cloud Monitoring.
• Tìm hiểu thêm về Gemini Cloud Assist.