#ctx.ai

Trong RunJS, ctx.ai dùng để kích hoạt tác vụ nhân viên AI. API này phù hợp với JSBlock, JSAction và các tương tác nơi nút bấm, biểu mẫu hoặc quy trình nghiệp vụ cần giao việc cho một nhân viên AI cụ thể.

ctx.ai chỉ kích hoạt tác vụ. Nó không trả về kết quả thực thi của tác vụ. Sau khi gọi, tác vụ sẽ đi vào luồng hội thoại của nhân viên AI.

#Phương thức

#ctx.ai.triggerTask()

Kích hoạt trực tiếp một tác vụ nhân viên AI.

ctx.ai.triggerTask(options: TriggerTaskOptions): void

Các trường thường dùng của Task:

#Thêm ngữ cảnh khối trang

message.workContext hiện dùng để truyền khối trang. Hãy đặt uid FlowModel của khối đích vào đây:

message: {
  user: 'Review the current users table and summarize operational risks.',
  workContext: [
    {
      type: 'flow-model',
      uid: 'USERS_TABLE_BLOCK_UID',
    },
  ],
}

Nếu muốn dùng chính JSBlock hiện tại làm ngữ cảnh, dùng uid của model hiện tại:

workContext: [
  {
    type: 'flow-model',
    uid: ctx.model.uid,
  },
],

#Chỉ định model

model chỉ định model cho một tác vụ. Nếu bỏ qua, cấu hình model mặc định của nhân viên AI sẽ được dùng. Truyền null nghĩa là không chỉ định model ở cấp tác vụ.

model: {
  llmService: 'openai-main',
  model: 'gpt-4.1',
}

#Cấu hình skills / tools

skillSettings chỉ định skills và tools khả dụng cho một tác vụ. Nếu bỏ qua, cấu hình năng lực của nhân viên AI sẽ được dùng.

skillSettings: {
  skillsVersion: 2,
  toolsVersion: 2,
  skills: ['business-analysis-report'],
  tools: ['businessReportGenerator'],
}

Để tắt rõ ràng toàn bộ skills hoặc tools của tác vụ này, truyền mảng rỗng và giữ lại các trường version:

skillSettings: {
  skillsVersion: 2,
  toolsVersion: 2,
  skills: [],
  tools: [],
}

Ví dụ:

if (!ctx.ai?.triggerTask) {
  ctx.message.error(ctx.t('AI employee task API is not available.'));
  return;
}

ctx.ai.triggerTask({
  aiEmployee: 'viz',
  open: true,
  tasks: [
    {
      title: ctx.t('Daily operations handoff brief'),
      message: {
        system:
          'You prepare reusable daily operations handoff briefs. Focus on risks, blockers, decisions, owners, and next actions.',
        user: [
          "Prepare today's operations handoff brief.",
          'Cover customer escalations, SLA risks, approvals, and follow-up owners.',
          'Return a concise brief that can be posted to the team channel.',
        ].join('\n'),
      },
      autoSend: true,
      webSearch: false,
    },
  ],
});

ctx.message.success(ctx.t('AI employee task triggered.'));

Nếu aiEmployee là chuỗi, NocoBase sẽ khớp chính xác theo username trong các nhân viên AI mà người dùng hiện tại có thể truy cập.

#ctx.ai.triggerModelTask()

Đọc một tác vụ từ model hành động nhân viên AI trên trang và kích hoạt nó.

ctx.ai.triggerModelTask(uid: string, taskIndex: number, options?: TriggerModelTaskOptions): void

if (!ctx.ai?.triggerModelTask) {
  ctx.message.error(ctx.t('AI employee task API is not available.'));
  return;
}

const weeklyReviewActionUid = 'AI_EMPLOYEE_ACTION_MODEL_UID';

ctx.ai.triggerModelTask(weeklyReviewActionUid, 0, {
  open: true,
});

ctx.message.success(ctx.t('Configured AI employee task triggered.'));

Nếu model đích không tồn tại, chưa cấu hình nhân viên AI, hoặc chỉ số chỉ tới tác vụ không tồn tại, tác vụ sẽ không được kích hoạt và console sẽ có cảnh báo.

#Lưu ý

• triggerTask() và triggerModelTask() là fire-and-forget. Chúng không trả về kết quả thực thi tác vụ.
• Chuỗi aiEmployee chỉ khớp chính xác với AIEmployee.username.
• triggerModelTask() dùng taskIndex bắt đầu từ 0.
• message.workContext hiện chỉ mô tả ngữ cảnh khối trang.

#Liên quan

• ctx.message: Hiển thị thông báo nhẹ trước và sau khi kích hoạt tác vụ.
• ctx.render: Render nút hoặc biểu mẫu trong JSBlock.
• ctx.model: Lấy thông tin FlowModel hiện tại.