Bỏ qua đến nội dung chính

Designing effective subagents

                        (Show All)_ · **Bài 3/4** · [🌐 English](../../en/03-designing-effective-subagents/en.md)

← Bài trước · 📋 Mục lục khoá · Bài sau →

Designing effective subagents

👨‍💻 Track: Developer Track · 📚 Course: Introduction to Subagents · 🧭 Path C

📖 Nội dung bài học

Bây giờ bạn đã biết cách tạo subagent, hãy cùng xem xét các mô hình (pattern) giúp chúng hoạt động thực sự hiệu quả. Một subagent được cấu hình kém sẽ dễ bị lạc đề, chạy quá lâu hoặc tạo ra kết quả mà agent chính không thể sử dụng. Các giải pháp nằm ở bốn yếu tố: viết mô tả tốt, định nghĩa định dạng đầu ra (output format), báo cáo các trở ngại và giới hạn quyền truy cập tool.

Cách dữ liệu cấu hình subagent được sử dụng

Khi bạn gửi tin nhắn đến agent trong context window chính, tên và mô tả của mọi subagent có sẵn sẽ được đưa vào system prompt. Đây là cách agent chính quyết định nên kích hoạt subagent nào và khi nào. Nếu bạn muốn kiểm soát tốt hơn thời điểm một subagent được kích hoạt tự động, tên và mô tả là những thứ bạn cần tinh chỉnh.

Mô tả còn đóng vai trò thứ hai. Khi agent chính kích hoạt một subagent, nó sẽ viết một input prompt để bắt đầu nhiệm vụ. Nó dùng phần mô tả như một hướng dẫn để viết prompt đó. Vì vậy, mô tả không chỉ kiểm soát khi nào một subagent chạy, mà còn định hình subagent được yêu cầu làm gì.

Viết mô tả để định hình input prompt

Hãy xem xét một subagent thực hiện code review. Với một mô tả chung chung, agent chính có thể viết một input prompt kiểu như "dùng git diff để tìm các thay đổi hiện tại". Câu lệnh này rất mơ hồ. Subagent sẽ phải tự tìm hiểu xem file nào là quan trọng.

Nếu bạn cập nhật mô tả thêm nội dung như: "Bạn phải yêu cầu agent chỉ rõ chính xác những file nào bạn muốn nó review", agent chính giờ đây sẽ viết một input prompt cụ thể hơn nhiều, liệt kê danh sách các file thực tế cần review.

Kỹ thuật tương tự cũng hiệu quả với các loại subagent khác. Ví dụ, thêm "trả về các nguồn có thể trích dẫn" vào mô tả của một subagent tìm kiếm web sẽ khiến agent chính đưa hướng dẫn đó vào khi giao phó nhiệm vụ.

Định nghĩa định dạng đầu ra (output format)

Cải tiến quan trọng nhất bạn có thể thực hiện cho một subagent là định nghĩa định dạng đầu ra (output format) trong system prompt của nó. Việc này mang lại hai lợi ích:

  • Nó tạo ra các điểm dừng tự nhiên — subagent biết mình đã hoàn thành khi đã điền xong từng phần của định dạng.
  • Nó ngăn subagent chạy quá lâu. Nếu không có đầu ra được định nghĩa rõ ràng, subagent thường khó quyết định khi nào việc nghiên cứu là đủ và có xu hướng chạy lâu hơn mức cần thiết.

Đây là ví dụ về định dạng đầu ra có cấu trúc cho một subagent code review:

Cung cấp bản review của bạn theo định dạng có cấu trúc:

1. Summary: Tóm tắt ngắn gọn những gì bạn đã review và đánh giá tổng thể
2. Critical Issues: Bất kỳ lỗ hổng bảo mật, rủi ro toàn vẹn dữ liệu,
   hoặc lỗi logic nào cần được sửa ngay lập tức
3. Major Issues: Các vấn đề về chất lượng, sai lệch kiến trúc, hoặc
   lo ngại đáng kể về hiệu suất
4. Minor Issues: Sự không nhất quán về phong cách (style), thiếu sót tài liệu, hoặc
   các tối ưu hóa nhỏ
5. Recommendations: Đề xuất cải tiến, cơ hội refactor, hoặc
   các best practice cần áp dụng
6. Approval Status: Tuyên bố rõ ràng về việc code đã sẵn sàng
   để merge/deploy hay cần thay đổi

Định dạng này cung cấp cho subagent một danh sách kiểm tra (checklist) rõ ràng. Khi mọi phần đã được điền xong, subagent biết nó có thể dừng lại.

Báo cáo trở ngại

Khi một subagent phát hiện ra một giải pháp tạm thời (workaround) trong quá trình làm việc — như giải quyết vấn đề phụ thuộc (dependency) hoặc tìm ra một lệnh nhất định cần các flag đặc biệt — những chi tiết đó cần xuất hiện trong bản tóm tắt mà nó trả về. Nếu không, luồng chính (main thread) sẽ phải tự tìm lại những giải pháp đó, gây lãng phí thời gian và token.

Những thứ bạn muốn được hiển thị bao gồm:

  • Vấn đề thiết lập hoặc các đặc điểm kỳ lạ của môi trường
  • Các workaround được phát hiện trong quá trình thực hiện nhiệm vụ
  • Các lệnh cần flag hoặc cấu hình đặc biệt
  • Các dependency hoặc import gây ra lỗi

Cách để có được thông tin này là yêu cầu rõ ràng trong định dạng đầu ra. Thêm phần "Obstacles Encountered" (Trở ngại gặp phải) vào template đầu ra sẽ giúp hiển thị thông tin này một cách đáng tin cậy.

7. Obstacles Encountered: Báo cáo bất kỳ trở ngại nào gặp phải trong
   quá trình review. Có thể là: vấn đề thiết lập, các workaround được phát hiện hoặc
   đặc điểm kỳ lạ của môi trường. Báo cáo các lệnh cần flag hoặc
   cấu hình đặc biệt. Báo cáo các dependency hoặc import gây ra lỗi.

Giới hạn quyền truy cập tool

không phải subagent nào cũng cần truy cập vào mọi tool. Hãy nghĩ về những gì một subagent thực sự cần làm và chỉ cấp cho nó những tool cần thiết cho công việc đó. Việc này giúp: ngăn chặn các tác dụng phụ không mong muốn và làm cho vai trò của mỗi subagent rõ ràng hơn khi bạn có nhiều subagent.

Dưới đây là cách tư duy về quyền truy cập tool cho các loại subagent phổ biến:

  • Subagent nghiên cứu / chỉ đọc (read-only) — Chỉ cần Glob, Grep, và Read. Không thể vô tình sửa đổi file.
  • Code reviewer — Cần quyền Bash để chạy git diff và xem những gì đã thay đổi, nhưng vẫn không cần Edit hoặc Write.
  • Agent chỉnh sửa code / định dạng (styling) — Đây là nơi bạn cấp quyền Edit và Write, vì nhiệm vụ của subagent là thực sự thay đổi code của bạn.

Tổng kết

Các subagent hiệu quả chia sẻ bốn đặc điểm:

  1. Mô tả cụ thể — Mô tả kiểm soát thời điểm subagent được kích hoạt và những hướng dẫn mà nó nhận được. Hãy viết mô tả để điều hướng cả hai.
  2. Đầu ra có cấu trúc — Định nghĩa định dạng đầu ra trong system prompt để subagent biết khi nào hoàn thành và trả về thông tin mà luồng chính có thể sử dụng.
  3. Báo cáo trở ngại — Bao gồm một phần trong định dạng đầu ra cho các workaround, các điểm kỳ lạ và vấn đề để luồng chính không phải tìm lại chúng.
  4. Giới hạn quyền truy cập tool — Chỉ cấp cho subagent những tool nó thực sự cần. Chỉ đọc để nghiên cứu, bash cho reviewer, edit/write chỉ dành cho các agent cần thay đổi code.

Mỗi mô hình này đều đơn giản khi đứng riêng lẻ, nhưng khi kết hợp lại, chúng biến một subagent từ một thứ cố gắng giúp đỡ một cách mơ hồ thành một cộng sự tập trung, có thể dự đoán, hoàn thành đúng hạn và báo cáo rõ ràng.

🎬 Bản ghi video

Source video: WPxWKT_OaU4

📜 Mở rộng bản ghi (đã chỉnh sửa + dịch AI)

Các mô hình thiết kế subagent hiệu quả

Sau khi đã nắm rõ cách tạo các subagent, hãy cùng tìm hiểu các mô hình (patterns) giúp tối ưu hóa hiệu suất của chúng. Trước tiên, chúng ta cần hiểu cách dữ liệu trong file cấu hình subagent được sử dụng. Mỗi khi bạn gửi một tin nhắn đến agent trong cửa sổ ngữ cảnh chính, tên và mô tả của từng subagent sẽ được đưa vào system prompt. Do đó, nếu bạn muốn kiểm soát tốt hơn thời điểm agent chính tự động kích hoạt một subagent, bạn nên tinh chỉnh tên và mô tả của chúng.

Tối ưu hóa Tên và Mô tả để Ủy thác công việc

Lưu ý rằng khi một subagent được kích hoạt, agent chính sẽ soạn thảo một input prompt. Trong quá trình này, nó sử dụng phần mô tả (description) làm chỉ dẫn. Hãy xem xét lại subagent review code của chúng ta. Hiện tại, khi agent chính chạy subagent này, subagent nhận được một input prompt yêu cầu sử dụng git diff để tìm các thay đổi hiện tại.

Nếu muốn agent chính chỉ định chính xác file cần review một cách đáng tin cậy hơn, chúng ta nên cập nhật mô tả thành: "Bạn phải yêu cầu agent chỉ rõ chính xác những file nào cần được review." Bây giờ, khi yêu cầu Claude chạy agent review code, chúng ta sẽ thấy một đầu vào khác biệt.

Bạn cũng có thể điều hướng nội dung mà luồng chính (main thread) truyền đạt cho subagent thông qua phần mô tả. Ví dụ, việc thêm cụm từ "trả về các nguồn có thể trích dẫn" vào mô tả của một subagent tìm kiếm web sẽ khiến luồng chính đưa chỉ dẫn đó vào khi ủy thác tác vụ.

Định nghĩa Định dạng Đầu ra có Cấu trúc

Cải tiến quan trọng nhất mà bạn có thể thực hiện là định nghĩa một định dạng đầu ra (output format) trong system prompt. Điều này tạo ra các điểm dừng tự nhiên cho subagent. Nếu không có định dạng đầu ra rõ ràng, các subagent thường gặp khó khăn trong việc quyết định khi nào việc nghiên cứu đã hoàn tất và có xu hướng chạy lâu hơn nhiều so với các subagent được cung cấp một định dạng đầu ra cụ thể.

Báo cáo Trở ngại và Giải pháp Tạm thời

Khi một subagent phát hiện ra giải pháp tạm thời (workaround) cho một vấn đề nào đó — chẳng hạn như xử lý lỗi dependency hoặc nhận ra một lệnh cụ thể cần các flag đặc biệt — những chi tiết này nên xuất hiện trong bản tóm tắt. Nếu không, luồng chính sẽ phải tự tìm lại những giải pháp đó từ đầu.

Việc yêu cầu báo cáo trở ngại một cách rõ ràng trong định dạng đầu ra sẽ giúp làm nổi bật các thông tin quan trọng như:

  • Các trở ngại gặp phải.
  • Các vấn đề về thiết lập (setup).
  • Các giải pháp tạm thời đã phát hiện hoặc các đặc điểm riêng biệt của môi trường.
  • Các lệnh yêu cầu flag hoặc cấu hình đặc biệt.
  • Các dependency hoặc import gây ra lỗi.

Giới hạn Quyền truy cập Tool và các Ràng buộc

Một subagent chỉ có quyền đọc (read-only) sử dụng các lệnh như glob, grep, và read sẽ không thể vô tình sửa đổi các file. Ràng buộc này làm rõ vai trò của subagent và ngăn chặn các tác dụng phụ không mong muốn.

Hãy cân nhắc xem một subagent thực sự cần làm gì. Nếu nó chỉ thực hiện nhiệm vụ nghiên cứu, nó chỉ cần quyền đọc file, vì vậy hãy giữ nó ở chế độ read-only. Bằng cách đó, nó không thể vô tình thay đổi bất cứ điều gì trong quá trình khám phá. Một subagent review cần chạy git diff để xem các thay đổi, vì vậy hãy cấp cho nó quyền truy cập Bash, nhưng nó vẫn không cần quyền chỉnh sửa file.

Chỉ cấp quyền chỉnh sửa và ghi cho các subagent thực sự có nhiệm vụ thay đổi mã nguồn, ví dụ như một styling agent chuyên áp dụng các cập nhật CSS. Điều này cũng giúp phân biệt rõ mục đích của từng subagent khi bạn có nhiều subagent trong Knowledge Base của mình. Tóm lại, các subagent hiệu quả là những subagent sử dụng đầu ra có cấu trúc, biết báo cáo trở ngại, có mô tả cụ thể và được giới hạn quyền truy cập tool hợp lý.

🔁 Bài học liên quan

📚 Nguồn & ghi nhận

Bài học có hữu ích không?

Góp ý / Báo lỗiPhát hiện sai sót hoặc có ý tưởng cải thiện?