[One Workflow] Register server-side agent builder tools for workflow authoring (elastic#255180)

Close elastic/security-team#15740

## Summary

Registers workflow-related tools and a skill with the Agent Builder,
enabling AI-powered workflow authoring from within the Kibana AI
Assistant.

### Tools added (namespace `platform.workflows.*`)

| Tool | Screenshot |
|---|---|
|
**get_step_definitions**<br/>`platform.workflows.get_step_definitions`<br/>Discover
available workflow step types, their input/config params, categories,
and usage examples. Supports filtering by type, keyword search, or
category. Optionally returns full JSON Schema. | <img width="1600"
height="1400" alt="02-get_step_definitions"
src="https://github.com/user-attachments/assets/f8ecb7a5-2767-4d57-91d0-84d3bf1345be"
/> |
|
**get_trigger_definitions**<br/>`platform.workflows.get_trigger_definitions`<br/>Look
up available trigger types (manual, scheduled, alert) with schemas and
YAML examples. | <img width="1600" height="1400"
alt="03-get_trigger_definitions"
src="https://github.com/user-attachments/assets/8358fa2a-e281-4485-a044-e11439150dff"
/> |
| **get_examples**<br/>`platform.workflows.get_examples`<br/>Search and
retrieve example workflow YAML files from the bundled library. Supports
category and keyword filtering. | <img width="1600" height="1400"
alt="04-get_examples"
src="https://github.com/user-attachments/assets/2d4ba4d4-7ce8-4f68-a8f9-bb36f9701718"
/> |
| **get_connectors**<br/>`platform.workflows.get_connectors`<br/>List
connector instances configured in the user's environment (Slack, Jira,
etc.) to get connector IDs for workflow steps. | <img width="1600"
height="1400" alt="05-get_connectors"
src="https://github.com/user-attachments/assets/26160604-7f57-47bc-92ba-936c4e6dfe8e"
/> |
|
**validate_workflow**<br/>`platform.workflows.validate_workflow`<br/>Validate
a workflow YAML string against all rules (syntax, schema, step name
uniqueness, Liquid templates). | <img width="801" height="401"
alt="Screenshot 2026-03-05 at 20 50 46"
src="https://github.com/user-attachments/assets/d25c63da-541c-4e57-87a6-b33d898e9437"
/> <img width="813" height="1021" alt="Screenshot 2026-03-05 at 20 50
37"
src="https://github.com/user-attachments/assets/e2a780ec-b421-4189-b2fd-cefe52b136cc"
/> |
| **list_workflows**<br/>`platform.workflows.list_workflows`<br/>List
workflows in the user's environment with search, tag, and status
filtering. | <img width="1600" height="1400" alt="07-list_workflows"
src="https://github.com/user-attachments/assets/0b3ae20e-32a6-4031-9f9f-bdabff54a464"
/> |
| **get_workflow**<br/>`platform.workflows.get_workflow`<br/>Retrieve a
specific workflow by ID, including its full YAML definition. | <img
width="1600" height="1400" alt="08-get_workflow"
src="https://github.com/user-attachments/assets/11709457-46e5-48a5-a2fb-2d443533e377"
/> |

### Skill added

- **`workflow-authoring`** — bundles all seven tools above with a
detailed system prompt covering YAML structure, step types, Liquid
templating, connector usage, and self-validation workflow.

### Other changes

- Added `platform.workflows` tool namespace to the Agent Builder
allow-list
- Exported helper utilities from `@kbn/workflows` for building
agent-friendly step/trigger schemas
- Added unit tests for tools

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

Author: Kiryous

src/platform/packages/shared/kbn-workflows/index.ts

@@ -7,14 +7,31 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
+export * from './spec/lib/build_step_schema_for_agent';
 export * from './spec/lib/generate_yaml_schema_from_connectors';
 export * from './spec/lib/get_workflow_json_schema';
 export { getElasticsearchConnectors } from './spec/elasticsearch';
 export { getKibanaConnectors } from './spec/kibana';
 export * from './spec/schema';
 export { builtInStepDefinitions, getBuiltInStepDefinition } from './spec/builtin_step_definitions';
 export type { BuiltInStepDefinition } from './spec/builtin_step_definitions';
-export { StepCategory } from './spec/step_definition_types';
+export {
+  builtInTriggerDefinitions,
+  getBuiltInTriggerDefinition,
+} from './spec/builtin_trigger_definitions';
+export type {
+  BaseTriggerDefinition,
+  TriggerDocumentation,
+} from './spec/builtin_trigger_definitions';
+export {
+  WORKFLOW_EXAMPLES,
+  WORKFLOW_EXAMPLE_IDS,
+  getWorkflowExamples,
+  getWorkflowExample,
+  getWorkflowExamplesDir,
+} from './spec/examples';
+export type { WorkflowExampleEntry } from './spec/examples';
+export { StepCategory, StepCategories } from './spec/step_definition_types';
 export type { BaseStepDefinition, StepDocumentation } from './spec/step_definition_types';
 export * from './types/latest';
 export * from './types/utils';

src/platform/packages/shared/kbn-workflows/server/examples.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+/* eslint-disable import/no-nodejs-modules -- we need this on server to read yaml files */
+import { readFile } from 'fs/promises';
+import path from 'path';
+
+import { getWorkflowExamplesDir, WORKFLOW_EXAMPLE_IDS } from '../spec/examples';
+
+/**
+ * Load the YAML content of a bundled workflow example by its catalog ID.
+ * Returns `undefined` if the ID is not in the allowlist or the file cannot be read.
+ */
+export async function loadWorkflowExampleContent(entry: {
+  id: string;
+  filename: string;
+}): Promise<string | undefined> {
+  if (!WORKFLOW_EXAMPLE_IDS.has(entry.id)) {
+    return undefined;
+  }
+  try {
+    return await readFile(path.join(getWorkflowExamplesDir(), entry.filename), 'utf-8');
+  } catch {
+    return undefined;
+  }
+}

src/platform/packages/shared/kbn-workflows/server/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { ExecutionError } from './errors/execution_error';
+export { loadWorkflowExampleContent } from './examples';
 export {
   getStepExecutionsByIds,
   getStepExecutionsByWorkflowExecution,

src/platform/packages/shared/kbn-workflows/spec/builtin_trigger_definitions.test.ts

@@ -0,0 +1,65 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import {
+  builtInTriggerDefinitions,
+  getBuiltInTriggerDefinition,
+} from './builtin_trigger_definitions';
+
+const EXPECTED_TRIGGER_IDS = ['manual', 'scheduled', 'alert'];
+
+describe('builtInTriggerDefinitions', () => {
+  it('covers all expected trigger types', () => {
+    const ids = builtInTriggerDefinitions.map((d) => d.id);
+    expect(ids.sort()).toEqual([...EXPECTED_TRIGGER_IDS].sort());
+  });
+
+  it.each(EXPECTED_TRIGGER_IDS)('"%s" has a non-empty description', (id) => {
+    const def = builtInTriggerDefinitions.find((d) => d.id === id);
+    expect(def).toBeDefined();
+    expect(def!.description.length).toBeGreaterThan(0);
+  });
+
+  it.each(EXPECTED_TRIGGER_IDS)('"%s" has a non-empty label', (id) => {
+    const def = builtInTriggerDefinitions.find((d) => d.id === id);
+    expect(def).toBeDefined();
+    expect(def!.label.length).toBeGreaterThan(0);
+  });
+
+  it.each(EXPECTED_TRIGGER_IDS)('"%s" has a schema with parse()', (id) => {
+    const def = builtInTriggerDefinitions.find((d) => d.id === id);
+    expect(def).toBeDefined();
+    expect(typeof def!.schema.parse).toBe('function');
+  });
+
+  it.each(EXPECTED_TRIGGER_IDS)('"%s" has non-empty documentation examples', (id) => {
+    const def = builtInTriggerDefinitions.find((d) => d.id === id);
+    expect(def).toBeDefined();
+    expect(def!.documentation.examples.length).toBeGreaterThan(0);
+    expect(def!.documentation.examples[0].length).toBeGreaterThan(0);
+  });
+});
+
+describe('getBuiltInTriggerDefinition', () => {
+  it('returns the definition for a known id', () => {
+    const def = getBuiltInTriggerDefinition('scheduled');
+    expect(def).toBeDefined();
+    expect(def!.id).toBe('scheduled');
+  });
+
+  it('returns the correct definition for alert', () => {
+    const def = getBuiltInTriggerDefinition('alert');
+    expect(def).toBeDefined();
+    expect(def!.id).toBe('alert');
+  });
+
+  it('returns undefined for an unknown id', () => {
+    expect(getBuiltInTriggerDefinition('nonexistent')).toBeUndefined();
+  });
+});

src/platform/packages/shared/kbn-workflows/spec/builtin_trigger_definitions.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { z } from '@kbn/zod/v4';
+import { AlertRuleTriggerSchema, ManualTriggerSchema, ScheduledTriggerSchema } from './schema';
+
+export interface TriggerDocumentation {
+  details?: string;
+  examples: string[];
+}
+
+export interface BaseTriggerDefinition {
+  id: string;
+  label: string;
+  description: string;
+  schema: z.ZodType;
+  documentation: TriggerDocumentation;
+}
+
+export const builtInTriggerDefinitions: BaseTriggerDefinition[] = [
+  {
+    id: 'manual',
+    label: 'Manual',
+    description: 'Trigger a workflow manually via the UI or API',
+    schema: ManualTriggerSchema,
+    documentation: {
+      examples: [
+        `triggers:
+  - type: manual`,
+      ],
+    },
+  },
+  {
+    id: 'scheduled',
+    label: 'Scheduled',
+    description:
+      'Run a workflow on a recurring schedule using a simple interval (e.g. every 5m) or an rrule for complex patterns (specific days, hours)',
+    schema: ScheduledTriggerSchema,
+    documentation: {
+      details:
+        'Supports two formats: simple interval (`every: "5m"`) for fixed-rate schedules, or `rrule` for calendar-based patterns with day-of-week, hour, and timezone control.',
+      examples: [
+        `triggers:
+  - type: scheduled
+    with:
+      every: "5m"`,
+        `triggers:
+  - type: scheduled
+    with:
+      rrule:
+        freq: WEEKLY
+        interval: 1
+        byweekday: [MO, WE, FR]
+        byhour: [9]
+        byminute: [0]
+        tzid: America/New_York`,
+      ],
+    },
+  },
+  {
+    id: 'alert',
+    label: 'Alert',
+    description:
+      'Trigger a workflow when an alerting rule fires. Optionally filter by rule_id or rule_name',
+    schema: AlertRuleTriggerSchema,
+    documentation: {
+      examples: [
+        `triggers:
+  - type: alert`,
+        `triggers:
+  - type: alert
+    with:
+      rule_name: "High CPU Usage"`,
+      ],
+    },
+  },
+];
+
+const builtInTriggerDefinitionsMap = new Map(builtInTriggerDefinitions.map((t) => [t.id, t]));
+
+export function getBuiltInTriggerDefinition(id: string): BaseTriggerDefinition | undefined {
+  return builtInTriggerDefinitionsMap.get(id);
+}

src/platform/packages/shared/kbn-workflows/spec/examples/esql_to_index.yml

@@ -0,0 +1,49 @@
+name: ES|QL Query Output to New Index
+description: Runs an ES|QL query to detect suspicious transactions over $10k, then indexes each result as a SAR report document.
+enabled: true
+
+triggers:
+  - type: manual
+
+steps:
+  - name: detect-amount-over-10k
+    type: elasticsearch.esql.query
+    with:
+      query: >
+        FROM fraud-workshop*
+        | WHERE event.amount >= 10000 AND (wire.inbound.bank_name IS NOT NULL OR wire.outbound.bank_name IS NOT NULL)
+        | GROK account.address "%{GREEDYDATA:account.address}, %{WORD:account.city}, %{WORD:account.state} %{NUMBER:account.zip}$"
+        | DISSECT account.name "%{account.first_name} %{account.last_name}"
+        | RENAME wire.inbound.bank_name AS bank_name
+        | RENAME wire.outbound.bank_name AS bank_name
+        | RENAME wire.inbound.routing_number AS routing_number
+        | RENAME wire.outbound.routing_number AS routing_number
+        | RENAME wire.direction AS direction
+        | STATS SARs = COUNT(*) BY event.amount, account.event, account.address, account.city, account.first_name, account.last_name, account.state, account.zip, account.type, account.telephone_number, bank_name, routing_number, direction
+        | SORT event.amount DESC
+
+  - name: loop_over_columns
+    type: foreach
+    foreach: '{{steps.detect-amount-over-10k.output.values}}'
+    steps:
+      # id uses execution.id + foreach.index to guarantee uniqueness across runs
+      - name: log_to_elasticsearch
+        type: elasticsearch.index
+        with:
+          index: 'sar-reports'
+          id: '{{ execution.id }}-{{ foreach.index }}'
+          document:
+            timestamp: '{{ execution.startedAt }}'
+            total_dollar_amount: '${{ foreach.item[1] }}'
+            activity_description: 'Account had {{ foreach.item[2] }} amount exceeding SAR threshold.'
+            activity_type: '{{ foreach.item[13] }} {{ foreach.item[2] }} in excess of $10,000'
+            financial_institution_name: '${{ foreach.item[11] }}'
+            financial_institution_ein: '${{ foreach.item[12] }}'
+            report_date: '{{ execution.startedAt }}'
+            suspect_first_name: '${{ foreach.item[5] }}'
+            suspect_last_name: '${{ foreach.item[6] }}'
+            suspect_address: '${{ foreach.item[3] }}'
+            suspect_city: '${{ foreach.item[4] }}'
+            suspect_state: '${{ foreach.item[7] }}'
+            suspect_zip: '${{ foreach.item[8] }}'
+            suspect_phone: '${{ foreach.item[10] }}'