ctx.ai

RunJS では ctx.ai を使って AI 従業員タスク を実行できます。JSBlock、JSAction、フォーム、ボタンなどから、指定した AI 従業員へ作業を渡す場面に向いています。

ctx.ai はタスクを実行するための API です。AI 従業員タスクの実行結果は返しません。呼び出し後、タスクは AI 従業員の会話フローに入り、結果はそのセッションで処理されます。

注意

ctx.ai は AI プラグインによって提供されます。AI プラグインが有効でない場合、または現在の RunJS 環境に対応するクライアント機能が読み込まれていない場合、ctx.ai は存在しないことがあります。呼び出す前に ctx.ai?.triggerTask または ctx.ai?.triggerModelTask を確認できます。

メソッド

ctx.ai.triggerTask()

AI 従業員タスクを直接実行します。

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

パラメーター	型	説明
`aiEmployee`	`string \| AIEmployee`	AI 従業員。文字列を渡す場合、`AIEmployee.username` と完全一致で検索され、現在のユーザーがアクセスできる必要があります。
`tasks`	`Task[]`	実行するタスク一覧。
`open`	`boolean`	AI 従業員の会話パネルを開くかどうか。
`auto`	`boolean`	AI 従業員アクションの自動実行セマンティクスを使うかどうか。

よく使う Task フィールド:

フィールド	型	説明
`title`	`string`	タスクタイトル。
`message.system`	`string`	AI 従業員の役割や出力要件を制約するシステムメッセージ。
`message.user`	`string`	このタスクの主要な指示。
`message.workContext`	`ContextItem[]`	タスクで使うページブロックのコンテキスト。
`autoSend`	`boolean`	タスクメッセージを自動送信するかどうか。
`webSearch`	`boolean`	このタスクで Web search を許可するかどうか。
`model`	`{ llmService: string; model: string } \| null`	このタスクで使うモデル。
`skillSettings`	`SkillSettings`	このタスクで使う skills / tools 設定。

ページブロックコンテキストを追加する

message.workContext は現在、ページブロックを渡すために使います。対象ページブロックの FlowModel uid を入れます。

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

フィールド	説明
`type`	`flow-model` 固定。ページブロックコンテキストであることを表します。
`uid`	テーブル、詳細、チャートなど、ページブロックの FlowModel uid。

現在の JSBlock 自体をコンテキストにしたい場合は、現在のモデル uid を使います。

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

モデルを指定する

model は単一タスクのモデルを指定します。省略すると AI 従業員のデフォルトモデル設定が使われます。null を渡すとタスク単位のモデルを指定しません。

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

skills / tools を設定する

skillSettings は単一タスクで利用できる skills と tools を指定します。省略すると AI 従業員自身の能力設定が使われます。

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

すべての skills または tools を明示的に無効にする場合は、空配列を渡し、バージョンフィールドは残します。

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

使用例:

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

aiEmployee に文字列を渡すと、NocoBase は現在のユーザーがアクセスできる AI 従業員を username の完全一致で検索します。

ctx.ai.triggerModelTask()

ページ上の AI 従業員アクションモデルからタスクを読み取り、実行します。

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

パラメーター	型	説明
`uid`	`string`	AI 従業員アクションの FlowModel uid。
`taskIndex`	`number`	タスクのインデックス。`0` から始まります。
`options.open`	`boolean`	AI 従業員の会話パネルを開くかどうか。
`options.auto`	`boolean`	AI 従業員アクションの自動実行セマンティクスを使うかどうか。

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

対象モデルが存在しない、AI 従業員が設定されていない、または指定インデックスにタスクがない場合、タスクは実行されず、コンソールに警告が出力されます。

注意事項

triggerTask() と triggerModelTask() は fire-and-forget です。AI 従業員タスクの実行結果は返しません。
aiEmployee の文字列は AIEmployee.username と完全一致でのみ検索されます。
triggerModelTask() の taskIndex は 0 から始まります。
message.workContext は現在、ページブロックコンテキストのみを表します。

#ctx.ai

#メソッド

#ctx.ai.triggerTask()

#ページブロックコンテキストを追加する

#モデルを指定する

#skills / tools を設定する

#ctx.ai.triggerModelTask()

#注意事項

#関連