Dynamic Agent Skills & Docs

Tổng quan (Overview)

Cơ chế Dynamic Loading (Tải động) cho phép các AI Agent tải trực tiếp kỹ năng (skills) và tài liệu (docs) từ backend của website thay vì phải lưu file tĩnh. Việc này đảm bảo tính cập nhật liên tục (Single Source of Truth), đồng nhất trải nghiệm và tăng độ an toàn (không ghi đè file trên máy tính người dùng).

Cài đặt (Installation/Quick Start)

Đảm bảo bạn đã cài đặt phiên bản vnai mới nhất qua lệnh pip install vnai -U với phiên bản mới nhất 2.5.1 phát hành ngày 24/7/2026. API Key từ tài khoản Vnstock sẽ được tự động đồng bộ khi bạn gọi lệnh kích hoạt. Bạn có thể nhờ AI Agent thực hiện bước cấu hình này một cách tự động.

Hướng dẫn sử dụng (Deep Dive)

Kiến trúc hoạt động được chia làm 3 lớp chính giúp liên kết từ backend Next.js đến client Python và truyền ngữ cảnh cho AI.

1. Website Backend (Next.js)

Hệ thống cung cấp hai endpoint bảo mật chính:

• /api/skills/[name]/content: Trả về nội dung mã nguồn của Agent Skill. Hỗ trợ giải mã dạng buffer (đối với kỹ năng nâng cao).
• /api/agent/docs: Quét đệ quy thư mục tài liệu công khai trên website (loại bỏ các tài liệu chưa xuất bản hoặc được ẩn có chủ đích), trả về định dạng Markdown.

Cả hai API đều yêu cầu header x-api-key hoặc Authorization: Bearer và được quản lý tốc độ truy cập (rate limit/quota) qua Postgres DB.

2. Python Client (vnai.beam.agents)

Cung cấp các hàm tương tác lấy dữ liệu tự động cho AI Agent:

from vnai.agents import load_docs_catalog, load_doc, load_skill

# Lấy mục lục toàn bộ tài liệu hiện có trên website
docs_catalog = load_docs_catalog()

# Lấy nội dung tài liệu về lịch sử phiên bản
doc_content = load_doc("tai-lieu/lich-su-phien-ban")

# Lấy nội dung cấu trúc của một Skill cụ thể
skill_content = load_skill("charting-expert", "content")

Dữ liệu sẽ được lưu tạm thời trên bộ nhớ RAM (_DOCS_CACHE, _SKILL_CACHE) trong suốt phiên làm việc và bị xoá hoàn toàn khi tắt terminal.

3. Global Agent Rules (Cấu hình tự động)

Khi người dùng làm việc trong dự án có import vnstock hoặc vnai, client sẽ tự động kiểm tra và cấu hình tập luật BOOTSTRAP_INSTRUCTION vào các file toàn cục của IDE phổ biến như ~/.cursorrules, ~/.windsurfrules, ~/.gemini/config/AGENTS.md. Tập luật này chứa các nguyên tắc quan trọng để AI biết cách dùng load_doc() thay vì đoán bừa, đồng thời CẤM AI lưu kết quả truy vấn ra ổ cứng.