Khoá học học máy ứng dụng – Từ người mới bắt đầu đến chuyên gia

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 nhiều 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 nghiên cứu kỹ lưỡng 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.

Toàn bộ lớp học lập trình chính này sẽ là một hành trình thực hành và tôi sẽ hướng dẫn bạn qua 2 sổ tay Colab cốt lõi chứa tất cả mã và ví dụ cho các phiên của chúng ta. Colab 1: Công cụ và bộ nhớ, Colab 2: MultiAgents

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 được 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 những câu trả lời chi tiết, hữu ích.
• 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ý của mình 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 nhiều 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 tác nhân: Hiểu rõ vai trò quan trọng của bộ nhớ đàm thoại, cho phép các tác nhân 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: Lấy khoá API

Thiết lập khoá API Google AI Studio

Để hỗ trợ các AI tác nhân, chúng tôi cần một khoá Gemini API từ Google AI Studio. Đây là cách nhanh nhất để bắt đầu.

Bước 1 – Lấy khoá Gemini API từ AI Studio (1 phút)

1. Mở https://aistudio.google.com/app/apikey trong một thẻ trình duyệt mới.
2. Đăng nhập bằng Tài khoản Google của bạn.
3. Nhấp vào "Tạo khoá API" (ở trên cùng bên phải).
4. Một hộp thoại sẽ mở ra kèm theo một trình đơn thả xuống dự án:
   • Nếu bạn đã tạo một dự án trên Google trước đó: Chọn dự án đó rồi nhấp vào "Tạo khoá API trong dự án hiện có"
   • Nếu dự án KHÔNG có trong danh sách: Nhấp vào "Tạo dự án".

5. Sao chép khoá API xuất hiện. Tham số này bắt đầu bằng AIza... và có khoảng 40 ký tự.

✏️ Dán khoá này vào một nơi an toàn – bạn sẽ cần khoá này cho sổ tay Colab và chế độ thiết lập ADK Web (trong Phụ lục).

Hãy coi khoá API như mật khẩu. Đừng dán khoá này vào các cuộc trò chuyện công khai, ảnh chụp màn hình hoặc cam kết với một kho lưu trữ GitHub công khai.

Bước 2 – Thêm khoá API vào Colab (1 phút)

Mỗi sổ tay có một ô thiết lập để tải khoá API của bạn. Bạn có hai lựa chọn – hãy chọn lựa chọn bạn muốn:

Lựa chọn A: Bí mật của Colab (Nên dùng – khoá vẫn ẩn)

1. Trong sổ tay Colab, hãy nhấp vào biểu tượng khoá 🔑 trong thanh bên trái.
2. Nhấp vào "Thêm khoá bí mật mới".
3. Đặt Tên thành GOOGLE_API_KEY.
4. Dán khoá API (ở Bước 1) vào trường Giá trị.
5. Bật nút chuyển "Quyền truy cập vào sổ tay".

Khi bạn chạy ô thiết lập, ô này sẽ tự động chọn khoá:

✅ API key loaded from Colab Secrets.

Cách B: Dán khi được nhắc (nhanh chóng và dễ dàng)

Nếu bạn bỏ qua Colab Secrets và chạy trực tiếp codelab1 và codelab2, sổ tay sẽ nhắc bạn nhập mật khẩu:

🔑 Enter your Google AI Studio API key: ••••••••

Dán khoá API rồi nhấn Enter. Khoá sẽ không xuất hiện trên màn hình.

✅ API key entered manually.

⚠️ Dù bạn chọn cách nào, hãy nhớ kiểm tra để đảm bảo bạn thấy thông báo xác nhận trước khi chuyển sang bước tiếp theo. Nếu bạn thấy lỗi về khoá API không hợp lệ hoặc bị thiếu, hãy kiểm tra kỹ để đảm bảo khoá của bạn bắt đầu bằng AIza... và có khoảng 40 ký tự.

Sau khi ô khoá API chạy, ô tiếp theo sẽ định cấu hình môi trường:

✅ API key configured (starts with 'AIzaSy...')
✅ Using Google AI Studio (not Vertex AI).

✅ Điểm dừng: Bạn thấy cả hai thông báo ✅ ở trên trong sổ tay. Khoá API của bạn đã được định cấu hình và bạn đã sẵn sàng tạo các tác nhân!

3. Phiên 1: Nhân viên hỗ trợ đầ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 trọn ngày dựa trên yêu cầu của người dùng, bao gồm cả các yếu tố về 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:

• Agent: 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. Nó 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 tác nhân), 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 của người dùng mới và điều phối các bước để tạo ra một phản hồi.

➡️ 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 1: Đặc vụ đầu tiên của bạn – Genie cho chuyến đi 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 tác nhân. Hãy lưu ý chuỗi hướng dẫn chi tiết – đây là câu lệnh cho biết cách hành xử của trợ lý. 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ử: Hàm 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". Tác nhân sử dụng các chỉ dẫn và công cụ Google Tìm kiếm để tìm vị trí 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 truy vấn kiểm thử 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 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 một công cụ hàm là chuỗi tài liệu của nó. 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ụ, những tham số mà công cụ chấp nhận (Args) và những tham số mà 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 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 của trợ lý ảo yêu cầu rõ ràng 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à Trình điều phối hoặc Bộ định tuyến) sẽ uỷ quyền các tác vụ cho những tác nhân khác có mục tiêu cụ thể hơn.

Mẫu này cho phép bạn tạo các tác nhân có thể tái sử dụng theo mô-đun. 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 tác nhân có chuyên môn cao, 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 đóng vai trò là nhân viên hỗ trợ 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à đượ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.
• 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 cung cấp thông tin về 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ợ khách hàng. 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.

➡️ Thao tác: 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 tác nhân 🧠

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 truy vấn một lần. AI 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 Gemini 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

👉 Điều này tương ứng với các ô trong Phần 3: Tác nhân có bộ nhớ – Công cụ lập kế hoạch thích ứng 🗺️. 🌟

• Định nghĩa 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 phải là người hâm mộ lâu đài"). Vì có thông tin về Lượt 1 trong bộ nhớ, 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 session_two hoàn toàn mới. Vì phiên mới này không có nhật ký, nên tác tử bị nhầm lẫn. Nó bị mất trí nhớ! Không biết chuyến đi nào đang được lên kế hoạch.

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 dùng tác nhân nào cho một truy vấn nhất định? Đó 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 câu hỏi mà chỉ định tuyến câu hỏi đó đế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 chiến của nhiều tác nhân – Quy trình làm việc tuần tự 🧠→🤖→🤖 🌟

• Định nghĩa 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 nhân viê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 hai bước: đầu tiên là tìm nhà hàng, sau đó là xem chỉ đường.

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, nhờ đó 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 yêu cầu 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 các tác nhân này chạy theo đúng thứ tự đó.
• Thực thi đơn giản: Hãy xem hàm run_sequential_app trong phần này. Logic if/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ể. Đây là lựa chọn hoàn hảo để xây dựng các tác nhân "cầu toàn" có thể lập kế hoạch, phê bình và cải thiện công việc của chính mình.

Sơ đồ này 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 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:

👉 Nội dung này được giải thích trong video Phát triển ý tưởng nhiều lần 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ối critic_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ệc refiner_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 lấy một truy vấn duy nhất và phân nhánh công việc thành 3 luồng đồ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ó 3 Specialist Agent được xác định, mỗi Specialist Agent 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 của nó.
• 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ìm được 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 (trong bước Thiết lập ở trên)
• 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 trong bước Thiết lập: Lấy khoá API!

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

1. 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)
2. Trong trình đơn thả xuống ở trên cùng bên trái, hãy chọn agent
3. 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 dấu 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 (trong bước Thiết lập ở trên)
• 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 trong bước Thiết lập: Lấy khoá API!

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 (.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

1. 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)
2. Trong trình đơn thả xuống ở trên cùng bên trái, hãy chọn agent
3. 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 dấu nhắc trên thiết bị đầu cuối.