Kiến trúc OpenDots: Kỹ thuật thiết kế Không gian AI Agent cá nhân

Tóm tắt nhanh:
OpenDots là giải pháp không gian làm việc tự triển khai (self-hosted workspace) dành cho AI Agent cá nhân được xây dựng trên nền tảng CopilotKit, kết hợp điều phối đa tác tử (multi-agent) tự chủ, cộng tác tài liệu trực quan và tương tác máy tính trong môi trường sandbox cô lập. Hệ thống định hình các nhân sự AI chuyên biệt (Specialist Dots) thông qua lớp DotAgent kế thừa từ @ag-ui/client. Các phân hệ kỹ thuật cốt lõi bao gồm: tự động hóa môi trường desktop qua container OpenBot xác thực bằng chữ ký HMAC, nghiên cứu web qua giao thức Parallel MCP, và tích hợp kênh Slack kiểm soát truy cập chặt chẽ theo từng tenant.

Phần lớn các AI Agent hỗ trợ lập trình viên hiện nay hoạt động dưới dạng công cụ dòng lệnh (CLI) hoặc khung chat tách biệt. Dù xử lý tốt tác vụ sinh mã nguồn hoặc kiểm tra file cục bộ, kiến trúc đơn lẻ này thường gặp phải rào cản lớn về ngữ cảnh thực thi:

• Ngữ cảnh tri thức bị phân mảnh: Ghi chú, tài liệu đặc tả kỹ thuật (specs) và tài liệu dự án nằm rải rác ở các ứng dụng bên ngoài, buộc người dùng phải liên tục sao chép và dán (copy-paste) thông tin nền vào prompt của agent.
• Rủi ro về đặc quyền hệ thống: Cho phép agent chạy trực tiếp trên shell của máy chủ vật lý (host) tiềm ẩn rủi ro bảo mật nghiêm trọng; ngược lại, các agent bị cô lập hoàn toàn trong khung chat lại không thể tương tác với trình duyệt desktop hay kiểm thử các server chạy cục bộ.
• Vòng lặp tra cứu web kém ổn định: Việc lạm dụng kỹ thuật bóc tách DOM toàn trang (DOM scraping) qua trình duyệt cho các truy vấn tra cứu thông tin cơ bản gây lãng phí tài nguyên tính toán, dễ gãy vỡ khi cấu trúc giao diện thay đổi và làm tăng nguy cơ rò rỉ token theo dõi.

OpenDots giải quyết bài toán phân mảnh này bằng cách hợp nhất quy trình làm việc cá nhân xoay quanh Spaces (Không gian lưu trữ), Specialist Dots (Agent chuyên biệt) và các trang tài liệu Tiptap tích hợp sẵn. Mã nguồn mở của dự án được phân phối theo giấy phép MIT License, xác minh tại LICENSE L1-L21. Về mặt kiến trúc gói phần mềm, hệ thống kết hợp backend Node.js sử dụng Hono framework cùng giao diện người dùng React khởi tạo bằng Vite, được định nghĩa tại package.json L1-L35.

Cơ chế vận hành phân hệ: DotAgent Runtime và giám sát OpenBot

Engine điều phối trung tâm của OpenDots chịu trách nhiệm quản lý vòng đời của từng lượt hội thoại (turn lifecycle), duy trì sự cô lập của môi trường container và điều phối lệnh gọi công cụ (tool execution).

Engine thực thi DotAgent

Mỗi nhân sự trợ lý chuyên biệt trong OpenDots được khởi tạo thông qua lớp DotAgent. Được triển khai tại src/server/dot-agent.ts L28-L55, DotAgent kế thừa lớp trừu tượng AbstractAgent từ gói @ag-ui/client, giúp kết nối trực tiếp agent vào luồng xử lý của CopilotKit runtime.

Để ngăn chặn tình trạng vòng lặp vô hạn khi agent thực hiện chuỗi lệnh gọi công cụ nhiều bước, engine áp đặt một hằng số giới hạn thời gian nghiêm ngặt cho mỗi lượt xử lý:

const TURN_TIME_LIMIT_MS = 90_000;

Nếu một lượt chạy của agent kéo dài quá 90 giây, AbortController sẽ chủ động ngắt tiến trình đang thực thi. Quá trình gọi công cụ được điều phối thông qua @tanstack/ai và @copilotkit/runtime/v2, kết nối linh hoạt các công cụ đọc/ghi trang tài liệu, thao tác máy tính OpenBot và các kỹ năng đã học (learned skills) vào ngữ cảnh của mô hình ngôn ngữ.

Điều khiển máy tính qua OpenBot và xác thực token HMAC

Khi cần thực hiện các tác vụ trên môi trường máy tính như tự động hóa trình duyệt, kiểm tra giao diện UI đã kết xuất (rendered UI) hoặc chạy lệnh kiểm thử trên terminal, OpenDots tích hợp trực tiếp với OpenBot.

Thay vì cấp cho agent quyền truy cập trực tiếp vào hệ điều hành máy chủ của lập trình viên, mọi thao tác đều được định tuyến qua lớp dịch vụ ComputerService, xác minh tại src/server/computer-service.ts L15-L42. Các chốt chặn an toàn kiến trúc bao gồm:

1. Cô lập bằng Container: Mỗi Dot giao tiếp với một trình giám sát container (container supervisor) độc lập hoạt động trên dải cổng mạng từ 1024 đến 65535.
2. Ràng buộc Token bằng mật mã: Mọi kết nối từ OpenDots tới container supervisor đều bắt buộc phải có chữ ký số HMAC-SHA256, được sinh ra từ khóa bí mật gốc (COMPUTER_TOKEN) kết hợp với mã định danh riêng của từng Dot.
3. Cơ chế con người tiếp quản tường minh (Human Takeover): Schema điều khiển luôn theo dõi trạng thái chủ thể giữ quyền nhập liệu hiện tại là bot hay human. Ngay khi người vận hành nhấn nút tiếp quản giao diện, phiên chạy của agent sẽ tạm dừng tức thì và yêu cầu chụp lại trạng thái màn hình mới (resume snapshot) trước khi được phép tiếp tục.

Nghiên cứu web dạng luồng (Streamable) qua Parallel MCP

OpenDots tách biệt rõ ràng giữa tác vụ tự động hóa trình duyệt tương tác và tác vụ tra cứu thông tin web thông thường. Đối với các truy vấn tìm kiếm thông tin và tài liệu, hệ thống định tuyến yêu cầu tới máy chủ MCP tìm kiếm của Parallel, được triển khai tại src/server/parallel.ts L1-L30.

Hàm khởi tạo webSearchProvider hỗ trợ ba chế độ cấu hình: parallel, browser hoặc disabled. Ở chế độ mặc định parallel, các truy vấn được truyền tải qua giao thức Model Context Protocol (MCP) bằng StreamableHTTPClientTransport. Bộ cung cấp này trích xuất tối đa 5 nguồn kết quả phù hợp nhất, đồng thời xác thực nghiêm ngặt rằng mọi URL trả về đều tuân thủ giao thức http: hoặc https: và không chứa thông tin xác thực nhúng trong đường dẫn. Cách tiếp cận này giúp giảm tải hoàn toàn chi phí khởi chạy trình duyệt nặng nề cho các nhu cầu tra cứu dữ liệu tiêu chuẩn.

Hướng dẫn cài đặt và triển khai OpenDots cho lập trình viên

OpenDots được thiết kế tối ưu cho việc tự triển khai cục bộ (local self-hosting) với số lượng phụ thuộc ngoại vi tối thiểu.

Yêu cầu hệ thống và khởi tạo môi trường

Hệ thống yêu cầu môi trường Node.js 22 trở lên. Tiến hành sao chép mã nguồn, cài đặt các gói phụ thuộc và khởi tạo file cấu hình môi trường:

git clone https://github.com/CopilotKit/OpenDots.git
cd OpenDots
npm install
cp .env.example .env

Thiết lập các biến môi trường quan trọng trong file .env:

# Cấu hình nhà cung cấp mô hình AI và CopilotKit Intelligence
OPENAI_API_KEY="sk-..."
COPILOTKIT_INTELLIGENCE_URL="https://api.copilotkit.ai"

# Cấu hình OpenBot container supervisor (Tùy chọn)
COMPUTER_SUPERVISOR_URL="http://127.0.0.1:4040"
COMPUTER_TOKEN="super-secret-hmac-seed"

# Tùy chọn nguồn tìm kiếm web (parallel | browser | disabled - Mặc định: parallel)
WEB_SEARCH_PROVIDER="parallel"
PARALLEL_API_KEY="" # Tùy chọn; hệ thống tự động áp dụng gói miễn phí nếu để trống

Khởi chạy các dịch vụ phát triển (Development Services)

Khởi động toàn bộ không gian làm việc bằng script phát triển tại thư mục gốc:

npm run dev

Lệnh này sử dụng concurrently để chạy song song hai tiến trình: theo dõi và thực thi mã nguồn backend TypeScript tại src/server/index.ts bằng tsx trên cổng 3000, đồng thời phục vụ giao diện frontend Vite React trên cổng 5173. Đối với các môi trường tra cứu headless không yêu cầu giao diện máy tính đầy đủ, dịch vụ trình duyệt độc lập có thể được khởi chạy riêng bằng lệnh:

npm run browser

Cấu hình Specialist Dot tùy chỉnh

Mỗi Specialist Dot đều có thể được phân quyền chi tiết đến từng nhóm công cụ. Bạn có thể tạo một chuyên viên nghiên cứu thông qua giao diện người dùng hoặc khai báo cấu hình trực tiếp trong tầng lưu trữ của workspace:

// Ví dụ khai báo cấu hình một Specialist Dot chuyên trách nghiên cứu
const researchDotConfig = {
  id: "researcher-dot",
  name: "Chuyên viên phân tích tài liệu",
  roleInstructions: `
    Bạn là chuyên gia nghiên cứu kỹ thuật. Hãy phân tích các API công khai,
    đánh giá các đánh đổi về mặt kiến trúc và xuất bản ghi chú có cấu trúc trực tiếp vào Pages.
  `,
  permissions: {
    webResearch: true,
    computerControl: false, // Vô hiệu hóa quyền chạy shell/browser đối với tác vụ thuần nghiên cứu
    mcpConnections: ["github-mcp", "postgres-mcp"],
  },
};

Chính sách bảo mật, giới hạn Telemetry và cơ chế xử lý lỗi

Việc vận hành một không gian AI Agent tự chủ có quyền đọc/ghi tài liệu cục bộ và kết nối ra các nền tảng trò chuyện bên ngoài đòi hỏi các ranh giới kiểm soát bảo mật chặt chẽ.

Kiểm soát truy cập kênh Slack doanh nghiệp

OpenDots cho phép gắn kết các Specialist Dots trực tiếp vào các kênh Slack thông qua gói @copilotkit/channels. Nhằm ngăn chặn các thành viên không có thẩm quyền trong workspace kích hoạt trái phép các tác vụ nội bộ, module src/server/slack-channel.ts L10-L40 thực thi cơ chế xác thực danh tính hai lớp:

• Danh sách duyệt Tenant và Người dùng (Allowlist): Mọi tin nhắn gửi đến đều được đối chiếu điều kiện context.tenant.id === config.slackTeam, đồng thời mã định danh của người gửi phải nằm trong danh sách config.slackUsers. Toàn bộ tin nhắn từ các tài khoản hoặc workspace nằm ngoài danh sách cho phép sẽ bị loại bỏ ngay lập tức.
• Ngăn chặn rò rỉ thông tin nhạy cảm: Hàm xử lý lỗi safeFailure tự động lọc bỏ toàn bộ chi tiết stack trace nội bộ và metadata mạng trước khi ghi log hoặc gửi thông báo lỗi lên kênh Slack, đảm bảo các khóa API hay chuỗi kết nối cơ sở dữ liệu không bao giờ bị phơi bày trên kênh chat chung.

Cơ chế tắt thu thập dữ liệu chẩn đoán (Telemetry Opt-out)

Theo mặc định, CopilotKit Intelligence và OpenDots thu thập dữ liệu thống kê quá trình cài đặt và chẩn đoán lỗi hệ thống. Quản trị viên có thể vô hiệu hóa hoàn toàn tính năng theo dõi này trên toàn bộ nền tảng bằng cách thiết lập hai biến môi trường:

COPILOTKIT_TELEMETRY_DISABLED=true
DO_NOT_TRACK=1

Khi các cờ cấu hình này được bật, cả máy chủ ứng dụng lẫn các bộ chạy kiểm thử (test runners) sẽ bỏ qua bước khởi tạo telemetry và tự động xóa bỏ các gói dữ liệu thống kê cài đặt đang chờ gửi.

Đánh đổi kiến trúc và tiêu chí lựa chọn OpenDots

OpenDots đóng vai trò vừa là một không gian làm việc AI cá nhân hoàn chỉnh, vừa là kiến trúc tham chiếu (reference architecture) tiêu biểu cho hệ sinh thái CopilotKit.

Khi nào nên triển khai OpenDots?

1. Xây dựng Workspace Nghiên cứu & Quản trị Tri thức AI Cá nhân: Phù hợp cho các kỹ sư và nhà nghiên cứu cần một bảng điều khiển hợp nhất giữa soạn thảo tài liệu trực quan (Tiptap), tra cứu thông tin và điều phối nhiều AI Agent có vai trò chuyên biệt.
2. Thử nghiệm Tự động hóa Máy tính qua Container an toàn: Dành cho các đội ngũ kỹ thuật đang đánh giá khả năng điều khiển desktop của OpenBot nhưng yêu cầu cơ chế xác thực token bằng chữ ký HMAC và tính năng chuyển giao quyền điều khiển cho con người (Human-in-the-loop Takeover) an toàn.
3. Kiến trúc mẫu cho hệ sinh thái CopilotKit: Là bản thiết kế chuẩn (blueprint) cấp độ sản phẩm dành cho các lập trình viên muốn tìm hiểu cách tích hợp đồng bộ CopilotKit Threads, Channels, giao thức AG-UI và trình soạn thảo Tiptap.

Các giới hạn vận hành cần lưu ý

• Mô hình trạng thái đơn chủ sở hữu (Single-Owner Architecture): Trạng thái lưu trữ của workspace hiện được thiết kế tối ưu cho một người dùng duy nhất; nếu muốn mở rộng cho đội nhóm nhiều người dùng (multi-tenant RBAC) hoặc cộng tác chỉnh sửa tài liệu đồng thời theo thời gian thực, lập trình viên cần xây dựng thêm tầng phân quyền và đồng bộ dữ liệu.
• Chi phí tài nguyên cho Container OpenBot: Việc duy trì các container môi trường desktop và trình duyệt riêng cho từng Dot để phục vụ bộ công cụ điều khiển máy tính sẽ tiêu tốn thêm đáng kể bộ nhớ RAM và tài nguyên điều phối container so với các agent chỉ gọi API thông thường.