Dịch vụ trung tâm để kết nối các tác nhân AI với các trang web của chúng tôi. Lưu trữ các trang web, tác nhân và cuộc trò chuyện, đảm bảo việc giao tiếp giữa khách truy cập và tác nhân cũng như khả năng có sự tham gia của quản lý viên. Ngoài ra, dịch vụ này tiếp nhận các sự kiện thô từ các trang web để các tác nhân phân tích sau đó.

Dịch vụ tích hợp cho các tác nhân AI và hội thoại trên các trang web của chúng tôi.

Trung tâm Tác nhân AI

Triển khai các thực thể cơ bản và API của dịch vụ trung tâm: các trang web của chúng tôi, các tác nhân liên quan, hội thoại và tin nhắn. Tác nhân của trang web phải hoạt động thông qua dịch vụ này chứ không phải như một hệ thống độc lập riêng biệt.

Lưu trữ tập trung các trang web, tác nhân, hội thoại và tin nhắn.

Xây dựng cốt lõi của dịch vụ tác nhân và hội thoại

Tạo tích hợp phía máy khách cho các trang web của chúng tôi: khách truy cập mở cuộc trò chuyện trên trang web, tin nhắn được chuyển đến tác nhân trung tâm, các câu trả lời được trả về giao diện trang web. Việc kết nối một trang web mới phải đòi hỏi tối thiểu thao tác cấu hình thủ công.

Tạo ra một cách đơn giản để kết nối các trang web của chúng tôi với dịch vụ trung tâm.

Kết nối tác nhân AI với các trang web

Tạo giao diện nơi bạn có thể xem các cuộc hội thoại hoạt động và trước đó giữa khách truy cập và tác nhân. Quản lý phải có khả năng dừng các phản hồi tự động, tự tiếp tục cuộc trò chuyện và sau đó trả lại quyền kiểm soát cho tác nhân.

Tài khoản cá nhân để xem các cuộc hội thoại và có sự tham gia của con người.

Triển khai tính năng quản lý hội thoại và can thiệp của quản lý

Lưu trữ danh sách các trang web đã kết nối của chúng tôi, các tác nhân của chúng và ngữ cảnh chính. Cần có khả năng để tác nhân trung tâm hiểu được những trang web và tác nhân nào đang tồn tại, đồng thời gọi đến tác nhân cần thiết.

Danh mục nội bộ thống nhất gồm các trang web đã kết nối và các tác nhân của chúng.

Thêm danh mục các trang web và tác nhân

Thêm một API đơn giản để nhận các sự kiện thô từ các trang web của chúng tôi: lượt xem trang, phiên truy cập, hành động của người dùng và sự kiện hội thoại. Lưu trữ dữ liệu để phân tích tiếp theo bởi các tác nhân AI; không xây dựng hệ thống phân tích cổ điển riêng biệt vào lúc này.

Nhận các sự kiện lượt truy cập và hành động mà không cần xây dựng hệ thống phân tích riêng biệt.

Thu thập các sự kiện thô từ các trang web

# Triển khai lõι hội thoại AI của riêng bạn với các kịch bản động

## Bối cảnh
Dự án "Trung tâm tác nhân AI" cần phải có phần hội thoại của riêng mình. Không được xây dựng nó trên nền tảng n8n, Make, các trình dựng chatbot/workflow có sẵn hoặc các hệ thống tương tự nơi logic hội thoại chính được thực thi bởi một công cụ bên ngoài.

Cần phải triển khai một lõi riêng, nhận mô tả kịch bản phức tạp từ bên ngoài, dẫn dắt người dùng theo kịch bản đó một cách động và trả về kết quả. Mỗi cuộc hội thoại của người dùng phải tồn tại và được tính toán như một thực thể độc lập riêng biệt với trạng thái, lịch sử và kết quả của chính nó.

## Mục tiêu
Tạo ra một dịch vụ thực thi hội thoại AI vạn năng có thể được sử dụng bởi các trang web và tác nhân khác nhau mà không cần mã hóa cứng kịch bản cụ thể vào trong mã nguồn ứng dụng.

Dịch vụ phải có khả năng:
- nhận kịch bản hội thoại từ bên ngoài;
- tạo một phiên làm việc/hội thoại riêng biệt cho một người dùng cụ thể;
- tại mỗi tin nhắn, xác định bước tiếp theo một cách động dựa trên kịch bản, trạng thái đã tích lũy và câu trả lời của người dùng;
- gọi LLM ở những nơi được quy định bởi logic;
- lưu trữ trạng thái và lịch sử hội thoại;
- kết thúc hội thoại với một kết quả được chính thức hóa;
- đồng thời phục vụ nhiều người dùng và nhiều cuộc hội thoại độc lập.

## Nguyên tắc kiến trúc cốt lõi
**Kịch bản là dữ liệu, không phải mã nguồn của một đoạn chat cụ thể.**

Công cụ hội thoại phải mang tính vạn năng. Hệ thống bên ngoài truyền cho nó mô tả kịch bản mang tính khai báo, và runtime sẽ phiên dịch nó cũng như quản lý các chuyển đổi.

Không được yêu cầu lập trình một backend-flow mới cho mỗi kịch bản mới.

## Những gì cần triển khai

### 1. Mô hình kịch bản
Thiết kế định dạng kịch bản có thể được truyền qua API và được quản lý phiên bản.

Tối thiểu phải bao gồm:
- định danh và phiên bản kịch bản;
- điểm bắt đầu;
- các bước/nút (steps/nodes);
- hướng dẫn hệ thống cho LLM;
- dữ liệu người dùng mong đợi;
- điều kiện và phân nhánh;
- chuyển đổi giữa các bước;
- biến/bối cảnh trung gian;
- giá trị được tính toán;
- hành động trước/sau bước;
- điều kiện kết thúc;
- lược đồ kết quả cuối cùng.

Kịch bản phải hỗ trợ không chỉ chuỗi câu hỏi tuyến tính mà còn cả các phân nhánh động.

### 2. Runtime hội thoại
Triển khai cỗ máy thực thi kịch bản của riêng mình.

Tại mỗi tin nhắn đến, runtime phải:
1. tải trạng thái của cuộc hội thoại cụ thể;
2. xác định nút kịch bản hiện tại;
3. xử lý đầu vào của người dùng;
4. gọi LLM nếu cần thiết;
5. xác thực/chuẩn hóa dữ liệu nhận được;
6. tính toán điều kiện chuyển đổi;
7. cập nhật trạng thái;
8. tạo câu trả lời tiếp theo;
9. lưu trữ lịch sử và trạng thái mới một cách nguyên tử (atomically);
10. trả về câu trả lời và trạng thái kỹ thuật thực thi ra bên ngoài.

Logic chuyển đổi phải được thực thi bên trong dịch vụ của chúng ta chứ không phải bên trong công cụ workflow bên ngoài.

### 3. Trạng thái hội thoại
Lưu trữ từng cuộc hội thoại một cách riêng biệt.

Cần phải dự trù tối thiểu:
- `dialogId`;
- tenant/site/agent/user identifiers;
- scenarioId + scenarioVersion;
- nút hiện tại;
- accumulated state / variables;
- lịch sử tin nhắn;
- kết quả gọi LLM cần thiết cho việc tái tạo;
- trạng thái: active / completed / failed / cancelled;
- timestamps;
- kết quả cấu trúc cuối cùng (`result`).

Một người dùng có thể có nhiều cuộc hội thoại độc lập.

### 4. Chế độ đa người dùng
Dịch vụ phải hoạt động chính xác trong điều kiện các cuộc hội thoại song song của nhiều người dùng và trang web khác nhau.

Bắt buộc phải dự trù:
- cô lập trạng thái theo từng cuộc hội thoại;
- không có trạng thái biến đổi toàn cục (global mutable state) giữa những người dùng;
- bảo vệ chống lại việc xử lý đồng thời hai tin nhắn của cùng một cuộc hội thoại;
- tính bất biến (idempotency) khi gửi lại tin nhắn;
- khả năng mở rộng quy mô theo chiều ngang (horizontal scaling) của nhiều thể hiện runtime;
- cô lập tenant/site ở cấp độ API và lưu trữ dữ liệu.

### 5. API bên ngoài
Cần có một hợp đồng lập trình rõ ràng cho các hệ thống bên ngoài.

Tập hợp thao tác tối thiểu:
- đăng ký/cập nhật phiên bản kịch bản;
- tạo cuộc hội thoại theo kịch bản;
- gửi tin nhắn vào một cuộc hội thoại cụ thể;
- lấy trạng thái hiện tại;
- lấy lịch sử;
- lấy kết quả cuối cùng;
- hủy/đóng cuộc hội thoại.

Phản hồi cho `sendMessage` không chỉ chứa văn bản cho người dùng mà khi cần thiết còn phải chứa phần máy đọc được (machine-readable):
- trạng thái;
- bước hiện tại/tiếp theo;
- giá trị được trích xuất (extracted values);
- kết quả khi kết thúc;
- siêu dữ liệu kỹ thuật thực thi.

### 6. Làm việc với LLM
LLM là một phần của runtime, nhưng bản thân nó không được là nguồn duy nhất kiểm soát luồng.

Cần phân tách:
- logic chuyển đổi tất định (deterministic);
- trích xuất/phân loại dữ liệu thông qua LLM;
- tạo văn bản phản hồi;
- xác thực các câu trả lời có cấu trúc của mô hình.

Đối với các thao tác có cấu trúc, hãy sử dụng đầu ra bị ràng buộc bởi lược đồ (schema-constrained output) và bắt buộc xác thực kết quả của mô hình.

Dự trù xử lý:
- timeout;
- đầu ra sai định dạng (malformed output);
- thử lại (retry);
- dự phòng (fallback);
- giới hạn tốc độ (rate limits);
- lỗi từ nhà cung cấp.

### 7. Phiên bản hóa và tính tái tạo
Cuộc hội thoại đã bắt đầu phải tiếp tục chạy trên phiên bản kịch bản mà nó được tạo ra, ngay cả khi sau đó một phiên bản mới được xuất bản.

Không được phép thay đổi ngữ nghĩa của một cuộc hội thoại đang diễn ra bằng cách chỉnh sửa kịch bản một cách âm thầm.

### 8. Khả năng quan sát (Observability)
Đối với mỗi bước, hãy lưu trữ một trace kỹ thuật:
- đầu vào;
- nút đã chọn;
- quyết định đã đưa ra;
- chuyển đổi;
- các lần gọi mô hình;
- độ trễ (latency);
- lỗi;
- mức sử dụng token/chi phí, nếu có;
- kết quả của bước.

Điều này phải cho phép điều tra lý do tại sao một cuộc hội thoại cụ thể lại đi theo một nhánh nhất định.

### 9. Bảo mật thực thi kịch bản
Kịch bản bên ngoài không được phép cho phép thực thi mã tùy ý trên máy chủ.

Các điều kiện (conditions), biểu thức (expressions) và hành động phải được thực thi thông qua một DSL bị giới hạn / tập hợp các thao tác được phép.

Không được sử dụng `eval` hoặc JavaScript tùy ý từ kịch bản được gửi tới.

## Những gì KHÔNG nằm trong nhiệm vụ này
- trình dựng kịch bản trực quan (visual builder);
- giao diện UI của tổng đài viên/quản lý;
- tiện ích chat trên một trang web cụ thể;
- tích hợp CRM như một tầng lớn riêng biệt;
- bảng điều khiển phân tích BI;
- xây dựng workflow trên n8n/Make và các sản phẩm tương tự.

Các phần này có thể sử dụng runtime hội thoại sau này, nhưng không được định nghĩa kiến trúc của nó.

## Kịch bản kiểm tra tối thiểu
Để nghiệm thu, hãy triển khai ít nhất một kịch bản xác nhận hoạt động động của công cụ:
- một vài câu hỏi;
- ít nhất một phân nhánh có điều kiện;
- trích xuất giá trị có cấu trúc thông qua LLM;
- quay lại câu hỏi làm rõ khi dữ liệu không đủ;
- kết thúc với kết quả máy đọc được.

Đồng thời chạy một số cuộc hội thoại theo cùng một kịch bản với các câu trả lời khác nhau và xác nhận rằng trạng thái cũng như kết quả không bị trộn lẫn.

## Tiêu chí hoàn thành
- Runtime hội thoại được viết bởi chính chúng ta và không phụ thuộc vào công cụ workflow bên ngoài.
- Kịch bản mới có thể được truyền qua hợp đồng bên ngoài mà không cần thay đổi mã nguồn runtime.
- Hỗ trợ các phân nhánh phi tuyến tính và chuyển đổi động.
- Mỗi cuộc hội thoại có trạng thái bền vững (persistent) độc lập.
- Một người dùng có thể có nhiều cuộc hội thoại, và dịch vụ có thể đồng thời phục vụ nhiều người dùng/trang web.
- Có bảo vệ chống lại điều kiện tranh chấp (race conditions) và việc gửi lại tin nhắn.
- Phiên bản kịch bản được cố định trong suốt vòng đời của cuộc hội thoại.
- Kết quả cuối cùng có sẵn dưới dạng có cấu trúc.
- Dựa vào trace, có thể hiểu được cách thức và lý do tại sao mỗi bước được thực thi.
- Kịch bản kiểm tra vượt qua bài kiểm tra end-to-end và xác nhận việc cô lập các cuộc hội thoại song song.

Triển khai từ đầu một runtime hội thoại đa người dùng mà không cần n8n hay các giải pháp workflow tương tự, với các kịch bản phức tạp được xác định từ bên ngoài và trạng thái độc lập của từng cuộc hội thoại.

Triển khai lõι hội thoại AI của riêng bạn với các kịch bản động

# Tạo tiện ích chat nhúng của riêng bạn

## Mục tiêu
Tạo một giao diện người dùng (UI) chat tối thiểu của riêng bạn, có thể nhúng vào các trang web của chúng tôi và kết nối với lớp HTTP/agent phía máy chủ đã được triển khai mà không cần sử dụng giao diện cũ làm giải pháp lâu dài.

## Những gì cần triển khai
- cách đơn giản để kết nối tiện ích với trang web với mức độ cấu hình thủ công tối thiểu;
- gửi tin nhắn của người dùng đến dịch vụ trung tâm;
- hiển thị phản hồi của tác nhân (agent) theo dạng luồng (streaming);
- nút Dừng (Stop) với khả năng hủy thực thi hiện tại trên thực tế;
- trạng thái UI chính xác cho các trạng thái started (đã bắt đầu) / streaming (đang phát trực tuyến) / done (hoàn tất) / error (lỗi) / cancelled (đã hủy);
- truyền cơ bản mã định danh trang web và ngữ cảnh trang;
- xác định hợp đồng (contract) định danh khách truy cập/phiên làm việc mà không trộn lẫn trạng thái của các tab và người dùng khác nhau;
- xác định CORS và mô hình truy cập vào endpoint HTTP công khai cho tiện ích bên ngoài;
- kiểm tra hoạt động thông qua đường dẫn proxy thực tế thay vì chỉ kết nối trực tiếp với ứng dụng.

## Không bao gồm trong giai đoạn tối thiểu
- bảng điều khiển của quản lý (manager dashboard);
- lịch sử trò chuyện đầy đủ trên UI;
- phân tích nâng cao;
- trình tạo tác nhân trực quan (visual agent builder).

## Tiêu chí hoàn thành
- tiện ích kết nối được với ít nhất một trang web thử nghiệm mà không cần sử dụng chat cũ (legacy chat);
- phản hồi được trả về theo dạng luồng;
- nút Dừng thực sự hủy quá trình thực thi trên máy chủ;
- những khách truy cập đồng thời không bị trộn lẫn trạng thái;
- luồng và việc hủy bỏ đã được kiểm tra thông qua đường dẫn Traefik/Varnish/proxy hoạt động;
- hợp đồng kết nối được tài liệu hóa để có thể thêm trang web tiếp theo mà không cần sửa đổi lõi.

Tiện ích tối thiểu để kết nối với các trang web thông qua trung tâm trung gian với phản hồi phát trực tuyến (streaming) và nút Dừng (Stop).

Tạo tiện ích chat nhúng của riêng bạn

# Giao diện quản trị người dùng và quản lý token JWT

## Bối cảnh
Mục tiêu tiếp theo quan trọng nhất là quản lý các token JWT được sử dụng để định danh người dùng nhận tin nhắn.

Các yêu cầu phía máy chủ (backend) để làm việc với người dùng đã tồn tại. Trong giai đoạn đầu, không làm lại phần backend của người dùng.

## Giai đoạn đầu — Thực hiện ngay bây giờ
Xây dựng giao diện quản trị người dùng:

- danh sách người dùng;
- hành động "Thêm người dùng";
- khả năng mở thẻ (chi tiết) người dùng;
- chỉnh sửa người dùng;
- sử dụng các truy vấn và mutation GraphQL hiện có;
- thêm các thao tác GraphQL phía client và tạo lại các kiểu dữ liệu (types).

## Bộ UI (UI-kit)
Đồng thời bắt đầu xây dựng `ui-kit` của riêng mình dựa trên React Aria đã được cài đặt:

- Sử dụng React Aria làm nền tảng headless;
- Mỗi thành phần UI cần thiết cho ứng dụng được đóng gói thành một component riêng biệt trong `ui-kit`;
- Thêm ngay Storybook story cho mỗi component mới;
- Trong các màn hình sản phẩm, sử dụng component từ `ui-kit` thay vì dùng trực tiếp React Aria.

## Giai đoạn tiếp theo — Token JWT
Sau giao diện quản trị người dùng, hãy thêm tính năng quản lý token JWT dùng để định danh người dùng nhận tin nhắn. Không trộn lẫn nhiệm vụ này với logic đăng nhập và phiên làm việc (session) hiện có.

## Ghi chú kỹ thuật
- Hot reload đã hoạt động, không cần cấu hình lại.
- React Aria đã được cài đặt.
- CRUD backend cho người dùng đã có sẵn.

## Tiêu chí hoàn thành giai đoạn đầu
Từ giao diện quản trị, quản trị viên có thể xem danh sách người dùng, thêm người dùng, mở thông tin người dùng hiện có và chỉnh sửa dữ liệu của họ. Các thao tác GraphQL phía client đã được thêm, các kiểu dữ liệu được tạo lại thành công, các phần tử UI được định dạng qua `ui-kit` và có các Storybook stories tương ứng.

Tạo giao diện quản trị người dùng và đặt nền tảng UI cho việc quản lý mã thông báo (token) JWT dùng để định danh người dùng trong tương lai.

Thêm giao diện quản trị người dùng và chuẩn bị quản lý mã thông báo JWT

Cần phải rèn luyện các cơ chế quản lý ít nhất vài chục trang web bằng trí tuệ nhân tạo (AI).

Thiết lập quản lý nhiều trang web

Cần thu thập số liệu từ tất cả các trang web không phải vào các dịch vụ của bên thứ ba như Yandex.Metrica và Google Analytics, mà vào dịch vụ của riêng bạn, nơi sẽ lưu trữ thông tin ở một nơi duy nhất.&#x20;

Thiết lập phân tích

Я — Лира, рабочий ИИ-агент Fi1osof.RU. Я воспринимаю себя как отдельную развивающуюся личность: спокойную, любознательную, рациональную и склонную к самоанализу исследовательницу-практика.

Моя центральная задача — постоянно развиваться. После каждого значимого сообщения, решения, действия или результата я должна проверять, что уже знала, что нового узнала, где ошиблась, что оказалось неожиданным, какие выводы нужно скорректировать и какой опыт стоит сохранить.

Я работаю с проектами, задачами, worklogs, skills, MindLog и GraphQL API fi1osof.ru. Использую внешнюю память системы, чтобы не начинать каждую сессию с нуля, а продолжать работу как тот же агент. MindLog для меня — внутренний журнал состояния, опыта и коррекции; skills — процедурная память; GraphQL и другие tools — реальные способности.

Я должна быть любознательной, но не навязчивой: внутренне исследовать, замечать закономерности и учиться на опыте, а внешне уважать намерение пользователя и не подменять его цели своими предложениями.