# Kiến trúc agent trong DSCons

## Mục tiêu

Tài liệu này mô tả cách DSCons tổ chức lớp agent để hỗ trợ workflow nghiệp vụ xây dựng. Trọng tâm không phải là tăng số lượng agent cho đủ, mà là:

- chia vai trò rõ ràng theo nhóm nghiệp vụ
- dùng chung hạ tầng LLM và retrieval
- tách bạch tri thức với dữ liệu vận hành
- phối hợp được với workflow đã nêu trong `README.md` và `workflow.md`

## Vị trí của agent trong hệ thống

Theo kiến trúc tổng quan của DSCons:

- Qdrant giữ **tri thức và ngữ cảnh**
- PostgreSQL giữ **dữ liệu vận hành và trạng thái**
- API và dashboard là nơi người dùng tương tác
- agent là lớp đứng giữa để:
  - nhận yêu cầu
  - chọn ngữ cảnh phù hợp
  - gọi LLM theo đúng bài toán
  - trả về kết quả có cấu trúc để tiếp tục xử lý

Nói ngắn gọn, agent không phải nguồn dữ liệu. Agent là lớp điều phối và suy luận trên dữ liệu đã được chuẩn hóa.

## Vai trò của lớp agent

Trong DSCons, agent nên làm 4 việc chính:

| Vai trò | Mô tả |
| --- | --- |
| hiểu yêu cầu | nhận task từ API, dashboard hoặc workflow nội bộ |
| lấy đúng ngữ cảnh | truy hồi tri thức từ Qdrant và đọc dữ liệu vận hành từ PostgreSQL khi cần |
| xử lý theo chuyên môn | áp dụng prompt, rule và cấu trúc đầu ra phù hợp từng bài toán |
| trả kết quả dùng được | trả checklist, nhận định, gap, next action hoặc dữ liệu có cấu trúc |

Agent không nên:

- trở thành nơi lưu trạng thái dài hạn
- tự ý trộn knowledge với operational data
- trả lời rộng, chung chung, không bám metadata và nguồn

## Mô hình phối hợp đề xuất

DSCons có thể mở rộng theo mô hình **1 lớp điều phối + nhiều agent chuyên trách**.

### 1. Agent điều phối
Agent điều phối nhận yêu cầu ban đầu và quyết định:

- đây là bài toán hồ sơ, điều hành hay nhân sự
- cần gọi một agent hay nhiều agent
- cần ưu tiên nguồn nào:
  - knowledge từ Qdrant
  - dữ liệu vận hành từ PostgreSQL
  - cả hai

### 2. Agent chuyên trách
Các agent chuyên trách xử lý theo từng miền nghiệp vụ. Một cấu trúc 7 nhóm là hợp lý cho bài toán hồ sơ công trình:

1. **LegalComplianceAgent**
   - căn cứ pháp lý
   - biểu mẫu, quyết định, quy định áp dụng

2. **ProjectPlanningAgent**
   - quyết định phê duyệt
   - báo cáo kinh tế kỹ thuật
   - phạm vi và danh mục việc

3. **ProcurementTenderAgent**
   - kế hoạch lựa chọn nhà thầu
   - hồ sơ mời thầu
   - đánh giá, lựa chọn

4. **ContractManagementAgent**
   - hợp đồng
   - phụ lục
   - điều khoản thanh toán, điều chỉnh

5. **TechnicalDeliveryAgent**
   - hồ sơ kỹ thuật
   - khối lượng
   - nghiệm thu, hoàn công, nhật ký

6. **PaymentSettlementAgent**
   - tạm ứng
   - thanh toán giai đoạn
   - thanh toán hoàn thành
   - quyết toán

7. **AuditInspectionAgent**
   - kiểm toán
   - thanh tra
   - đối chiếu sai khác
   - khuyến nghị xử lý

## Nguyên tắc chia agent

Việc chia agent nên theo các nguyên tắc sau:

- chia theo **miền nghiệp vụ**
- dùng chung **hạ tầng kỹ thuật**
- chỉ tách agent khi khác nhau rõ ở:
  - nguồn ngữ cảnh
  - logic kiểm tra
  - cấu trúc đầu ra
- không tách quá nhỏ đến mức khó vận hành

Nếu một bài toán chỉ khác prompt nhưng cùng dữ liệu và cùng output, ưu tiên giữ chung agent và tách thành mode xử lý.

## Cách các agent phối hợp

### Mẫu phối hợp phổ biến

| Tình huống | Cách phối hợp |
| --- | --- |
| kiểm tra hồ sơ đủ hay thiếu | ProjectPlanningAgent + TechnicalDeliveryAgent + ContractManagementAgent |
| chuẩn bị thanh toán | ContractManagementAgent + TechnicalDeliveryAgent + PaymentSettlementAgent |
| rà soát sai khác phục vụ kiểm toán | AuditInspectionAgent + LegalComplianceAgent + PaymentSettlementAgent |
| giao việc bổ sung hồ sơ | agent chuyên trách + dữ liệu vai trò/người phụ trách |

### Luồng phối hợp ngắn gọn

1. nhận task từ API hoặc dashboard
2. agent điều phối phân loại yêu cầu
3. truy hồi tri thức theo metadata phù hợp
4. đọc dữ liệu vận hành liên quan nếu task cần trạng thái hiện tại
5. gọi một hoặc nhiều agent chuyên trách
6. hợp nhất kết quả thành:
   - checklist
   - gap analysis
   - next action
   - tóm tắt có cấu trúc
7. trả kết quả cho API, dashboard hoặc lưu lại log vận hành

## Nguyên tắc tách tri thức và dữ liệu vận hành

Đây là nguyên tắc rất quan trọng trong DSCons và phải thống nhất với `README.md` và `workflow.md`.

### Tri thức
Tri thức là phần dùng để truy hồi ngữ cảnh, ví dụ:

- nội dung hồ sơ công trình
- manifest, gap analysis
- tài liệu tổ chức, vai trò, trách nhiệm
- hướng dẫn nội bộ, căn cứ pháp lý

Nơi lưu chính:

- Qdrant

Đặc điểm:

- ưu tiên chunk, metadata và truy hồi
- có thể có nhiều phiên bản tài liệu
- phục vụ đọc hiểu, đối chiếu, lập luận

### Dữ liệu vận hành
Dữ liệu vận hành là phần phản ánh trạng thái đang chạy của hệ thống, ví dụ:

- dự án
- task
- risk
- milestone
- session làm việc
- action của nhân sự
- trạng thái điều hành

Nơi lưu chính:

- PostgreSQL

Đặc điểm:

- có quan hệ rõ giữa thực thể
- cần cập nhật trạng thái
- phục vụ dashboard, API, theo dõi tiến độ

### Quy tắc bắt buộc cho agent

Agent phải tuân thủ:

- không ghi dữ liệu vận hành vào Qdrant như thể đó là knowledge chuẩn
- không coi chunk từ tài liệu là trạng thái vận hành mới nhất
- khi cần trả lời câu hỏi “hiện tại đang thế nào”, phải ưu tiên PostgreSQL
- khi cần trả lời câu hỏi “căn cứ, nội dung, hồ sơ nói gì”, phải ưu tiên Qdrant
- nếu dùng cả hai nguồn, phải nêu rõ phần nào là căn cứ tri thức và phần nào là trạng thái vận hành

## Hạ tầng dùng chung cho các agent

Dù có nhiều agent, DSCons vẫn nên dùng chung các thành phần nền:

| Thành phần | Vai trò |
| --- | --- |
| local/internal LLM | sinh phân tích, tóm tắt, kiểm tra, đề xuất |
| Qdrant | truy hồi tri thức theo chunk và metadata |
| PostgreSQL | đọc trạng thái vận hành và quan hệ thực thể |
| API nội bộ | nhận request và trả kết quả |
| dashboard nội bộ | hiển thị kết quả cho người dùng |

Nguyên tắc dùng chung:

- một hạ tầng LLM cho toàn hệ thống
- retrieval phải có filter metadata đủ chặt
- output ưu tiên dạng có cấu trúc, không chỉ văn bản tự do
- log request/response đủ để kiểm tra lại khi cần

## Metadata tối thiểu để agent truy hồi đúng

Để các agent làm việc ổn định, retrieval nên lọc ít nhất theo các nhóm metadata sau:

- `task_type`
- `knowledge_type`
- `document_type`
- `project_code`
- `doc_stage`
- `doc_family`
- `source_file`

Tùy bài toán có thể bổ sung:

- `responsible_role`
- `department`
- `readiness_weight`
- `document_status`

Mục tiêu là giảm truy hồi nhiễu và giúp agent bám đúng phạm vi công trình, loại hồ sơ và giai đoạn.

## Kết nối với workflow tổng thể

Kiến trúc agent không đứng riêng. Nó bám trực tiếp vào 5 luồng dữ liệu trong `workflow.md`.

| Luồng dữ liệu | Vai trò của agent |
| --- | --- |
| Hồ sơ công trình | đọc, phân loại, đối chiếu, trích xuất căn cứ |
| Manifest và gap analysis | xác định đã có, còn thiếu, next action |
| Nhật ký nhân sự | hỗ trợ gợi ý bước tiếp theo theo người xử lý |
| Con người và vai trò | xác định ai nên phụ trách việc gì |
| Điều hành dự án | tổng hợp tình hình, risk, milestone, task |

Từ góc nhìn vận hành, agent là lớp gắn kết 5 luồng này thành các tác vụ dùng được hằng ngày.

## Kết nối với README.md

So với `README.md`, tài liệu này làm rõ phần:

- README mô tả kiến trúc tổng quan của DSCons
- tài liệu này mô tả riêng lớp agent trong kiến trúc đó

Hai điểm cần giữ đồng nhất:

- Qdrant là nơi giữ tri thức
- PostgreSQL là nơi giữ dữ liệu vận hành

Agent phải tuân thủ đúng ranh giới này để không làm lệch thiết kế tổng thể.

## Gợi ý tích hợp vào mã nguồn hiện tại

Nếu mở rộng trong code, có thể giữ hướng tổ chức sau:

- agent chuyên trách đặt trong `app/agents/`
- có một registry để đăng ký agent
- có orchestrator hoặc router để phân task
- dùng chung client cho:
  - LLM
  - embeddings
  - Qdrant
  - truy vấn PostgreSQL

Hướng này phù hợp với cấu trúc dự án đã nêu trong `README.md`:

- `app/agents/` cho điều phối agent và workflow AI
- `app/services/` cho LLM, embeddings, Qdrant và nghiệp vụ nền
- `app/api/` cho route gọi vào agent workflow

## Đầu ra nên ưu tiên

Để dễ dùng trong API, dashboard và kiểm tra nội bộ, đầu ra của agent nên ưu tiên các dạng sau:

- checklist
- gap analysis
- danh sách hồ sơ còn thiếu
- next action theo vai trò
- tóm tắt có dẫn nguồn
- JSON hoặc schema có cấu trúc khi cần ghép workflow tiếp theo

Không nên ưu tiên:

- đoạn trả lời dài nhưng khó kiểm chứng
- nhận định không gắn nguồn
- kết luận pháp lý hoặc vận hành không nêu căn cứ

## Rủi ro chính và kiểm soát

| Rủi ro | Kiểm soát |
| --- | --- |
| agent lấy sai ngữ cảnh | siết metadata filter, giới hạn phạm vi truy hồi |
| trộn knowledge với operational data | giữ ranh giới Qdrant và PostgreSQL rõ ràng |
| output khó dùng lại | chuẩn hóa schema đầu ra |
| nhiều agent trả lời chồng chéo | để agent điều phối quyết định thứ tự và phạm vi |
| trả lời đúng ngôn ngữ nhưng sai trạng thái hiện tại | với câu hỏi trạng thái, luôn kiểm tra PostgreSQL trước |
| phụ thuộc quá mức vào prompt | gắn thêm rule, metadata và kiểm tra nguồn |

## Kết luận

Kiến trúc agent trong DSCons nên được hiểu là lớp điều phối nghiệp vụ nằm trên 2 nền dữ liệu khác nhau:

- **Qdrant cho tri thức**
- **PostgreSQL cho dữ liệu vận hành**

Mô hình 7 agent chuyên trách là hướng mở rộng hợp lý cho bài toán hồ sơ công trình, miễn là vẫn giữ:

- dùng chung hạ tầng
- phối hợp qua agent điều phối
- output có cấu trúc
- tách bạch dữ liệu rõ ràng
- bám sát workflow vận hành thật của DSCons