#ctx.ai

Use ctx.ai in RunJS to trigger AI employee tasks. It works well in JSBlock, JSAction, and other interactions where a button, form, or business flow needs to hand work to a specific AI employee.

ctx.ai only triggers tasks. It does not return the execution result of the AI employee task. After the call, the task enters the AI employee conversation flow, and the result is handled by the AI employee session.

#Methods

#ctx.ai.triggerTask()

Trigger an AI employee task directly.

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

Common Task fields:

#Add Page Block Context

message.workContext currently passes page blocks. Put the FlowModel uid of the target page block into it:

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

If you want to use the current JSBlock itself as context, use the current model uid:

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

Usually, message.workContext should be placed inside the message of a concrete task. triggerModelTask() reuses the task configured on the target AI employee action, so it also reads message.workContext from that task.

#Specify Model

model specifies the model for a single task. If omitted, the AI employee's default model configuration is used. Passing null means no task-level model is specified.

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

#Configure Skills / Tools

skillSettings specifies the skills and tools available to a single task. If omitted, the AI employee's own capability configuration is used.

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

To explicitly disable all skills or tools for this task, pass empty arrays and keep the version fields:

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

The following example asks viz to generate a handoff brief and opens the AI employee conversation panel:

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.'));

If aiEmployee is a string, NocoBase matches accessible AI employees by username exactly. If no match is found, the task is not triggered and a warning is printed to the console.

#ctx.ai.triggerModelTask()

Read a task from an AI employee action model on the page and trigger it.

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

This method reads the AI employee and task configuration from the target model. It is useful when the task has already been configured on an AI employee action on the page, and RunJS only needs to trigger it.

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.'));

If the target model does not exist, has no AI employee configured, or the specified index has no task, no task is triggered and a warning is printed to the console.

#Which Method to Use

#Notes

• triggerTask() and triggerModelTask() are fire-and-forget. They do not return the execution result of the AI employee task.
• aiEmployee strings only match AIEmployee.username exactly. They do not match nicknames, job titles, or translated names.
• triggerModelTask() uses a 0-based taskIndex.
• triggerModelTask() reads task configuration from the target AI employee action model. If the task needs work context, configure message.workContext on that task.

#Related

• ctx.message: Show lightweight prompts before and after triggering tasks.
• ctx.render: Render buttons or forms in JSBlock.
• ctx.model: Get current FlowModel information.