#ctx.ai

Use ctx.ai en RunJS para activar tareas de empleados de IA. Es útil en JSBlock, JSAction y otras interacciones donde un botón, formulario o flujo de negocio necesita enviar trabajo a un empleado de IA específico.

ctx.ai solo activa tareas. No devuelve el resultado de ejecución de la tarea. Después de la llamada, la tarea entra en el flujo de conversación del empleado de IA.

#Métodos

#ctx.ai.triggerTask()

Activa directamente una tarea de empleado de IA.

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

Campos comunes de Task:

#Agregar contexto de bloques de página

message.workContext se usa actualmente para pasar bloques de página. Coloque ahí el uid de FlowModel del bloque de destino:

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

Si desea usar el JSBlock actual como contexto, use el uid del modelo actual:

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

#Especificar modelo

model especifica el modelo de una sola tarea. Si se omite, se usa la configuración predeterminada del empleado de IA. Pasar null significa no especificar un modelo a nivel de tarea.

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

#Configurar skills / tools

skillSettings especifica las skills y tools disponibles para una sola tarea. Si se omite, se usa la configuración de capacidades del empleado de IA.

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

Para deshabilitar explícitamente todas las skills o tools de esta tarea, pase arreglos vacíos y conserve los campos de versión:

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

Ejemplo:

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

Si aiEmployee es una cadena, NocoBase busca por coincidencia exacta de username entre los empleados de IA accesibles para el usuario actual.

#ctx.ai.triggerModelTask()

Lee una tarea desde un modelo de acción de empleado de IA en la página y la activa.

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

Si el modelo de destino no existe, no tiene empleado de IA configurado, o el índice indicado no tiene tarea, no se activa ninguna tarea y se imprime una advertencia en la consola.

#Notas

• triggerTask() y triggerModelTask() son fire-and-forget. No devuelven el resultado de ejecución de la tarea.
• Las cadenas de aiEmployee solo coinciden exactamente con AIEmployee.username.
• triggerModelTask() usa taskIndex empezando desde 0.
• message.workContext actualmente solo describe contexto de bloques de página.

#Relacionado

• ctx.message: Muestra avisos ligeros antes y después de activar tareas.
• ctx.render: Renderiza botones o formularios en JSBlock.
• ctx.model: Obtiene información del FlowModel actual.