1. Giới thiệu
Trong lớp học lập trình này, bạn sẽ từng bước xây dựng tác nhân AI đầu tiên của mình bằng Bộ công cụ phát triển tác nhân (ADK) và Gemini của Google. Bạn sẽ tạo một tác nhân viết blog cơ bản có thể lập kế hoạch và viết nội dung, minh hoạ các khái niệm cốt lõi về suy luận và hành động.
Bạn sẽ thực hiện
- Thiết lập môi trường phát triển cho ADK.
- Tạo một hệ thống đa tác nhân bằng Trình lập kế hoạch và Trình viết.
- Chạy tác nhân cục bộ và tương tác với tác nhân đó thông qua giao diện người dùng web ADK.
Bạn cần có
- Một trình duyệt web như Chrome.
- Python 3.10 trở lên đã được cài đặt trên máy của bạn.
- Khoá API Google AI Studio.
Lớp học lập trình này dành cho nhà phát triển ở mọi cấp độ, kể cả người mới bắt đầu.
Thời lượng ước tính: 30 phút.
2. Hướng dẫn bằng hình ảnh: Tác nhân AI là gì?
Trước khi bắt đầu xây dựng, hãy tìm hiểu nhanh về các tác nhân AI và những mẫu hình phổ biến mà chúng tuân theo.
Tác nhân AI là gì?
Ở cấp độ đơn giản nhất, tác nhân là phần mềm không chỉ trả lời mà còn có thể quyết định và hành động. Thay vì tạo một câu trả lời duy nhất như chatbot truyền thống, Gemini sẽ xem xét yêu cầu của bạn, tìm ra các bước cần thực hiện, có thể gọi một API, chạy mã, xem xét kết quả rồi quyết định việc cần làm tiếp theo.
Một trong những giải thích rõ ràng nhất đến từ bài viết nghiên cứu ReAct: Synergizing Reasoning and Acting in Language Models (ReAct: Kết hợp suy luận và hành động trong mô hình ngôn ngữ). Ý tưởng trong bài viết nghiên cứu đó rất đơn giản nhưng hiệu quả: mô hình ngôn ngữ không chỉ tạo văn bản trong một lần. Mô hình ngôn ngữ có thể suy luận từng bước, thực hiện một hành động như gọi một công cụ hoặc API, quan sát kết quả rồi quyết định việc cần làm tiếp theo.
Chu trình suy luận, hành động, quan sát và điều chỉnh đó là nền tảng cho cách hoạt động của các tác nhân AI hiện đại. Điều này phù hợp với cách Google Cloud định nghĩa về AI: các hệ thống có khả năng suy luận, lập kế hoạch và ghi nhớ, có đủ quyền tự chủ để thích ứng và đưa ra quyết định thay cho người dùng.
3 kiểu hành vi của nhân viên
Không phải tác nhân nào cũng hoạt động giống nhau. Có 3 mẫu hình chung mà bạn có thể tham khảo:
- Các tác nhân tuần tự: Các tác nhân này chạy từng bước như một dây chuyền lắp ráp: Bước 1, sau đó là Bước 2, rồi đến Bước 3. Chúng có thể dự đoán được nhưng lại cứng nhắc.
- Tác nhân phản ứng: Những tác nhân này đưa ra quyết định ngay lập tức. Họ xem xét tình hình hiện tại và tự hỏi: "Tôi nên làm gì tiếp theo?" Có thể lần này dùng Công cụ A, lần sau dùng Công cụ B. Họ linh hoạt nhưng không lên kế hoạch trước.
- Tác nhân có cân nhắc hoặc lập kế hoạch: Những tác nhân này tạm dừng để phác thảo kế hoạch, sau đó thực hiện. Hãy nghĩ đến việc đặt chuyến đi – bạn không chỉ mua vé máy bay một cách ngẫu nhiên, mà còn chọn ngày, khách sạn, sắp xếp các bước rồi thực hiện.
Đâu là lựa chọn "phù hợp"? Điều này tuỳ thuộc vào vấn đề. Đối với các quy trình đơn giản, có thể dự đoán được, quy trình tuần tự là phù hợp. Đối với các tác vụ linh động, quy trình phản ứng sẽ hoạt động hiệu quả hơn. Đối với các mục tiêu nhiều bước có sự phụ thuộc, bạn nên sử dụng các tác nhân lập kế hoạch.
Trong lớp học lập trình này, chúng ta sẽ xây dựng một tác nhân Có cân nhắc/Lập kế hoạch. Tác nhân này sẽ tạo dàn ý trước rồi mới viết bài đăng trên blog!
3. Trước khi bắt đầu
Tạo Tài khoản và Dự án trên Google Cloud
Để triển khai tác nhân của bạn lên Google Cloud Run sau này trong phòng thí nghiệm này, bạn cần có một tài khoản Google Cloud và một dự án đã bật tính năng thanh toán.
- Đăng nhập vào Google Cloud Console. Tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Nếu chưa có Tài khoản Google, bạn phải tạo một tài khoản.
- Tiếp theo, bạn cần bật tính năng thanh toán trong Cloud Console để sử dụng các tài nguyên trên đám mây. Việc thực hiện codelab này sẽ tốn ít hơn vài xu. Người dùng mới của Google Cloud cũng có thể đủ điều kiện tham gia chương trình Dùng thử miễn phí trị giá 300 USD.
- Ghi lại Mã dự án (tên riêng biệt cho tất cả dự án trên Google Cloud). Bạn sẽ cần thông tin này để định cấu hình và triển khai tác nhân.
Lấy khoá API Google AI Studio
Để sử dụng các mô hình Gemini, bạn cần có một khoá API từ Google AI Studio.
- Truy cập vào Google AI Studio.
- Nhấp vào Lấy khoá API.
- Tạo khoá mới hoặc sử dụng khoá hiện có. Sao chép khoá để sử dụng sau.
4. Tạo cấu trúc dự án cho Blog Writer Agent
Trong bước này, bạn sẽ thiết lập thư mục và các tệp để lưu trữ mã của tác nhân viết blog trên máy cục bộ.
1. Tạo không gian làm việc cho tác nhân viết blog
Mở cửa sổ dòng lệnh rồi chạy các lệnh sau để tạo một thư mục riêng cho tác nhân viết blog và chuyển đến thư mục đó:
mkdir bloggeragent
cd bloggeragent
2. Khởi chạy các tệp tác nhân
Khung ADK của Google tải các quy trình làm việc của tác nhân ngay từ thư mục dự án của bạn. Tạo các tệp cần thiết ngay trong thư mục gốc của bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Cài đặt các phần phụ thuộc và thiết lập môi trường
Trong bước này, bạn sẽ thiết lập một môi trường ảo Python, cài đặt khung Google ADK và định cấu hình các biến môi trường để xác thực tác nhân blog của bạn bằng mô hình Gemini.
1. Định cấu hình các yêu cầu đối với tác nhân
Mở tệp requirements.txt trong thư mục bloggeragent và chỉ định các gói cần thiết cho tác nhân viết blog bằng cách thêm nội dung sau vào tệp đó:
google-adk==2.2.0
python-dotenv
2. Tạo môi trường ảo cho tác nhân
Trong thư mục bloggeragent, hãy tạo và kích hoạt một môi trường ảo Python để tách biệt các gói của tác nhân:
python3 -m venv .venv
source .venv/bin/activate
3. Cài đặt khung ADK
Cài đặt các phần phụ thuộc được xác định trong requirements.txt để trang bị cho không gian làm việc cục bộ của bạn bằng Google ADK:
pip install -r requirements.txt
4. Định cấu hình thông tin đăng nhập API của tác nhân
Mở tệp .env mà bạn đã tạo trong thư mục gốc của dự án rồi thêm khoá Gemini API của bạn:
GOOGLE_API_KEY=your_api_key
Thay thế your_api_key bằng khoá mà bạn đã sao chép từ Google AI Studio.
6. Xây dựng Trình viết blog nhiều tác nhân
Trong bước này, bạn sẽ triển khai quy trình làm việc cốt lõi của hệ thống tác nhân viết blog.
Thay vì một chatbot đơn giản chỉ có một câu lệnh, bạn sẽ xây dựng một hệ thống phức tạp gồm nhiều tác nhân sử dụng các vòng lặp tự sửa lỗi và quy trình xác minh dàn ý để viết các bài đăng kỹ thuật chất lượng cao. Điều này tuân theo mẫu Cân nhắc/Lập kế hoạch mà chúng ta đã thảo luận trước đó.
Tổng quan về Cấu trúc (Architecture)
Sau đây là cách các đặc vụ chuyên trách trong hệ thống của bạn tương tác:
Định cấu hình init.py
Mở __init__.py trong trình chỉnh sửa văn bản rồi thêm nội dung nhập sau để hiển thị quy trình làm việc của tác nhân cho trình chạy:
from . import agent
Viết quy trình làm việc của tác nhân viết blog
Mở agent.py trong trình soạn thảo mã và thêm đoạn mã sau đây để xác định Planner, Writer, Validation Checkers và tác nhân Blogger chính:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Tìm hiểu về Cấu trúc tác nhân
Hãy phân tích các thành phần chính của mã mà bạn vừa thêm vào agent.py để hiểu cách mã này triển khai quy trình lập kế hoạch và viết nhiều tác nhân:
1. The BlogPlanner Sub-Agent
Tác nhân blog_planner chịu trách nhiệm lập kế hoạch nội dung. Công cụ này lấy chủ đề do người dùng cung cấp và tạo ra một dàn ý có cấu trúc ở định dạng Markdown (gồm tiêu đề, phần giới thiệu, 4 đến 6 phần và phần kết luận). Đường viền được lưu vào từ điển trạng thái dùng chung theo khoá "blog_outline".
2. OutlineValidationChecker
Tác nhân OutlineValidationChecker đóng vai trò là cổng kiểm soát chất lượng. Thành phần này xem xét "blog_outline" đã tạo ở trạng thái. Nếu đường viền hợp lệ, thì đường viền sẽ phản hồi bằng "ok". Nếu không, hàm này sẽ trả về "retry" cùng với danh sách những thông tin còn thiếu.
3. Vòng lặp RobustBlogPlanner
Để ngăn tác nhân tạo ra những dàn ý không phù hợp, chúng tôi sẽ bao bọc trình lập kế hoạch và trình kiểm tra xác thực bên trong một LoopAgent có tên là robust_blog_planner. Nếu quá trình xác thực không thành công và trả về "retry", thì vòng lặp sẽ tự động chạy lại trình lập kế hoạch, tối đa 3 lần, đảm bảo quá trình tự sửa lỗi trước khi chuyển sang giai đoạn tiếp theo.
4. The BlogWriter Sub-Agent
Sau khi bản phác thảo hoàn tất, tác nhân blog_writer sẽ đọc "blog_outline" từ trạng thái và tạo bài viết kỹ thuật đầy đủ ở định dạng Markdown, khớp với cấu trúc của bản phác thảo và điều chỉnh cho phù hợp với kỹ sư phần mềm.
5. Vòng lặp BlogPostValidationChecker và RobustBlogWriter
Giống như dàn ý, bài viết cuối cùng được BlogPostValidationChecker xác thực để đảm bảo tất cả các phần chính đều có mặt và rõ ràng. Người viết và người kiểm tra được đưa vào vòng lặp robust_blog_writer, cho phép tự sửa tối đa 3 lần nếu người kiểm tra phát hiện ra vấn đề.
6. Hiển thị các vòng lặp dưới dạng công cụ
Chúng ta gói vòng lặp của trình lập kế hoạch (robust_blog_planner) và vòng lặp của trình viết (robust_blog_writer) dưới dạng các công cụ (planner_tool và writer_tool) bằng cách sử dụng AgentTool. Nhờ đó, các tác nhân khác có thể gọi những quy trình công việc phức tạp này như thể chúng là các công cụ đơn giản.
7. Tác nhân gốc của Blogger
root_agent (được đặt tên là Blogger) điều phối toàn bộ quy trình công việc. Khi được cung cấp một chủ đề, các chỉ dẫn của root_agent sẽ hướng dẫn Blogger thực hiện những việc sau:
- Gọi
planner_toolđể tạo đường viền đã xác thực. - Gọi
writer_toolđể viết bản nháp dựa trên dàn ý đó. - Kết thúc bằng cách tạo 3 tiêu đề thay thế và 2 câu dẫn để đăng lên Twitter.
Cấu trúc vòng lặp nhiều tác nhân này đảm bảo độ tin cậy bằng cách phát hiện và sửa lỗi định dạng hoặc cấu trúc của LLM trước khi cho người dùng thấy kết quả!
7. Chạy và kiểm thử tác nhân
Giờ là lúc bạn có thể xem tác nhân của mình hoạt động!
1. Khởi động giao diện người dùng web ADK
Đảm bảo bạn đang ở thư mục gốc của dự án bloggeragent trong thiết bị đầu cuối và môi trường ảo của bạn đang hoạt động (source .venv/bin/activate), sau đó khởi động giao diện web:
adk web
2. Tương tác với Tác nhân
- Mở trình duyệt rồi chuyển đến
http://127.0.0.1:8000(hoặc cổng mà bạn đã chỉ định). - Bạn sẽ thấy giao diện người dùng web ADK với tác nhân
Bloggerđã tải và bố cục trực quan của tác nhân đó (cho thấy tác nhân gốc Blogger trỏ đến các công cụ RobustBlogPlanner và RobustBlogWriter):
- Nhập một chủ đề kỹ thuật vào hộp tin nhắn rồi nhấn Enter. Sau đây là một số câu lệnh kiểm thử thú vị mà bạn có thể dùng để đánh giá tác nhân:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Xem dấu vết thực thi trong giao diện người dùng. Bạn sẽ thấy
BlogPlannertạo dàn ý,OutlineValidationCheckerxác thực dàn ý vàBlogWriterviết bản nháp cuối cùng dựa trên dàn ý:
8. Triển khai lên Cloud Run
Giờ đây, bạn đã xác minh rằng tác nhân hoạt động cục bộ, hãy triển khai tác nhân đó lên Google Cloud Run để người khác có thể sử dụng!
Google Cloud Run là một nền tảng điện toán được quản lý, cho phép bạn chạy các vùng chứa không trạng thái có thể gọi được thông qua các yêu cầu trên web hoặc sự kiện Pub/Sub.
1. Điều kiện tiên quyết để triển khai
Để triển khai tác nhân viết blog lên Cloud Run, bạn cần cài đặt và xác thực Google Cloud CLI (gcloud) trên máy cục bộ:
- Cài đặt Google Cloud CLI: Nếu bạn chưa cài đặt, hãy làm theo Hướng dẫn cài đặt Google Cloud CLI cho hệ điều hành của bạn (macOS, Windows hoặc Linux).
- Xác thực thiết bị đầu cuối cục bộ: Sau khi cài đặt, hãy chạy lệnh sau trong thiết bị đầu cuối để đăng nhập vào tài khoản Google Cloud của bạn:
gcloud auth login - Xác minh quá trình xác thực: Xác nhận rằng bạn đã đăng nhập thành công vào tài khoản và có thể truy cập vào các tài nguyên trên Google Cloud:
gcloud auth list
2. Thiết lập dự án trên Google Cloud
Đặt dự án đang hoạt động trong thiết bị đầu cuối:
gcloud config set project <YOUR_PROJECT_ID>
Bật các dịch vụ cần thiết của Google Cloud để tạo và triển khai tác nhân được chứa trong vùng chứa:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Vì lệnh triển khai ADK sử dụng Google Cloud Build để tự động hoá quy trình tạo bản dựng, nên bạn phải cấp cho tài khoản dịch vụ điện toán mặc định quyền sử dụng Cloud Build.
Tìm số dự án bằng cách chạy:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Chạy các lệnh sau để liên kết các vai trò IAM bắt buộc (thay
- Cấp quyền cho Cloud Build để tạo vùng chứa của bạn:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Cấp quyền truy cập Gemini Enterprise để tác nhân được triển khai có thể gọi các mô hình Gemini mà không cần khoá API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Thiết lập các biến môi trường cục bộ
Để đơn giản hoá lệnh triển khai và tránh lỗi chính tả, hãy đặt mã dự án làm biến môi trường trong phiên thiết bị đầu cuối:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Triển khai bằng ADK CLI
ADK CLI cung cấp một lệnh tinh giản để triển khai tác nhân của bạn lên Cloud Run.
Đảm bảo môi trường ảo của bạn đang hoạt động và bạn đang ở trong thư mục dự án bloggeragent, sau đó chạy lệnh triển khai:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Trong quá trình triển khai, bạn sẽ được nhắc trả lời 2 câu hỏi sau trong cửa sổ dòng lệnh:
- Xác nhận việc tạo kho lưu trữ:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yrồi nhấn Enter. - Cho phép quyền truy cập chưa xác thực:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yrồi nhấn Enter (thao tác này cho phép bạn truy cập công khai vào giao diện người dùng web ADK trong trình duyệt).
5. Truy cập vào Tác nhân đã triển khai
Sau khi quá trình triển khai hoàn tất, lệnh sẽ xuất ra một URL. Mở URL đó trong trình duyệt để truy cập vào giao diện người dùng web ADK đang hoạt động và có thể truy cập công khai!
9. Dọn dẹp
Để tránh các khoản phí phát sinh cho tài khoản Google Cloud của bạn, hãy xoá các tài nguyên đã tạo trong lớp học lập trình này.
1. Xoá dịch vụ Cloud Run
Xoá dịch vụ bloggeragent đã triển khai:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Xoá Kho lưu trữ Artifact Registry
Xoá kho lưu trữ Docker đã tạo để lưu trữ các hình ảnh vùng chứa đã tạo:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Dừng máy chủ cục bộ
Để dừng máy chủ ADK cục bộ, hãy nhấn CTRL+C trong thiết bị đầu cuối đang chạy máy chủ đó rồi huỷ kích hoạt môi trường ảo:
deactivate
10. Xin chúc mừng
Xin chúc mừng! Bạn đã tạo được tác nhân AI đầu tiên bằng ADK và Gemini của Google.
Kiến thức bạn học được
- Các khái niệm cốt lõi về tác nhân AI (Lập luận và Hành động).
- Cách sử dụng ADK của Google để xây dựng một hệ thống nhiều tác nhân.
- Cách chạy và kiểm thử tác nhân bằng giao diện người dùng trên web.
Các bước tiếp theo
- Hãy thử thêm các công cụ vào trợ lý ảo (chẳng hạn như tìm kiếm trên web hoặc lệnh gọi API).
- Hãy theo dõi Video 2, nơi chúng ta sẽ tích hợp một máy chủ MCP!