Tham chiếu API — AI

Tổng quan Resources

Plugin AI đăng ký các resource sau thông qua app.resourceManager:

Resource	Mô tả	Quyền
`llmServices`	Quản lý LLM providers	Admin (`pm.ai.llm-services`)
`aiBots`	Quản lý AI bots	Admin (`pm.ai.ai-bots`)
`aiConversations`	Phiên hội thoại	Người dùng đã đăng nhập
`aiMessages`	Tin nhắn trong phiên	Thông qua conversation
`aiTools`	Định nghĩa AI tools	Admin (quản lý), loggedIn (xem)
`aiSkills`	RAG skills / knowledge connectors	Admin (quản lý), loggedIn (xem)
`aiSettings`	Cấu hình AI toàn cục	Admin (`pm.ai.ai-settings`)
`aiMcpClients`	Kết nối MCP servers	Admin (`pm.ai.mcp-settings`)
`aiContextDatasources`	Nguồn dữ liệu ngữ cảnh	loggedIn (xem)
`aiFiles`	Files đính kèm trong chat	loggedIn (tạo)
`ai`	Resource tổng hợp (listModels, v.v.)	Tuỳ action

LLM Services

Tạo LLM service

typescript

await agent.resource('llmServices').create({
  values: {
    name: 'openai-main',
    provider: 'openai',
    apiKey: 'sk-...',
    baseUrl: 'https://api.openai.com/v1',
    defaultModel: 'gpt-4o',
  },
});

Lấy danh sách providers

typescript

const response = await agent.resource('llmServices').list();
// response.body.data = [{ id, name, provider, defaultModel, ... }]

Liệt kê tất cả model khả dụng

typescript

const response = await agent.resource('ai').listAllEnabledModels();
// Trả về danh sách model từ tất cả provider đã kích hoạt

AI Bots

Tạo bot

typescript

await agent.resource('aiBots').create({
  values: {
    name: 'Support Bot',
    username: 'support-bot',
    systemPrompt: 'Bạn là trợ lý hỗ trợ khách hàng chuyên nghiệp...',
    llmServiceId: 1,
    model: 'gpt-4o',
  },
});

Cập nhật bot

typescript

await agent.resource('aiBots').update({
  filterByTk: botId,
  values: {
    systemPrompt: 'System prompt mới...',
    model: 'gpt-4o-mini',
  },
});

Lấy danh sách bot theo user

typescript

// Chỉ trả về bots mà user hiện tại có quyền truy cập (theo role)
const response = await agent.resource('aiBots').listByUser();

Cập nhật prompt cá nhân

typescript

// User có thể tuỳ chỉnh prompt riêng cho bot
await agent.resource('aiBots').updateUserPrompt({
  filterByTk: botUsername,
  values: { userPrompt: 'Trả lời bằng tiếng Việt...' },
});

Conversations & Messages

Tạo conversation

typescript

const conv = await agent.resource('aiConversations').create({
  values: { botId: 1 },
});
const conversationId = conv.body.data.id;

Gửi message

typescript

await agent.resource('aiMessages').create({
  values: {
    conversationId: conversationId,
    content: 'Làm sao để đặt hàng?',
    role: 'user',
  },
});

Lấy lịch sử chat

typescript

const messages = await agent.resource('aiMessages').list({
  filter: { conversationId: conversationId },
  sort: ['createdAt'],
});

Huỷ cuộc hội thoại đang xử lý

Plugin hỗ trợ huỷ qua sync message:

typescript

// Server-side: gửi sync message để abort conversation
plugin.handleSyncMessage({
  type: 'aiBots:abortConversation',
  payload: { sessionId: 'xxx' },
});

AI Tools

Tools là các “khả năng hành động” mà bot có thể gọi khi chat (ví dụ tạo báo cáo, tìm kiếm web, truy vấn dữ liệu). Khi một tool được gán cho bot và model hỗ trợ function calling, bot có thể gọi tool để tạo kết quả có cấu trúc.

Tool: `businessReportGenerator` (Business analysis report)

Tool này tạo báo cáo phân tích dạng “dashboard” gồm:

Nội dung markdown (có cấu trúc theo mục)
Danh sách biểu đồ ECharts (cấu hình options)
UI hiển thị dạng report card và mở modal báo cáo

Cách gán cho bot (UI): Settings → AI → Bots → chọn bot → Tools → bật businessReportGenerator.

Cách gán cho bot (gợi ý): nếu bạn quản lý bot qua API/automation, hãy lưu cấu hình tools vào aiBots theo schema của hệ thống (tên tool + options UI nếu có).

Prompt gợi ý cho người dùng

Để báo cáo hữu ích, hãy nêu rõ khoảng thời gian, KPI, và cách nhóm (theo ngày/tuần/tháng, theo kênh, theo sản phẩm…).

Tool: `subAgentWebSearch` (Web search)

Tool tìm kiếm web realtime (yêu cầu LLM provider có khả năng web search). Phù hợp khi cần:

Tra cứu thông tin công khai mới nhất
Tóm tắt và dẫn nguồn

Trong triển khai, tool trả về kết quả có cấu trúc kèm nguồn; bot sẽ dùng kết quả đó để trả lời.

MCP Clients

Thêm MCP server

typescript

await agent.resource('aiMcpClients').create({
  values: {
    name: 'My MCP Server',
    url: 'http://localhost:3001',
    description: 'Server cung cấp tools bổ sung',
  },
});

AI Settings

Lấy cấu hình công khai

typescript

// Endpoint cho user đã đăng nhập (không cần admin)
const settings = await agent.resource('aiSettings').publicGet();

Database Collections

Collection	Mô tả	Ghi chú
`llmServices`	Cấu hình LLM provider (API key, base URL, model)	Dữ liệu nhạy cảm
`aiBots`	Định nghĩa bot (system prompt, model, tools)	Liên kết M2M với roles
`aiConversations`	Phiên chat	Thuộc về user
`aiMessages`	Tin nhắn trong phiên	Thuộc về conversation
`aiTools`	Định nghĩa AI tools	Đăng ký động hoặc tĩnh
`aiSkills`	RAG skills, datasource connectors	Gán cho bot
`aiSettings`	Cấu hình AI toàn cục	Một bản ghi duy nhất
`aiMcpClients`	MCP server connections	Cung cấp tools động
`aiContextDatasource`	Nguồn dữ liệu ngữ cảnh	Cho work context
`aiFiles`	Files đính kèm trong chat	Lưu qua file-manager
`aiToolMessages`	Log các lần gọi tool	Debugging
`lc-checkpoints`	LangChain checkpoints (agent state)	Tự dọn sau 48h
`lc-checkpoint-blobs`	Blob data cho checkpoints
`lc-checkpoint-writes`	Ghi checkpoint
`users-ai-bots`	Liên kết user ↔ bot (M2M)	Phân quyền
`roles` (mở rộng)	Thêm field `allowNewAiBot`	Default `true`

Giới hạn kỹ thuật

Tham số	Giá trị	Ghi chú
LLM response timeout	60 giây (mặc định)	Tuỳ thuộc provider
File đính kèm	Tối đa 10MB	Cấu hình qua aiSettings
Checkpoint retention	48 giờ	Cron job dọn lúc 2:00 AM
Rate limit	Theo LLM provider	Không giới hạn phía plugin