Thông tin về lớp học lập trình này
1. Kiến thức bạn sẽ học được
Chào mừng bạn đến với Lớp học chuyên sâu về ADK – Hành trình khám phá Hệ thống đa tác nhân
Bạn sắp bước vào thế giới thú vị của các tác nhân AI. Hãy quên đi những chatbot đơn giản chỉ trả lời câu hỏi. Chúng tôi đang tìm hiểu kỹ về Agent Development Kit (ADK)
để xây dựng các hệ thống tự động, tinh vi có thể suy luận, lập kế hoạch và sử dụng các công cụ để hoàn thành những nhiệm vụ phức tạp.
Sau khi hoàn thành hướng dẫn này, bạn sẽ có thể:
- Xây dựng tác nhân AI đầu tiên: Từ con số không đến một tác nhân có đầy đủ chức năng, có thể hiểu nhu cầu của người dùng, sử dụng các công cụ như Google Tìm kiếm và tạo ra các câu trả lời chi tiết, hữu ích.
- Sử dụng thành thạo các công cụ tuỳ chỉnh: Khai thác sức mạnh thực sự của các tác nhân bằng cách kết nối chúng với các hàm và API tuỳ chỉnh của riêng bạn. Bạn sẽ hướng dẫn cho trợ lý ảo cách tìm nạp dữ liệu theo thời gian thực, chẳng hạn như dự báo thời tiết trực tiếp.
- Xây dựng hệ thống đa tác nhân: Tìm hiểu mẫu "Tác nhân dưới dạng công cụ", một khái niệm mang tính cách mạng trong đó các tác nhân uỷ quyền nhiệm vụ cho các tác nhân chuyên biệt khác, tạo ra một nhóm chuyên gia AI làm việc cùng nhau.
- Điều phối quy trình công việc phức tạp: Vượt xa việc uỷ quyền đơn giản và nắm vững các mẫu nâng cao như Bộ định tuyến, Chuỗi tuần tự, Vòng lặp và Thực thi song song để xây dựng các ứng dụng mạnh mẽ, hiệu quả và thông minh có thể xử lý hầu hết mọi yêu cầu.
- Trang bị bộ nhớ cho các trợ lý ảo: Hiểu rõ vai trò quan trọng của bộ nhớ đàm thoại, cho phép các trợ lý ảo xử lý các câu hỏi nối tiếp, học hỏi từ ý kiến phản hồi và quản lý các tác vụ nhiều bước một cách liền mạch.
Hãy bắt đầu! 🚀
2. Thiết lập GCP và khoá Gemini API
Thiết lập dự án GCP và khoá Gemini API
Để hỗ trợ các tác nhân AI của chúng tôi, chúng tôi cần hai thứ: một Dự án Google Cloud để cung cấp nền tảng và một Khoá Gemini API để truy cập vào các mô hình mạnh mẽ của Google.
Bước 1: Bật Tài khoản thanh toán
- Bạn cần phải xác nhận quyền sở hữu tài khoản thanh toán(đường liên kết không bắt buộc) có sẵn 5 đô la tín dụng quà tặng để triển khai. Đảm bảo bạn đã đăng nhập vào tài khoản gmail.
Bước 2: Tạo một dự án GCP mới
- Truy cập vào Google Cloud Console rồi tạo một dự án mới.
- Truy cập vào Google Cloud Console rồi tạo một dự án mới.
- Mở bảng điều khiển bên trái, nhấp vào
Billing
, kiểm tra xem tài khoản thanh toán có được liên kết với tài khoản GCP này hay không.
Nếu bạn thấy trang này, hãy kiểm tra manage billing account
, chọn Google Cloud Trial One và liên kết với trang đó.
Bước 3: Tạo khoá Gemini API
Trước khi có thể bảo mật khoá, bạn cần phải có khoá.
- Truy cập vào Google AI Studio : https://aistudio.google.com/
- Đăng nhập bằng tài khoản Gmail của bạn.
- Nhấp vào nút "Lấy khoá API", thường nằm trong ngăn điều hướng bên trái hoặc ở góc trên cùng bên phải.
- Trong hộp thoại "Khoá API", hãy nhấp vào "Tạo khoá API trong dự án mới".
- Chọn dự án mới mà bạn đã tạo và đã thiết lập tài khoản thanh toán.
- Một khoá API mới sẽ được tạo cho bạn. Sao chép ngay khoá này và tạm thời lưu trữ ở một nơi an toàn (chẳng hạn như trình quản lý mật khẩu hoặc ghi chú bảo mật). Đây là giá trị bạn sẽ sử dụng trong các bước tiếp theo.
3. Phiên 1: Tác nhân đầu tiên của bạn với Runner
Hãy bắt đầu với những kiến thức cơ bản. Ở đây, chúng ta sẽ tạo tác nhân đơn giản đầu tiên, day_trip_agent
. Mục đích của trợ lý này là tạo một hành trình du lịch cả ngày dựa trên yêu cầu của người dùng, bao gồm cả việc cân nhắc ngân sách. Ví dụ này giới thiệu 3 thành phần cốt lõi của mọi hoạt động tương tác với tác nhân trong ADK:
- Tác nhân: Bộ não cốt lõi của hoạt động. AI tuỳ chỉnh được xác định bằng các chỉ dẫn (tính cách và nhiệm vụ), mô hình AI mà AI tuỳ chỉnh sử dụng (chẳng hạn như Gemini) và các công cụ mà AI tuỳ chỉnh có thể truy cập.
- Phiên: Bộ nhớ của cuộc trò chuyện. Ứng dụng này lưu trữ nhật ký tương tác (tin nhắn của người dùng và câu trả lời của trợ lý ảo), cho phép duy trì cuộc trò chuyện liên tục.
- Runner: Công cụ thực thi tác vụ. Nó lấy Agent và Session, xử lý truy vấn mới của người dùng và điều phối các bước để tạo ra câu trả lời.
➡️ Nơi tìm thấy thông tin trong sổ tay
👉 Phần này tương ứng với các ô trong Phần 1: Nhân viên hỗ trợ ảo đầu tiên của bạn – Thần đèn du lịch trong ngày 🧞.🌟
- Định nghĩa về tác nhân: Tìm hàm
create_day_trip_agent()
. Đây là nơi xác định nhân viên hỗ trợ. Hãy lưu ý chuỗi hướng dẫn chi tiết – đây là câu lệnh cho biết cách nhân viên hỗ trợ nên hành xử. Chúng tôi cũng cung cấp cho AI công cụ đầu tiên: Google Tìm kiếm. - Hàm trợ giúp: Hàm trợ giúp
run_agent_query()
được xác định ở đây. Chúng ta sẽ sử dụng tiện ích này trong suốt sổ tay để đơn giản hoá việc chạy các truy vấn. - Chạy thử: Chức năng
run_day_trip_genie()
mô phỏng một người dùng yêu cầu chuyến đi trong ngày "vừa túi tiền" và "thư giãn". Dựa vào các chỉ dẫn và công cụ Tìm kiếm của Google, trợ lý này sẽ tìm những địa điểm phù hợp và tạo một hành trình được định dạng bằng markdown.
➡️ Hành động: Xem xét câu lệnh hướng dẫn cho day_trip_agent
. Xem cách yêu cầu về một chuyến đi "phải chăng" trong cụm từ tìm kiếm thử nghiệm liên quan trực tiếp đến nguyên tắc "Biết rõ ngân sách" của trợ lý.
4. Phiên 2: Công cụ tuỳ chỉnh 🛠️
Mặc dù Google Tìm kiếm rất mạnh mẽ, nhưng tiềm năng thực sự của các tác nhân AI sẽ được khai thác khi bạn kết nối chúng với các nguồn dữ liệu, API hoặc logic tuỳ chỉnh riêng biệt của mình. Trong phần này, chúng ta sẽ tạo một công cụ tuỳ chỉnh từ một hàm Python đơn giản.
Phần quan trọng nhất của công cụ hàm là chuỗi tài liệu. ADK tự động phân tích cú pháp chuỗi tài liệu để hiểu chức năng của công cụ, các tham số mà công cụ chấp nhận (Args) và những gì công cụ trả về (Returns). Mô hình ngôn ngữ lớn (LLM) đọc nội dung mô tả này để quyết định thời điểm và cách sử dụng công cụ.
➡️ Nơi tìm thấy thông tin trong sổ tay
👉 Điều này tương ứng với các ô trong phần 2.1 The Simple FunctionTool: Calling a Real-Time Weather API (Công cụ chức năng đơn giản: Gọi API thời tiết theo thời gian thực). 🌟
- Định nghĩa công cụ: Hàm
get_live_weather_forecast(location: str)
là cốt lõi của công cụ tuỳ chỉnh. Hàm này lấy tên thành phố, gọi API công khai của Dịch vụ Thời tiết Quốc gia và trả về một từ điển có nhiệt độ và thông tin dự báo. - Định nghĩa về tác nhân: weather_agent được tạo và trang bị công cụ mới của chúng tôi bằng cách truyền
tools=[get_live_weather_forecast]
trong quá trình khởi chạy. Hướng dẫn dành cho trợ lý ảo yêu cầu trợ lý ảo sử dụng công cụ này trước khi đề xuất các hoạt động ngoài trời. - Chạy thử: Cụm từ tìm kiếm "Tôi muốn đi bộ đường dài gần hồ Tahoe, thời tiết thế nào?" sẽ trực tiếp kích hoạt tác nhân sử dụng công cụ
get_live_weather_forecast
vì hướng dẫn của công cụ này yêu cầu như vậy.
➡️ Hành động: Đọc chuỗi tài liệu cho hàm get_live_weather_forecast
và hướng dẫn cho weather_agent
. Lưu ý mối quan hệ trực tiếp giữa các mục này.
5. Phiên 3: Agent-as-a-Tool 🧑🍳
Tại sao phải xây dựng một tác nhân đơn lẻ, nguyên khối khi bạn có thể tạo một nhóm chuyên gia? Mẫu Agent-as-a-Tool
là một cách hiệu quả để xây dựng các hệ thống phức tạp, trong đó một tác nhân chính (thường được gọi là Orchestrator hoặc Router) sẽ uỷ quyền các tác vụ cho những tác nhân khác tập trung hơn.
Mẫu này cho phép bạn tạo các tác nhân mô-đun có thể dùng lại. Ví dụ: bạn có thể có một đặc vụ là chuyên gia về truy vấn cơ sở dữ liệu, một đặc vụ khác là chuyên gia về viết nội dung sáng tạo và một đặc vụ thứ ba đóng vai trò là nhân viên hỗ trợ thân thiện. Nhiệm vụ của điều phối viên là hiểu yêu cầu của người dùng và chuyển yêu cầu đó đến đúng chuyên gia.
➡️ Nơi tìm thấy thông tin trong sổ tay
👉 Điều này tương ứng với các ô trong phần 2.2 Agent-as-a-Tool: Tư vấn cho chuyên gia 🧑🍳.🌟
Ví dụ này xây dựng một hệ thống tác nhân phức tạp, nhiều lớp:
- The Specialists (Các chuyên gia)
- :
- food_critic_agent: Một trợ lý chuyên trách chỉ đưa ra đề xuất về nhà hàng.
- db_agent: Một tác nhân mô phỏng giả vờ truy vấn cơ sở dữ liệu để lấy thông tin về khách sạn.
- concierge_agent: Một trợ lý ở cấp trung bình, đóng vai trò là một nhân viên hướng dẫn khách lịch sự. Điều quan trọng là
food_critic_agent
có công cụ riêng.
- Orchestrator (
trip_data_concierge_agent
): Đây là tác nhân cấp cao nhất mà người dùng tương tác. Các chỉ dẫn của nó khiến nó trở thành "người lập kế hoạch du lịch chính" và nó được cung cấp hai công cụ để gọi các tác nhân khác:- call_db_agent: Một hàm gọi
db_agent
. - call_concierge_agent: Một hàm gọi
concierge_agent
.
- call_db_agent: Một hàm gọi
- Luồng: Lần chạy thử trong
run_trip_data_concierge()
minh hoạ toàn bộ chuỗi uỷ quyền.- Người dùng yêu cầu điều phối viên tìm một khách sạn và một nhà hàng ở gần đó.
- Các chỉ dẫn của trình điều phối yêu cầu trình điều phối trước tiên sử dụng công cụ
call_db_agent
để lấy dữ liệu khách sạn. - Sau đó, trình điều phối sẽ dùng công cụ
call_concierge_agent
để nhận đề xuất. - Sau khi nhận được yêu cầu,
concierge_agent
sẽ dùng công cụ riêng làfood_critic_agent
để tìm ý tưởng về nhà hàng.
Phản hồi của nhà phê bình ẩm thực được chuyển lại cho nhân viên hỗ trợ. Nhân viên này sẽ định dạng phản hồi một cách lịch sự rồi gửi lại cho điều phối viên. Cuối cùng, điều phối viên sẽ trình bày phản hồi cho người dùng.
➡️ Hành động: Theo dõi quy trình thực thi trong phiên chạy thử nghiệm trong run_trip_data_concierge()
. Quan sát cách các bản in TOOL CALLED
cho thấy chuỗi uỷ quyền từ trình điều phối xuống đến các chuyên gia. Đây là một chuỗi lệnh tuần tự.
6. Phiên 4: Bộ nhớ của trợ lý ảo 🧠
Một tác nhân thực sự thông minh cần làm nhiều việc hơn là chỉ phản hồi các cụm từ tìm kiếm một lần. Công cụ này cần ghi nhớ cuộc trò chuyện, hiểu được bối cảnh và thích ứng với ý kiến phản hồi. Điều này đạt được thông qua việc quản lý phiên đúng cách. Hãy xem "tác nhân lặp" là một tác nhân tham gia vào một vòng lặp trò chuyện liên tục, dựa trên bộ nhớ của tác nhân đó.
Khi bạn sử dụng cùng một đối tượng phiên cho nhiều truy vấn tuần tự, tác nhân có thể "nhìn thấy" toàn bộ nhật ký cuộc trò chuyện. Điều này cho phép mô hình xử lý các câu hỏi nối tiếp, tự sửa lỗi dựa trên ý kiến phản hồi và lập kế hoạch cho các nhiệm vụ nhiều bước.
➡️ Nơi tìm thấy thông tin trong sổ tay
👉 Phần này tương ứng với các ô trong Phần 3: Agent có bộ nhớ – Công cụ lập kế hoạch thích ứng 🗺️. 🌟
- Định nghĩa về tác nhân: Hàm
create_multi_day_trip_agent()
xác định một tác nhân được thiết kế để lập kế hoạch cho một chuyến đi theo từng bước. Hướng dẫn này nhấn mạnh việc ghi nhớ bối cảnh, xử lý ý kiến phản hồi và lập kế hoạch từng ngày.
Tình huống 3a: Agent CÓ Bộ nhớ (✅)
Thử nghiệm này được chạy trong hàm run_adaptive_memory_demonstration()
.
- Một
trip_session
duy nhất được tạo và dùng lại trong 3 lượt liên tiếp. - Lượt tương tác 1: Người dùng bắt đầu lập kế hoạch cho chuyến đi kéo dài 2 ngày.
- Lượt 2: Người dùng đưa ra ý kiến phản hồi ("Tôi không thích lâu đài lắm"). Vì có bộ nhớ của Lượt 1, nên trợ lý ảo hiểu được phần nào của kế hoạch cần thay đổi và đưa ra một lựa chọn thay thế.
- Lượt 3: Người dùng xác nhận thay đổi và yêu cầu bước tiếp theo. Trợ lý nhớ mọi thứ và tiếp tục lên kế hoạch cho Ngày 2.
Tình huống 3b: Đặc vụ KHÔNG có Bộ nhớ (❌)
Thử nghiệm này được chạy trong hàm run_memory_failure_demonstration()
.
Điều này minh hoạ tầm quan trọng của việc quản lý phiên bằng cách cố tình mắc lỗi. Một phiên mới sẽ được tạo cho mỗi lượt.
- Lượt 1: Người dùng bắt đầu chuyến đi trong session_one. Nhân viên hỗ trợ trả lời chính xác.
- Lượt 2: Người dùng yêu cầu lập kế hoạch cho Ngày 2, nhưng cụm từ tìm kiếm được gửi trong một phiên hoàn toàn mới (session_two). Vì phiên mới này không có nhật ký, nên nhân viên hỗ trợ bị nhầm lẫn. Nó bị mất trí nhớ! Ứng dụng không biết bạn đang lên kế hoạch cho chuyến đi nào.
Hành động: So sánh câu trả lời của nhân viên hỗ trợ trong run_adaptive_memory_demonstration()
và run_memory_failure_demonstration()
. Đây là khái niệm quan trọng nhất trong sổ tay: một cuộc trò chuyện liên tục đòi hỏi một phiên liên tục.
7. Phiên 5: Tác nhân định tuyến 🚏
Một nhân viên hỗ trợ chỉ có thể làm được một số việc nhất định. Để giải quyết những yêu cầu thực sự phức tạp của người dùng, chúng tôi cần một nhóm nhân viên chuyên trách. Nhưng làm cách nào để biết nên sử dụng tác nhân nào cho một truy vấn nhất định? Đây là lúc Router Agent xuất hiện.
Router Agent đóng vai trò là một tác nhân "chính" hoặc một tác nhân điều phối. Mục đích duy nhất của nó là phân tích một truy vấn đến của người dùng và quyết định xem tác nhân chuyên trách (hoặc quy trình làm việc của các tác nhân) nào phù hợp nhất cho công việc. Nó không tự trả lời truy vấn mà chỉ định tuyến truy vấn đến đúng tác nhân hạ nguồn.
Ví dụ: một cụm từ tìm kiếm về "món sushi ngon nhất" sẽ được chuyển đến foodie_agent, trong khi một câu hỏi về "các buổi hoà nhạc vào cuối tuần này" sẽ được weekend_guide_agent
xử lý.
➡️ Nơi tìm thấy thông tin này trong sổ tay:
👉 Khái niệm này là trọng tâm của toàn bộ sổ tay, nhưng lần đầu tiên được giới thiệu trong Phần 1: Cuộc cách mạng của nhiều tác nhân – Quy trình làm việc tuần tự 🧠→🤖→🤖 🌟
- Định nghĩa về các tác nhân: Ô mã xác định nhiều tác nhân chuyên biệt (day_trip_agent, foodie_agent, transportation_agent) và quan trọng nhất là router_agent. Hãy chú ý kỹ đến lời nhắc hướng dẫn cho router_agent, lời nhắc này chỉ rõ rằng chỉ trả về tên của tác nhân phù hợp nhất cho công việc.
- Logic thực thi: Hàm run_sequential_app minh hoạ cách gọi router_agent trước để đưa ra quyết định (chosen_route), sau đó sử dụng quyết định đó trong khối
if/elif
để thực thi tác nhân chuyên gia thích hợp.
8. Phiên 6: SequentialAgent ⛓️
Một số tác vụ yêu cầu nhiều bước theo một thứ tự cụ thể. Ví dụ: "Tìm cho tôi món sushi ngon nhất ở Palo Alto rồi chỉ cho tôi cách đến đó." Đây là quy trình gồm 2 bước: đầu tiên là tìm nhà hàng, sau đó là xem đường đi.
ADK cung cấp một cách thức rõ ràng và hiệu quả để quản lý việc này bằng SequentialAgent. Đây là một tác nhân quy trình công việc đặc biệt, thực thi danh sách các tác nhân phụ theo một thứ tự định sẵn.
Điều kỳ diệu nằm ở trạng thái được chia sẻ. Đầu ra của một tác nhân trong chuỗi có thể tự động lưu vào một từ điển trạng thái dùng chung, sau đó được dùng làm đầu vào cho tác nhân tiếp theo, giúp bạn không cần phải viết mã thủ công phức tạp để truyền thông tin giữa các bước.
➡️ Nơi tìm thấy thông tin này trong sổ tay:
👉 Nội dung này được đề cập trong Phần 2 (Cách ADK): Nhiều tác nhân hỗn loạn với SequentialAgent 🧠→⛓️→🤖. 🌟
- Tái cấu trúc tác nhân: Trong ô mã đầu tiên của phần này, hãy lưu ý những thay đổi chính đối với
foodie_agent
vàtransportation_agent
:foodie_agent
hiện cóoutput_key="destination"
. Thao tác này hướng dẫn ADK lưu câu trả lời cuối cùng vào một biến có tên làdestination
trong trạng thái dùng chung.transportation_agent
hiện có phần giữ chỗ{destination}
trong lời nhắc hướng dẫn. ADK sẽ tự động chèn giá trị từ trạng thái dùng chung vào phần giữ chỗ này.
- Xác định quy trình làm việc:
find_and_navigate_agent
được xác định là SequentialAgent, với sub_agents được đặt thành [foodie_agent
,transportation_agent
], đảm bảo chúng chạy theo đúng thứ tự đó. - Thực thi đơn giản: Xem hàm
run_sequential_app
trong phần này. Logicif/elif
phức tạp đã biến mất!find_and_navigate_agent
hiện được coi là một đơn vị có thể gọi duy nhất và ADK sẽ tự động xử lý các bước tuần tự nội bộ.
9. Phiên 7: LoopAgent 🔁
Không phải vấn đề nào cũng có giải pháp đơn giản và chỉ cần thực hiện một lần. Đôi khi, chúng ta cần đề xuất một giải pháp, phê bình và tinh chỉnh giải pháp đó cho đến khi đáp ứng một ràng buộc cụ thể.
Để làm việc này, ADK cung cấp LoopAgent
. Tác nhân quy trình công việc này sẽ thực thi lặp lại một chuỗi các tác nhân phụ cho đến khi đáp ứng một điều kiện cụ thể. Điều này rất phù hợp để xây dựng các tác nhân "cầu toàn" có thể lên kế hoạch, phê bình và cải thiện công việc của chính mình.
Sơ đồ cho thấy Planner Agent
tạo kế hoạch trước. Sau đó, chúng ta nhập LoopAgent
. Critic Agent
kiểm tra kế hoạch. Nếu có lỗi, Refiner Agent
sẽ tạo một phiên bản mới và vòng lặp sẽ lặp lại. Nếu kế hoạch này phù hợp, Refiner Agent
sẽ gọi công cụ exit_loop
và kế hoạch cuối cùng đã được xác thực sẽ được trả về.
➡️ Nơi tìm thấy thông tin này trong sổ tay:
👉 Điều này được giải thích trong video Đưa ra ý tưởng lặp đi lặp lại bằng LoopAgent 🧠→🔁→🤖. 🌟
- Các tác nhân cốt lõi: Quy trình công việc sử dụng
planner_agent
,critic_agent
vàrefiner_agent
. - Định nghĩa vòng lặp:
refinement_loop
được xác định là một LoopAgent điều phốicritic_agent
,refiner_agent
vàsets max_iterations=3
. - Điều kiện thoát: Vòng lặp sẽ kết thúc khi
critic_agent
phê duyệt kế hoạch, dẫn đến việcrefiner_agent
gọi công cụexit_loop
tuỳ chỉnh.
10. Phiên 8: ParallelAgent ⚡️
Hiệu quả là yếu tố then chốt. Nếu người dùng yêu cầu nhiều thông tin không liên quan cùng một lúc, thì việc chạy từng lượt tìm kiếm sẽ rất chậm.
ParallelAgent
là giải pháp. Tác nhân quy trình công việc này thực thi đồng thời một danh sách các tác nhân phụ. Sau khi hoàn tất tất cả các tác vụ song song, kết quả của các tác vụ đó có thể được thu thập và tổng hợp thành một câu trả lời duy nhất và toàn diện.
Sơ đồ này cho thấy ParallelAgent
nhận một truy vấn duy nhất và phân nhánh công việc thành 3 đường dẫn đồng thời. museum_finder
, concert_finder
và restaurant_finder
đều chạy cùng một lúc. Sau khi cả ba hoàn thành, kết quả riêng lẻ của chúng (được lưu vào trạng thái dùng chung) sẽ được kết hợp và chuyển đến Synthesis Agent cuối cùng. Synthesis Agent này sẽ kết hợp các kết quả đó thành một câu trả lời.
➡️ Nơi tìm thấy thông tin này trong sổ tay:
👉 Quy trình này được trình bày chi tiết trong phần Sức mạnh song song với ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟
- Specialist Agents (Các Đặc vụ chuyên trách): Có 3 Đặc vụ chuyên trách được xác định, mỗi Đặc vụ có một output_key riêng biệt (ví dụ: museum_result).
- Quy trình song song: parallel_research_agent được xác định là một ParallelAgent, với 3 tác nhân tìm kiếm được liệt kê là sub_agents.
- Bước tổng hợp: Sau bước song song, một synthesis_agent cuối cùng sẽ thu thập tất cả thông tin từ trạng thái được chia sẻ bằng cách sử dụng các phần giữ chỗ (
{museum_result}
,{concert_result}
, v.v.) để định dạng một bản tóm tắt gọn gàng.
11. Phụ lục: ADK Web – 🍎 Dành cho máy Mac/Linux
Hướng dẫn này sẽ hướng dẫn bạn cách thiết lập và chạy ADK Day Trip Planning Agent trên máy cục bộ.
Điều kiện tiên quyết
- Python 3.8 trở lên
- Python 3.9 trở lên: Cài đặt google-adk==1.5.0 (phiên bản mới nhất có đầy đủ tính năng)
- Python 3.8: Cài đặt google-adk==0.3.0 (phiên bản tương thích)
- Khoá API Google AI Studio
- Kết nối Internet
Bước 1: Sao chép kho lưu trữ
Mở Terminal rồi chạy:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Bước 2: Thiết lập môi trường ảo và cài đặt các phần phụ thuộc
Lựa chọn A: Thiết lập tự động (Nên dùng)
# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh
Cách B: Thiết lập thủ công
# Create virtual environment
python3 -m venv .adk_env
# Activate virtual environment
source .adk_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Bước 3: 🔥 QUAN TRỌNG – Tạo biến môi trường
⚠️ Đừng bỏ qua bước này! Tạo một tệp .env
trong thư mục agent/
:
# Create the .env file
touch agent/.env
# Open it in your default text editor
open agent/.env
Thêm các dòng sau vào tệp:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRITICAL: Thay thế your_actual_api_key_here
bằng khoá API thực tế của bạn!
Bước 4: Kích hoạt Môi trường ảo (nếu chưa kích hoạt)
source .adk_env/bin/activate
Bạn sẽ thấy (.adk_env)
ở đầu dấu nhắc của thiết bị đầu cuối.
Bước 5: Chạy Giao diện web ADK
adk web
Bước 6: Mở trình duyệt
- Mở trình duyệt rồi truy cập vào URL xuất hiện trong cửa sổ dòng lệnh (thường là
http://localhost:8000
) - Trong trình đơn thả xuống ở trên cùng bên trái, hãy chọn
agent
- Bắt đầu trò chuyện với chuyên viên lập kế hoạch chuyến đi trong ngày!
Bạn sẽ thấy cuộc trò chuyện như sau:
Huỷ kích hoạt môi trường
Khi bạn hoàn tất việc xử lý dự án:
deactivate
Lệnh này hoạt động giống nhau trên cả Mac/Linux và Windows. Bạn sẽ thấy tiền tố (.adk_env)
biến mất khỏi lời nhắc trên thiết bị đầu cuối.
Khắc phục sự cố trên máy Mac
- Không tìm thấy Python: Sử dụng
python3
thay vìpython
- Quyền bị từ chối: Chạy
chmod +x setup_venv.sh
trước khi chạy tập lệnh
12. Phụ lục: ADK Web – 🪟 Dành cho người dùng Windows
Hướng dẫn này sẽ hướng dẫn bạn cách thiết lập và chạy ADK Day Trip Planning Agent trên máy cục bộ.
Điều kiện tiên quyết
- Python 3.8 trở lên
- Python 3.9 trở lên: Cài đặt google-adk==1.5.0 (phiên bản mới nhất có đầy đủ tính năng)
- Python 3.8: Cài đặt google-adk==0.3.0 (phiên bản tương thích)
- Khoá API Google AI Studio
- Kết nối Internet
Bước 1: Sao chép kho lưu trữ
Mở Command Prompt hoặc PowerShell rồi chạy:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Bước 2: Thiết lập môi trường ảo và cài đặt các phần phụ thuộc
Lựa chọn A: Thiết lập tự động (Nên dùng)
# Run the setup script in Command Prompt
setup_venv.bat
Cách B: Thiết lập thủ công
Đối với Command Prompt:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Đối với PowerShell:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\Activate.ps1
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Bước 3: 🔥 QUAN TRỌNG – Tạo biến môi trường
⚠️ Đừng bỏ qua bước này! Tạo một tệp .env
trong thư mục agent/
:
# Create the .env file
type nul > agent\.env
# Open it in Notepad
notepad agent\.env
Thêm các dòng sau vào tệp:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRITICAL: Thay thế your_actual_api_key_here
bằng khoá API thực tế của bạn!
Bước 4: Kích hoạt Môi trường ảo (nếu chưa kích hoạt)
Dấu nhắc lệnh:
.adk_env\Scripts\activate
PowerShell:
.adk_env\Scripts\Activate.ps1
Bạn sẽ thấy biểu tượng (.adk_env)
ở đầu câu lệnh.
Bước 5: Chạy Giao diện web ADK
adk web
Bước 6: Mở trình duyệt
- Mở trình duyệt rồi truy cập vào URL xuất hiện trong cửa sổ dòng lệnh (thường là
http://localhost:8000
) - Trong trình đơn thả xuống ở trên cùng bên trái, hãy chọn
agent
- Bắt đầu trò chuyện với chuyên viên lập kế hoạch chuyến đi trong ngày!
Khắc phục sự cố trên Windows
- Lỗi chính sách thực thi PowerShell: Chạy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Bạn sẽ thấy cuộc trò chuyện như sau:
Huỷ kích hoạt môi trường
Khi bạn hoàn tất việc xử lý dự án:
deactivate
Lệnh này hoạt động giống nhau trên cả Mac/Linux và Windows. Bạn sẽ thấy tiền tố (.adk_env)
biến mất khỏi lời nhắc trên thiết bị đầu cuối.