From cc79ad7b5e851bfb44e4ddc4ad08231d638fd99a Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Thu, 22 Oct 2026 12:29:31 +0200 Subject: [PATCH 1/5] [Agent Builder] Split action-policy-authoring from rule-authoring Kibana #281663 split action-policy handling out of the rule skill in 9.6, and #298119 renamed the skills to rule-authoring and action-policy-authoring and dropped the experimental-features gating. Document both skills, keep the 9.5 behaviour (rule-management, which also composes action policies), and update the inline tools list and the alerting Agent Builder page to match. - Scope agentBuilder:experimentalFeatures to 9.5 and drop alerting:v2:experimentalFeatures as a skill prerequisite. - Add the 9.6 space and project availability limits. - Point links at the moved alerting/esql pages. - Scope the 9.5 save-order rule (policy blocked until rule exists). Squashes the earlier branch history onto current main. Co-Authored-By: Claude Opus 5.5 --- .../agent-builder/builtin-skills-reference.md | 41 +++++++++++++++++-- .../tools/builtin-tools-reference.md | 3 +- ...ate-rules-action-policies-agent-builder.md | 29 ++++++++----- 3 files changed, 59 insertions(+), 14 deletions(-) diff --git a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md index 0ffce72dfb3..d8cc55eee6c 100644 --- a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md +++ b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md @@ -129,14 +129,49 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack ::: -$$$agent-builder-rule-management-skill$$$ `rule-management` {applies_to}`stack: preview 9.5` {applies_to}`serverless: preview` -: Composes, discovers, and modifies alerting rules and action policies from within a conversation. +$$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: preview 9.5+` {applies_to}`serverless: preview` +: Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{kib}} alerting](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules, or {{elastic-sec}} detection rules. + + {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. + + {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. This skill still offers to set up notifications after it composes a rule, then passes the request to `action-policy-authoring`. + + {applies_to}`stack: preview =9.5` This skill composes action policies itself, and is also assigned the `platform.alerting.manage_action_policy` tool. + + :::{dropdown} Assigned tools + `platform.alerting.manage_rule` + + ::: + + **Prerequisites:** + + * The `alerting:v2:enabled` advanced setting turned on, on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This setting is on by default. + * {applies_to}`stack: preview =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on, on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. + * {applies_to}`serverless: preview` An {{obs-serverless}} project. + + Saving a rule requires the **Rules: All** privilege. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). + +$$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` +: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. It applies to a whole {{kib}} space rather than to a single rule, so one policy can match alerts from many rules. + + {applies_to}`serverless: preview` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, change it to `action-policy-authoring`. :::{dropdown} Assigned tools - `platform.alerting.manage_rule`, `platform.alerting.manage_action_policy` + `platform.alerting.manage_action_policy` ::: + **Prerequisites:** + + * The `alerting:v2:enabled` advanced setting turned on, on the **Global Settings** tab. This setting is on by default. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). + * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. + * {applies_to}`serverless: preview` An {{obs-serverless}} project. + + Saving an action policy requires the **Action Policies: All** privilege, and an Enterprise license on {{stack}} deployments. An action policy dispatches to a workflow rather than to a connector directly, so notifications also need a workflow whose steps reference a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). + + **Related skills:** [`rule-authoring`](#agent-builder-rule-authoring-skill) composes the rules whose alerts a policy matches. + ### Streams and significant events $$$agent-builder-streams-management-skill$$$ `streams-management` {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga` diff --git a/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md b/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md index 06c208a2526..3d56f8fbb70 100644 --- a/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md +++ b/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md @@ -504,7 +504,8 @@ Identifier formats depend on the service: Some [built-in skills](../builtin-skills-reference.md) include inline tools that are only available while that skill is active. Because they are scoped to a skill rather than assignable on their own, they are not listed among the namespaced tools in this reference. For example: - The [`dashboards`](../builtin-skills-reference.md#agent-builder-dashboards-skill) skill (`dashboard-management` in 9.4 and 9.5) includes an inline tool for generating and updating dashboards. -- The `rule-management` skill includes the `platform.alerting.manage_rule` and `platform.alerting.manage_action_policy` tools for composing and modifying alerting rules and their action policies. +- The [`rule-authoring`](../builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) includes the `platform.alerting.manage_rule` tool for composing and modifying {{alerting-v2-system}} rules. In 9.5, it also includes `platform.alerting.manage_action_policy`. +- {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` The [`action-policy-authoring`](../builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill includes the `platform.alerting.manage_action_policy` tool for composing and modifying action policies. - The `alert-triage` skill includes the `security.alert-triage` tool for prioritizing the alert queue. :::{tip} diff --git a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md index f51429b51d1..b25a5da7ff4 100644 --- a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md @@ -5,20 +5,20 @@ applies_to: serverless: experimental products: - id: kibana -description: "How Agent Builder creates rules and action policies using the rule management skill, what the agent produces, and the save-order dependency." +description: "Create Universal Alerting rules and action policies with Agent Builder. Describe what to monitor in natural language, review the proposal, and save in dependency order." --- # Create rules and action policies with {{agent-builder}} [create-rules-agent-builder] -Use {{agent-builder}} to create and configure {{alerting-v2-system}} rules and action policies through natural language instead of the rule form. Describe what you want to monitor, and an agent equipped with the rule management skill resolves the data source and proposes a fully configured rule. +Use {{agent-builder}} to create and configure {{alerting-v2-system}} rules and action policies through natural language instead of the rule form. Describe what you want to monitor, and an agent equipped with the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) resolves the data source and proposes a fully configured rule. ## Requirements [create-ai-agent-requirements] Before you start, make sure you have the following: - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). -- **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. -- {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` **The `alerting:v2:experimentalFeatures` advanced setting turned on** - The setting is off by default and applies only to the space where you turn it on. To turn it on, refer to [Try experimental features in a space](../setup.md#alerting-setup-experimental-features). +- {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. +- {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces. - **The required privileges** - Your role needs the [privileges to use {{agent-builder}} and save rules and action policies](../manage/configure-access.md#alerting-agent-builder-privileges). ## Propose and save a rule [ai-agent-rule-proposal] @@ -27,9 +27,9 @@ Before you start, make sure you have the following: To create a rule, go to **Alerting** → **Rules** in the {{observability}} navigation menu, or find **Rules** using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). -Then select the creation path that lets you create the rule with an agent. Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. +Then select the creation path that lets you create the rule with an agent. Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill configured. -The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the {{alerting-v2-system}} data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. +The `rule-authoring` skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the {{alerting-v2-system}} data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. ### Review the proposal [ai-agent-review-proposal] @@ -58,10 +58,17 @@ Use these prompts as a starting point, then adjust them to your data and thresho ## Set up notifications [ai-agent-notification-setup] -After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating workflows and action policies. +After a rule is saved, you can ask the agent to configure notifications. The agent creates the workflows and action policies needed to deliver them. + +{applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself. + +{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill creates action policies. After the `rule-authoring` skill proposes a complete rule, it offers to set up notifications and then passes the request to `action-policy-authoring`. :::{note} -Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, the skill explains the limitation. If the rule is still a draft in the conversation, the skill changes it so matches open alerts before you save it. If the rule is already saved, that setting can't change, so the skill offers to create a new rule with the same query and schedule that opens alerts, then set up notifications on that rule. +Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward: + +- **Unsaved rule** - The agent changes the draft so that matches open alerts, then you save it. +- **Saved rule** - Whether a rule opens alerts can't change after you save it, so the agent offers to create a new rule with the same query and schedule that does, and to set up notifications on that one. ::: - **Workflows** - Workflows are the delivery mechanism. They define what happens when {{alerting-v2-system}} determines that a notification should be sent, such as posting to Slack, emailing a team, triggering PagerDuty, and so on. @@ -73,11 +80,13 @@ Both objects are proposed as inline attachments and must be explicitly saved bef ### Save order [save-order-ai-agent] -The three objects have a dependency chain that determines the order in which they must be saved: +The three objects have a dependency chain that determines the order in which to save them: 1. **Rule** - Save the rule first. The link between the rule and the action policy takes effect only after the rule is saved. 2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. -3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist. +3. **Action policy** - Save the action policy last. + * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` You can't save the action policy until its workflow exists: {{kib}} disables **Create policy** while a workflow destination is still a draft. You can save the policy before the rule, but the policy doesn't apply to the rule's alerts until the rule is saved. + * {applies_to}`stack: experimental =9.5` You can't save the action policy until both its rule and its workflow exist. :::{note} :applies_to: {"stack": "removed 9.6+, experimental =9.5", "serverless": "unavailable"} From e673ac94012d3a933ff33dd188d3907eb7cf9ba7 Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Thu, 22 Oct 2026 12:49:09 +0200 Subject: [PATCH 2/5] Apply writing guidelines on changes --- .../agent-builder/builtin-skills-reference.md | 18 ++++++++---------- ...eate-rules-action-policies-agent-builder.md | 9 +++++---- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md index d8cc55eee6c..e84666a8a6d 100644 --- a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md +++ b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md @@ -132,28 +132,26 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack $$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: preview 9.5+` {applies_to}`serverless: preview` : Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{kib}} alerting](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules, or {{elastic-sec}} detection rules. - {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. + {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. After this skill composes a rule, it offers to set up notifications and passes the request to `action-policy-authoring`. - {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. This skill still offers to set up notifications after it composes a rule, then passes the request to `action-policy-authoring`. - - {applies_to}`stack: preview =9.5` This skill composes action policies itself, and is also assigned the `platform.alerting.manage_action_policy` tool. + {applies_to}`stack: preview =9.5` This skill composes action policies itself. :::{dropdown} Assigned tools - `platform.alerting.manage_rule` + `platform.alerting.manage_rule`, `platform.alerting.manage_action_policy` {applies_to}`stack: preview =9.5` ::: **Prerequisites:** - * The `alerting:v2:enabled` advanced setting turned on, on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This setting is on by default. - * {applies_to}`stack: preview =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on, on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This setting is on by default. + * {applies_to}`stack: preview =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. * {applies_to}`serverless: preview` An {{obs-serverless}} project. Saving a rule requires the **Rules: All** privilege. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). $$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` -: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. It applies to a whole {{kib}} space rather than to a single rule, so one policy can match alerts from many rules. +: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. Each policy applies to a whole {{kib}} space rather than to a single rule, so one policy can match alerts from many rules. {applies_to}`serverless: preview` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, change it to `action-policy-authoring`. @@ -164,11 +162,11 @@ $$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {app **Prerequisites:** - * The `alerting:v2:enabled` advanced setting turned on, on the **Global Settings** tab. This setting is on by default. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). + * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). This setting is on by default. * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. * {applies_to}`serverless: preview` An {{obs-serverless}} project. - Saving an action policy requires the **Action Policies: All** privilege, and an Enterprise license on {{stack}} deployments. An action policy dispatches to a workflow rather than to a connector directly, so notifications also need a workflow whose steps reference a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). + Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. An action policy dispatches to a workflow rather than to a connector directly, so notifications also need a workflow whose steps reference a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). **Related skills:** [`rule-authoring`](#agent-builder-rule-authoring-skill) composes the rules whose alerts a policy matches. diff --git a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md index b25a5da7ff4..5932e7a820c 100644 --- a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md @@ -19,6 +19,7 @@ Before you start, make sure you have the following: - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). - {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. - {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces. +- {applies_to}`serverless: experimental` **An {{obs-serverless}} project** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other project types. - **The required privileges** - Your role needs the [privileges to use {{agent-builder}} and save rules and action policies](../manage/configure-access.md#alerting-agent-builder-privileges). ## Propose and save a rule [ai-agent-rule-proposal] @@ -58,7 +59,7 @@ Use these prompts as a starting point, then adjust them to your data and thresho ## Set up notifications [ai-agent-notification-setup] -After a rule is saved, you can ask the agent to configure notifications. The agent creates the workflows and action policies needed to deliver them. +After you save a rule, you can ask the agent to configure notifications. The agent creates the workflows and action policies needed to deliver them. {applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself. @@ -67,7 +68,7 @@ After a rule is saved, you can ask the agent to configure notifications. The age :::{note} Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward: -- **Unsaved rule** - The agent changes the draft so that matches open alerts, then you save it. +- **Unsaved rule** - The agent changes the draft rule so that it opens alerts. Then you save the rule. - **Saved rule** - Whether a rule opens alerts can't change after you save it, so the agent offers to create a new rule with the same query and schedule that does, and to set up notifications on that one. ::: @@ -80,12 +81,12 @@ Both objects are proposed as inline attachments and must be explicitly saved bef ### Save order [save-order-ai-agent] -The three objects have a dependency chain that determines the order in which to save them: +The three objects depend on each other. Save them in this recommended order: 1. **Rule** - Save the rule first. The link between the rule and the action policy takes effect only after the rule is saved. 2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. 3. **Action policy** - Save the action policy last. - * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` You can't save the action policy until its workflow exists: {{kib}} disables **Create policy** while a workflow destination is still a draft. You can save the policy before the rule, but the policy doesn't apply to the rule's alerts until the rule is saved. + * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` You can't save the action policy until its workflow exists: {{kib}} disables **Create policy** while a workflow destination is still a draft. You can save the policy before the rule, but the policy doesn't apply to the rule's alerts until the rule is saved. * {applies_to}`stack: experimental =9.5` You can't save the action policy until both its rule and its workflow exist. :::{note} From dd97bfcb5d93ff35b4013ed47ba7ef123419cb80 Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Thu, 22 Oct 2026 13:28:32 +0200 Subject: [PATCH 3/5] Apply fact check results --- .../agent-builder/builtin-skills-reference.md | 33 +++++++++++-------- .../tools/builtin-tools-reference.md | 2 +- ...ate-rules-action-policies-agent-builder.md | 8 +++-- 3 files changed, 25 insertions(+), 18 deletions(-) diff --git a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md index e84666a8a6d..8fa4e2e2bab 100644 --- a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md +++ b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md @@ -129,31 +129,35 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack ::: -$$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: preview 9.5+` {applies_to}`serverless: preview` +$$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: experimental 9.5+` {applies_to}`serverless: experimental` : Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{kib}} alerting](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules, or {{elastic-sec}} detection rules. - {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. After this skill composes a rule, it offers to set up notifications and passes the request to `action-policy-authoring`. + {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. After this skill composes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. - {applies_to}`stack: preview =9.5` This skill composes action policies itself. + {applies_to}`stack: experimental =9.5` In 9.5, this skill is named `rule-management` and also composes action policies. :::{dropdown} Assigned tools - `platform.alerting.manage_rule`, `platform.alerting.manage_action_policy` {applies_to}`stack: preview =9.5` + `platform.alerting.manage_rule` + + {applies_to}`stack: experimental =9.5` `platform.alerting.manage_action_policy` ::: **Prerequisites:** - * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` This setting is on by default. - * {applies_to}`stack: preview =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). - * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. - * {applies_to}`serverless: preview` An {{obs-serverless}} project. + * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This setting is on by default. + * {applies_to}`stack: experimental =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * {applies_to}`stack: experimental =9.5` To find or edit saved rules and action policies, the `contextEngine:enabled` advanced setting also turned on. You can find it on the **Space Settings** tab. + * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` To search for saved rules from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Without it, the agent can still create rules, and it can edit a saved rule when you open the agent from that rule's details page. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view. + * {applies_to}`serverless: experimental` An {{obs-serverless}} project. Saving a rule requires the **Rules: All** privilege. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). -$$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` -: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. Each policy applies to a whole {{kib}} space rather than to a single rule, so one policy can match alerts from many rules. +$$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` +: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. Each policy is a space-level object rather than part of a single rule, so one policy can match alerts from many rules. - {applies_to}`serverless: preview` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, change it to `action-policy-authoring`. + {applies_to}`serverless: experimental` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, change it to `action-policy-authoring`. :::{dropdown} Assigned tools `platform.alerting.manage_action_policy` @@ -163,10 +167,11 @@ $$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {app **Prerequisites:** * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). This setting is on by default. - * {applies_to}`stack: preview 9.6+` A space that uses the Classic or {{observability}} solution view. - * {applies_to}`serverless: preview` An {{obs-serverless}} project. + * To search for saved action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Without it, the agent can still create action policies, and it can edit a saved policy when you open the agent from that policy's edit page. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view. + * {applies_to}`serverless: experimental` An {{obs-serverless}} project. - Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. An action policy dispatches to a workflow rather than to a connector directly, so notifications also need a workflow whose steps reference a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). + Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. An action policy dispatches to a workflow rather than to a connector directly, so notifications usually also need a workflow whose steps use a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). **Related skills:** [`rule-authoring`](#agent-builder-rule-authoring-skill) composes the rules whose alerts a policy matches. diff --git a/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md b/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md index 3d56f8fbb70..cd31c21f627 100644 --- a/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md +++ b/explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md @@ -505,7 +505,7 @@ Some [built-in skills](../builtin-skills-reference.md) include inline tools that - The [`dashboards`](../builtin-skills-reference.md#agent-builder-dashboards-skill) skill (`dashboard-management` in 9.4 and 9.5) includes an inline tool for generating and updating dashboards. - The [`rule-authoring`](../builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) includes the `platform.alerting.manage_rule` tool for composing and modifying {{alerting-v2-system}} rules. In 9.5, it also includes `platform.alerting.manage_action_policy`. -- {applies_to}`stack: preview 9.6+` {applies_to}`serverless: preview` The [`action-policy-authoring`](../builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill includes the `platform.alerting.manage_action_policy` tool for composing and modifying action policies. +- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](../builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill includes the `platform.alerting.manage_action_policy` tool for composing and modifying action policies. - The `alert-triage` skill includes the `security.alert-triage` tool for prioritizing the alert queue. :::{tip} diff --git a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md index 5932e7a820c..e46363764fd 100644 --- a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md @@ -5,7 +5,7 @@ applies_to: serverless: experimental products: - id: kibana -description: "Create Universal Alerting rules and action policies with Agent Builder. Describe what to monitor in natural language, review the proposal, and save in dependency order." +description: "Create Universal Alerting rules and action policies with Agent Builder. Describe what to monitor in natural language, review the proposal, and save the rule, workflow, and action policy." --- # Create rules and action policies with {{agent-builder}} [create-rules-agent-builder] @@ -18,6 +18,8 @@ Before you start, make sure you have the following: - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). - {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. +- {applies_to}`stack: experimental =9.5` **To search for and edit existing rules and action policies, the `contextEngine:enabled` advanced setting also turned on** - Turn it on in the same way, in each space where you use the agent. +- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` **To search for existing rules and action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on** - Without it, the agent can still create rules and action policies. It can also edit a saved rule or action policy when you open the agent from that rule's details page or that policy's edit page. To turn it on, refer to [Enable experimental features](/explore-analyze/ai-features/agent-builder/get-started.md#enable-experimental-features-optional). - {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces. - {applies_to}`serverless: experimental` **An {{obs-serverless}} project** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other project types. - **The required privileges** - Your role needs the [privileges to use {{agent-builder}} and save rules and action policies](../manage/configure-access.md#alerting-agent-builder-privileges). @@ -59,11 +61,11 @@ Use these prompts as a starting point, then adjust them to your data and thresho ## Set up notifications [ai-agent-notification-setup] -After you save a rule, you can ask the agent to configure notifications. The agent creates the workflows and action policies needed to deliver them. +After you save a rule, you can ask the agent to configure notifications. The agent proposes the workflows and action policies needed to deliver them. {applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself. -{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill creates action policies. After the `rule-authoring` skill proposes a complete rule, it offers to set up notifications and then passes the request to `action-policy-authoring`. +{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill creates action policies. After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. :::{note} Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward: From 67f9042c51288f0f200188d4d27aecbd7eaec0f5 Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Sat, 24 Oct 2026 19:05:22 +0200 Subject: [PATCH 4/5] update ui naming --- .../agent-builder/builtin-skills-reference.md | 2 +- .../create-rules-action-policies-agent-builder.md | 14 +++++++++----- explore-analyze/alerting/esql/setup.md | 7 +++---- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md index 8fa4e2e2bab..857b255890b 100644 --- a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md +++ b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md @@ -130,7 +130,7 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack ::: $$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: experimental 9.5+` {applies_to}`serverless: experimental` -: Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{kib}} alerting](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules, or {{elastic-sec}} detection rules. +: Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{alerting-v1-system}}](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules created with {{alerting-v1-system}}, or {{elastic-sec}} detection rules. {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. After this skill composes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. diff --git a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md index e46363764fd..4ed847893fe 100644 --- a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md @@ -17,8 +17,8 @@ Use {{agent-builder}} to create and configure {{alerting-v2-system}} rules and a Before you start, make sure you have the following: - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). -- {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`. -- {applies_to}`stack: experimental =9.5` **To search for and edit existing rules and action policies, the `contextEngine:enabled` advanced setting also turned on** - Turn it on in the same way, in each space where you use the agent. +- {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), select the **Space Settings** tab, and turn on `agentBuilder:experimentalFeatures`. +- {applies_to}`stack: experimental =9.5` **To search for and edit existing rules and action policies, the `contextEngine:enabled` advanced setting also turned on** - On the **Space Settings** tab, turn it on in each space where you use the agent. - {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` **To search for existing rules and action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on** - Without it, the agent can still create rules and action policies. It can also edit a saved rule or action policy when you open the agent from that rule's details page or that policy's edit page. To turn it on, refer to [Enable experimental features](/explore-analyze/ai-features/agent-builder/get-started.md#enable-experimental-features-optional). - {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces. - {applies_to}`serverless: experimental` **An {{obs-serverless}} project** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other project types. @@ -30,7 +30,11 @@ Before you start, make sure you have the following: To create a rule, go to **Alerting** → **Rules** in the {{observability}} navigation menu, or find **Rules** using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). -Then select the creation path that lets you create the rule with an agent. Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill configured. +{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` Select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**. + +{applies_to}`stack: experimental =9.5` In the rule creation options, select **Create with agent**. + +Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill configured. The `rule-authoring` skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the {{alerting-v2-system}} data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. @@ -61,11 +65,11 @@ Use these prompts as a starting point, then adjust them to your data and thresho ## Set up notifications [ai-agent-notification-setup] -After you save a rule, you can ask the agent to configure notifications. The agent proposes the workflows and action policies needed to deliver them. +The agent proposes the workflows and action policies needed to deliver notifications. {applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself. -{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill creates action policies. After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. +{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads the [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill, which creates the action policies. :::{note} Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward: diff --git a/explore-analyze/alerting/esql/setup.md b/explore-analyze/alerting/esql/setup.md index 5630d4dd711..86576124120 100644 --- a/explore-analyze/alerting/esql/setup.md +++ b/explore-analyze/alerting/esql/setup.md @@ -62,10 +62,7 @@ stack: experimental 9.6+ To try features of {{alerting-v2-system}} that are still experimental, turn on the **Universal Alerting: Experimental Features** advanced setting (`alerting:v2:experimentalFeatures`). The setting is off by default and applies only to the space where you turn it on. -When the setting is on, you can: - -- Detect multi-step alert patterns by chaining rules into a sequence. On the **Rules** page, select **Build a sequence (Experimental)**. -- Create rules and action policies by describing them to {{agent-builder}} in natural language. Select **Create rule** → **Create with agent (Experimental)** on the **Rules** page, or **Create policy** → **Create with agent (Experimental)** on the **Action Policies** page. {{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements). +When the setting is on, you can detect multi-step alert patterns by chaining rules into a sequence. On the **Rules** page, select **Build a sequence (Experimental)**. To turn on experimental features: @@ -74,6 +71,8 @@ To turn on experimental features: 3. Select the **Space Settings** tab, then turn on **Universal Alerting: Experimental Features**. 4. Select **Save changes**, then reload {{kib}}. +You can create rules and action policies with {{agent-builder}} while this setting is off. On the **Rules** page, select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**. On the **Action Policies** page, select **Create policy** → **Create with agent**. When the Action Policies list is empty, select **Create with AI Agent**. {{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements). + ## Keep the Observability alerts page for {{alerting-v1-system}} [alerting-setup-v1-alerts-page] ```yaml {applies_to} From 8e7bd28f5a86c5a448d46d271f8df7349b66555b Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Sat, 24 Oct 2026 19:25:05 +0200 Subject: [PATCH 5/5] rewrite long pharagraphs --- .../agent-builder/builtin-skills-reference.md | 22 +++++++++++++------ ...ate-rules-action-policies-agent-builder.md | 18 +++++++++------ explore-analyze/alerting/esql/setup.md | 9 ++++++-- 3 files changed, 33 insertions(+), 16 deletions(-) diff --git a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md index 857b255890b..b866f5fa379 100644 --- a/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md +++ b/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md @@ -130,9 +130,15 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack ::: $$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: experimental 9.5+` {applies_to}`serverless: experimental` -: Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover [{{alerting-v1-system}}](/explore-analyze/alerting/alerts.md) rules, {{observability}} rules created with {{alerting-v1-system}}, or {{elastic-sec}} detection rules. +: Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover: - {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, change it to `rule-authoring`. The [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) skill handles notification setup. After this skill composes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. + * [{{alerting-v1-system}}](/explore-analyze/alerting/alerts.md) rules + * {{observability}} rules created with {{alerting-v1-system}} + * {{elastic-sec}} detection rules + + {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, replace that id with `rule-authoring`. + + {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) sets up notifications. After this skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`. {applies_to}`stack: experimental =9.5` In 9.5, this skill is named `rule-management` and also composes action policies. @@ -148,16 +154,18 @@ $$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$ * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This setting is on by default. * {applies_to}`stack: experimental =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). * {applies_to}`stack: experimental =9.5` To find or edit saved rules and action policies, the `contextEngine:enabled` advanced setting also turned on. You can find it on the **Space Settings** tab. - * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` To search for saved rules from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Without it, the agent can still create rules, and it can edit a saved rule when you open the agent from that rule's details page. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` To search for saved rules from a conversation, turn on `agentBuilder:experimentalFeatures` on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). The agent can still create rules with this setting off. It can also edit a saved rule from that rule's details page. * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view. * {applies_to}`serverless: experimental` An {{obs-serverless}} project. Saving a rule requires the **Rules: All** privilege. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). $$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` -: Composes, discovers, and modifies action policies from within a conversation. Use when a user asks to set up, change, or inspect alert notifications, such as sending email or paging an on-call responder. An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and dispatched to workflows. Each policy is a space-level object rather than part of a single rule, so one policy can match alerts from many rules. +: Composes, discovers, and modifies action policies from within a conversation. Use it to set up, inspect, or edit alert notifications, such as email or paging an on-call responder. + + An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and sent to workflows. A policy belongs to a space, so one policy can match alerts from many rules. - {applies_to}`serverless: experimental` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, change it to `action-policy-authoring`. + {applies_to}`serverless: experimental` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, replace that id with `action-policy-authoring`. :::{dropdown} Assigned tools `platform.alerting.manage_action_policy` @@ -167,11 +175,11 @@ $$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {app **Prerequisites:** * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). This setting is on by default. - * To search for saved action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Without it, the agent can still create action policies, and it can edit a saved policy when you open the agent from that policy's edit page. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). + * To search for saved action policies from a conversation, turn on `agentBuilder:experimentalFeatures` on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). The agent can still create action policies with this setting off. It can also edit a saved policy from that policy's edit page. * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view. * {applies_to}`serverless: experimental` An {{obs-serverless}} project. - Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. An action policy dispatches to a workflow rather than to a connector directly, so notifications usually also need a workflow whose steps use a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). + Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. The policy sends alerts to a workflow. The workflow steps use a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges). **Related skills:** [`rule-authoring`](#agent-builder-rule-authoring-skill) composes the rules whose alerts a policy matches. diff --git a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md index 4ed847893fe..97f4dbabdea 100644 --- a/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md +++ b/explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md @@ -10,7 +10,7 @@ description: "Create Universal Alerting rules and action policies with Agent Bui # Create rules and action policies with {{agent-builder}} [create-rules-agent-builder] -Use {{agent-builder}} to create and configure {{alerting-v2-system}} rules and action policies through natural language instead of the rule form. Describe what you want to monitor, and an agent equipped with the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) resolves the data source and proposes a fully configured rule. +Use an agent with the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) instead of the rule form. The agent resolves the data source and proposes a configured {{alerting-v2-system}} rule. ## Requirements [create-ai-agent-requirements] @@ -19,7 +19,7 @@ Before you start, make sure you have the following: - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons). - {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), select the **Space Settings** tab, and turn on `agentBuilder:experimentalFeatures`. - {applies_to}`stack: experimental =9.5` **To search for and edit existing rules and action policies, the `contextEngine:enabled` advanced setting also turned on** - On the **Space Settings** tab, turn it on in each space where you use the agent. -- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` **To search for existing rules and action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on** - Without it, the agent can still create rules and action policies. It can also edit a saved rule or action policy when you open the agent from that rule's details page or that policy's edit page. To turn it on, refer to [Enable experimental features](/explore-analyze/ai-features/agent-builder/get-started.md#enable-experimental-features-optional). +- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` **To search for existing rules and action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on** - On the **Space Settings** tab, turn it on. Refer to [Enable experimental features](/explore-analyze/ai-features/agent-builder/get-started.md#enable-experimental-features-optional). The agent can still create rules and action policies with this setting off. It can also edit a saved rule from its details page, or a saved action policy from its edit page. - {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces. - {applies_to}`serverless: experimental` **An {{obs-serverless}} project** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other project types. - **The required privileges** - Your role needs the [privileges to use {{agent-builder}} and save rules and action policies](../manage/configure-access.md#alerting-agent-builder-privileges). @@ -36,7 +36,7 @@ To create a rule, go to **Alerting** → **Rules** in the {{observability}} navi Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill configured. -The `rule-authoring` skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the {{alerting-v2-system}} data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal. +The `rule-authoring` skill covers {{esql}} query patterns, thresholds, grouping, and the {{alerting-v2-system}} data model. ### Review the proposal [ai-agent-review-proposal] @@ -69,18 +69,22 @@ The agent proposes the workflows and action policies needed to deliver notificat {applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself. -{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads the [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill, which creates the action policies. +{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads the [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill. That skill creates the action policies. :::{note} Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward: - **Unsaved rule** - The agent changes the draft rule so that it opens alerts. Then you save the rule. -- **Saved rule** - Whether a rule opens alerts can't change after you save it, so the agent offers to create a new rule with the same query and schedule that does, and to set up notifications on that one. +- **Saved rule** - Whether a rule opens alerts can't change after you save it. The agent offers to create a new rule with the same query and schedule that opens alerts, then set up notifications on that rule. ::: - **Workflows** - Workflows are the delivery mechanism. They define what happens when {{alerting-v2-system}} determines that a notification should be sent, such as posting to Slack, emailing a team, triggering PagerDuty, and so on. - **Action Policies** - Action policies are the gating mechanism. {{kib}} evaluates them against the rule's alerts and invokes the workflow for the alerts they apply to. When you create an action policy with a rule, the policy applies to that rule's alerts. - * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` The agent links the policy to the rule with a [routing tag](../action-policies/create-configure-action-policy.md#routing-tags). If the rule already has a routing tag that no other rule uses, the agent can reuse it. Otherwise, the agent adds a `notify-` routing tag to the rule and the policy, in lowercase with hyphens (for example, `notify-high-cpu-prod`). The policy also applies to alerts from any other rule with that routing tag. If the agent adds a routing tag to a rule you already saved, save the rule again so the tag takes effect. + * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` The agent links the policy to the rule with a [routing tag](../action-policies/create-configure-action-policy.md#routing-tags). + * If the rule already has a routing tag that no other rule uses, the agent reuses it. + * Otherwise, the agent adds a `notify-` routing tag to the rule and the policy. The tag is lowercase with hyphens, for example, `notify-high-cpu-prod`. + * The policy also applies to alerts from any other rule with that routing tag. + * If the agent adds a routing tag to a rule you already saved, save the rule again so the tag takes effect. * {applies_to}`stack: removed 9.6+, experimental =9.5` {applies_to}`serverless: unavailable` The action policy references the rule by ID. Both objects are proposed as inline attachments and must be explicitly saved before they take effect. @@ -92,7 +96,7 @@ The three objects depend on each other. Save them in this recommended order: 1. **Rule** - Save the rule first. The link between the rule and the action policy takes effect only after the rule is saved. 2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow. 3. **Action policy** - Save the action policy last. - * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` You can't save the action policy until its workflow exists: {{kib}} disables **Create policy** while a workflow destination is still a draft. You can save the policy before the rule, but the policy doesn't apply to the rule's alerts until the rule is saved. + * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` You can't select **Create policy** while a workflow destination is still a draft. You can save the policy before the rule. The policy doesn't apply to the rule's alerts until the rule is saved. * {applies_to}`stack: experimental =9.5` You can't save the action policy until both its rule and its workflow exist. :::{note} diff --git a/explore-analyze/alerting/esql/setup.md b/explore-analyze/alerting/esql/setup.md index 86576124120..975c1b120e2 100644 --- a/explore-analyze/alerting/esql/setup.md +++ b/explore-analyze/alerting/esql/setup.md @@ -62,7 +62,7 @@ stack: experimental 9.6+ To try features of {{alerting-v2-system}} that are still experimental, turn on the **Universal Alerting: Experimental Features** advanced setting (`alerting:v2:experimentalFeatures`). The setting is off by default and applies only to the space where you turn it on. -When the setting is on, you can detect multi-step alert patterns by chaining rules into a sequence. On the **Rules** page, select **Build a sequence (Experimental)**. +When the setting is on, you can chain rules into a sequence and detect multi-step alert patterns. On the **Rules** page, select **Build a sequence (Experimental)**. To turn on experimental features: @@ -71,7 +71,12 @@ To turn on experimental features: 3. Select the **Space Settings** tab, then turn on **Universal Alerting: Experimental Features**. 4. Select **Save changes**, then reload {{kib}}. -You can create rules and action policies with {{agent-builder}} while this setting is off. On the **Rules** page, select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**. On the **Action Policies** page, select **Create policy** → **Create with agent**. When the Action Policies list is empty, select **Create with AI Agent**. {{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements). +You can create rules and action policies with {{agent-builder}} while this setting is off. + +- On the **Rules** page, select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**. +- On the **Action Policies** page, select **Create policy** → **Create with agent**. When the Action Policies list is empty, select **Create with AI Agent**. + +{{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements). ## Keep the Observability alerts page for {{alerting-v1-system}} [alerting-setup-v1-alerts-page]