Khái niệm

Một danh sách ngắn các khái niệm dùng xuyên suốt tài liệu này. Nếu một thuật ngữ xuất hiện ở trang khác mà không giải thích lại, nghĩa của nó nằm ở đây.

Organization (tổ chức)Sao chép liên kết

Đơn vị cô lập cao nhất. Mọi agent, knowledge base, conversation, end-user, API key... đều thuộc về đúng một organization, và dữ liệu giữa hai organization không bao giờ trộn lẫn — kể cả khi cả hai dùng chung một publishable key sai hay một token hết hạn. Xem Cô lập dữ liệu.

Thành viên & vai tròSao chép liên kết

Người trong tổ chức bạn đăng nhập vào console quản trị (app.harnix.vn) bằng tài khoản được mời. Vai trò và lời mời được quản lý ở Thành viên trong console — xem Khoá API & Thành viên.

AgentSao chép liên kết

Một cấu hình trả lời: provider + model (ví dụ OpenAI, hoặc một endpoint tương thích OpenAI), một system prompt, một cửa sổ lịch sử hội thoại, và tuỳ chọn một ngân sách token mỗi ngày. Một agent có thể được gán knowledge base (để tra cứu) và MCP server (để gọi tool ngoài). Một agent bị tắt (deactivate) vẫn còn đó nhưng từ chối nhận message mới (agent_inactive). Xem Xây dựng agent.

Knowledge base & documentSao chép liên kết

Một knowledge base là một tập hợp document (PDF, Markdown, text) được "ingest" — trích xuất văn bản, chia đoạn, và nhúng vector (embedding) bằng một model embedding cố định cho cả hệ thống. Một document có trạng thái ingest riêng (đang xử lý, hoàn tất, lỗi). Xem Knowledge base.

ToolSao chép liên kết

Hai loại tool một agent có thể gọi trong lúc trả lời:

• knowledge_search — tự động bật khi agent có ít nhất một knowledge base được gán; không có công tắc riêng.
• MCP server — một server bên ngoài nói giao thức MCP (Model Context Protocol), cấu hình URL và header xác thực riêng cho tổ chức bạn.

Xem Tool.

Run & traceSao chép liên kết

Mỗi lần agent trả lời một message là một run: model nghĩ, có thể gọi một hoặc nhiều tool, rồi trả lời. Một trace là toàn bộ diễn biến của run đó — từng bước model gọi, từng tool call, từng kết quả, từng trích dẫn — xem lại được trong console. Run stream theo thời gian thực qua SSE trong lúc đang chạy; xem Streaming và Lượt chạy & Trace.

Conversation & messageSao chép liên kết

Một conversation thuộc về một agent và một end-user; nó chứa một chuỗi message (vai user hoặc assistant) theo thứ tự. Mỗi message của assistant có thể mang citations — nguồn cụ thể trong knowledge base mà agent đã trích dẫn.

End-userSao chép liên kết

Người dùng cuối trò chuyện với agent — không phải thành viên tổ chức bạn, mà là người dùng của sản phẩm bạn. Ba mức danh tính: anonymous (widget tự sinh một id ẩn danh), identified (bạn khẳng định danh tính, có ký hoặc qua API key), và service (một end-user đại diện cho chính API key khi gọi /v2/chat không kèm end_user_id). Xem Xác thực.

API key, publishable key, identity secretSao chép liên kết

Ba credential khác mục đích, đừng nhầm lẫn:

• API key (X-API-Key) — bí mật, chỉ dùng từ backend của bạn, không bao giờ đặt trong HTML hay JavaScript phía trình duyệt. Cho phép gọi thẳng /v2/chat thay mặt end-user của bạn.
• Publishable key (pk_...) — không phải bí mật, được phép nằm trong HTML công khai. Chỉ mở được POST /v2/token, và chỉ khi request tới từ một origin nằm trong danh sách cho phép của tổ chức bạn.
• Identity secret — bí mật nằm ở backend của bạn, dùng để ký (HMAC) một danh tính end-user trước khi giao cho widget, để widget đổi lấy token mà không cần backend bạn tự phát hành token. Xem Đổi lấy token.