Event Definition Tuning Advisor Agent Workflow

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

• You have a valid Graylog Security license.

• You have configured an LLM provider and model for AI Agent Workflows.

• You have the appropriate role to view and configure Graylog Agents.

• You have one or more enabled event definitions that are generating events. See Create Event Definitions.

• You have events flagged as False Positive so the agent has data to review.

• You have permission to edit event definitions if you plan to apply the agent's suggestions. See Manage Event Definitions.

How the Event Definition Tuning Workflow Works

The Event Definition Tuning Advisor helps reduce false positives. It reviews events flagged as False Positive and recommends changes to the event definitions that produced them.

The agent is powered by the large language model (LLM) provider and model configured for AI Agent Workflows. The LLM does the reasoning; it finds what the flagged events have in common and decides what change would reduce the noise. Deciding why an event definition is noisy is a judgment call rather than a fixed calculation, which is where an LLM helps. Because LLM output is not deterministic, two runs over the same data can produce different suggestions.

The agent calls Graylog tools directly inside Graylog, not through the MCP server, so it does not spend tokens discovering which tools are available on each run. It runs under its own built-in service account with only the permissions it needs. To analyze the activity, it sends its instructions and the data it retrieves, such as events and log messages, to your LLM provider. No other Graylog data leaves your environment.

The agent fits into the event workflow as follows:

1. Define the detection: An event definition sets the condition that triggers an event, such as a filter & aggregation search, an event correlation sequence, or a Sigma rule event. This condition is what the agent later suggests changes to. See Event Definitions.

2. Graylog generates events: Each time the condition is met, Graylog creates an event and lists it on the Alerts & Events page. If the event definition has a notification attached, the event is also an alert. See Alerts.

3. Analysts flag false positives: Analysts review each event. When an event is not a real issue, they change its event status to False Positive, for example from New. The agent analyzes events marked as False Positive, within the limits set in its configuration. 

4. The agent analyzes the false positives: The agent identifies the event definitions that are good tuning candidates, reviews why their flagged events triggered, and posts a tuning suggestion on each one. The audit log records every change the agent makes under the workflow's built-in service account. See What the Agent Does During a Run.

5. Tune the event definition: The agent does not change event definitions on its own. Review its suggestion on the event definition, then apply it or dismiss it. To make a different change, edit the event definition yourself, for example by refining its search query, adding a search filter, or filtering it with a dynamic list. See Apply a Tuning Suggestion.

After an event definition is updated, the cycle starts again. The updated definition generates new events, and the agent reviews any new false positives on its next run.

Hint: The agent works from flagged events, so the quality of its suggestions depends on how consistently events are flagged as False Positive.

What the Agent Does During a Run

Each time the agent runs, it follows the same sequence of steps. Knowing these steps helps you understand why the agent made suggestions for some event definitions and not others, and how to read the numbers in its report.

Step 1: Measure Event Volume and False Positives

The agent counts how many events each event definition produced in the last 24 hours, and how many of each definition's events were closed as false positives during the lookback period configured for the workflow. It then calculates a false positive ratio for each definition: the number of false positives in the lookback period divided by the number of events in the last 24 hours. Because false positives are counted over the whole lookback period but events only over the last 24 hours, the ratio can be higher than 100%. A definition with no events in the last 24 hours has a ratio of 0.

Step 2: Identify Tuning Candidates

An event definition is a tuning candidate when it meets both the minimum number of false positives and the minimum false positive percentage configured for the workflow. The agent ranks the candidates by their event volume in the last 24 hours and keeps the highest-volume ones, up to the maximum number of candidates. The following settings control which event definitions become candidates:

Setting	What it controls
Lookback Days	The number of days of false positives the agent counts for each event definition. The default is 7.
Maximum Candidates	The maximum number of event definitions the agent examines and makes suggestions for in each run. The default is 5.
Minimum False Positives	The minimum number of false positives an event definition must have in the lookback period to be a candidate. The default is 10.
Minimum False-Positive Percentage	The minimum false positive ratio, as a percentage, an event definition must reach to be a candidate. The default is 20.

Step 3: Examine Each Candidate

For each candidate, the agent:

1. Reads which of the event definition's settings can be changed and whether the definition supports search filters. If it needs more detail, it also reads the full configuration, including the filter query, the fields the definition groups by, search window, execution interval, threshold conditions, source streams, priority, and event procedure.

2. Reviews the individual events that were closed as false positives, including their field values and messages, and looks for a pattern they share, such as a scanner's source IP address, a service account, or a specific host name.

3. Compares those false positives with the definition's events that were not flagged as false positives, so it can tell when the definition fires correctly and when it does not.

4. Replays an event's search to retrieve the log messages around it when the event's field values alone do not explain why it triggered.

Hint: The agent suggests excluding a value only when it observed that value in the false positive events or their log messages. It does not infer exclusions from event counts alone.

Step 4: Build Concrete Suggestions

The agent makes each suggestion specific and references the current setting it would change, for example "raise the count threshold from 3 to 5" instead of "review the filter." A suggestion can be one of the following:

Suggestion	Example
Exclude a value	Add a search filter that excludes a scanner's source IP address or a service account observed in the false positives. Suggested only for event definitions that support search filters.
Change the condition	Raise the count threshold from 3 to 5, or adjust the search window or how often the definition runs.
Narrow the source streams	Search only the stream that produces real detections instead of three streams.
Improve the event summary template	Use a more descriptive Event Summary Template when the current event title does not give an analyst enough detail.
Add or improve the description	Add an event definition description when it is missing or inaccurate.

Step 5: Post Suggestions and Report the Results

The agent posts its suggestions on each candidate event definition. It completes this step on every run, even when no event definition is a candidate. It then reports a status, a one-sentence summary of the outcome, and a detailed report, which you can view on the Runs tab of Enterprise > AI Agent Workflows. The Runs tab lists each run with when it ran, its state and outcome, its summary, the provider, how the run was triggered, the account that ran it, its duration, and its token usage. Click a run to see a full walkthrough of it: which event definitions the agent found, why it selected them, and how it built its suggestions.

Run status	When the agent reports it
All good	No event definition met the candidate thresholds. Event volume and false positive ratios are acceptable.
Heads up	At least one event definition is a tuning candidate, and the agent posted suggestions for it.

For each candidate, the detailed report lists the event definition, its event volume in the last 24 hours, its false positives in the lookback period, its false positive ratio, and the suggested change. Event definitions in the report are links that open the event definition in Graylog.

Configure and Enable the Event Definition Tuning Advisor Workflow

You manage Graylog Agents on the AI Agent Workflows page, under Enterprise > AI Agent Workflows. The page has three tabs:

• Workflows: Lists each available workflow with its title, description, and status (Enabled or Disabled). Use this tab to enable or disable a workflow, or click its title to open its page.

• Runs: Lists each workflow run. Click a run to view its report. See Post Suggestions and Report the Results.

• Usage: Shows the LLM token usage of your workflows.

The LLM provider and model that every workflow uses are set on the Model Provider page. To setup your LLM provider and model, see Configure LLM Provider for Graylog Agents.htm. If no provider is configured, Graylog directs you to the Model Provider page when you try to enable a workflow.

To configure and enable the Event Definition Tuning Advisor workflow:

1. Navigate to Enterprise > AI Agent Workflows.

2. On the Workflows tab, click Event Definition Tuning Advisor.

3. Expand the Runtime Permissions section and review the roles and stream access assigned to the agent's built-in service account. Each workflow runs under its own built-in service account that has only the permissions that workflow needs, and that account is what appears in the audit log. Because the agent can only review events, and replay the searches behind them, for streams its built-in service account can access, make sure that account can access the streams your event definitions search. See Graylog Agentic Framework to learn how agent permissions work.

4. Optionally, expand the Prompt section to see the instructions and information the agent sends to the LLM. This section shows the agent's task prompt. Graylog also sends a short system prompt with safety guardrails, such as protections against log injection, that is not displayed. The prompt can change in future releases.

5. Click Edit Configuration.

6. In the Edit Event Definition Tuning Advisor dialog, set Lookback Days, Maximum Candidates, Minimum False Positives, and Minimum False-Positive Percentage. See What the Agent Does During a Run for what each setting controls. Lower thresholds and more candidates increase coverage but also increase the processing time and LLM token usage of each run. You can track token usage in the Token Usage section of the workflow's page and on the Usage tab.

7. Click Update workflow.

8. To enable the workflow, click Disabled next to Status on the workflow's page, or in the Status column on the Workflows tab. The status changes to Enabled.

To stop the workflow, click Enabled. The status changes to Disabled.

Run the Workflow Manually

To run the Event Definition Tuning Advisor workflow on demand, in addition to its automatic runs:

1. Navigate to Enterprise > AI Agent Workflows.

2. On the Workflows tab, click Event Definition Tuning Advisor.

3. Click the Run Workflow button. The agent begins reviewing flagged events immediately instead of waiting for its next automatic run. This is useful after your team finishes triaging a batch of noisy alerts.

4. To see the outcome, return to Enterprise > AI Agent Workflows and select the Runs tab.

Review Tuning Suggestions

When the Event Definition Tuning Advisor finds a tuning candidate, it posts its suggestion where you already work with event definitions, so you do not need to open the AI Agent Workflows page to act on it. The Runs tab is mainly for administrators who want to see what the agent did behind the scenes. Each suggestion references the current setting it would change, so you can judge whether it addresses the real cause of the noise. To see how the agent arrived at a suggestion, open the run's report (see Post Suggestions and Report the Results).

To review the agent's suggestions:

1. Navigate to Alerts > Event Definitions.

2. Locate the tuning suggestions for an event definition the agent reviewed. Tuning suggestions appear on the Event Definitions page.

3. Review the suggestion. It names the candidate event definition and the change the agent recommends, such as excluding a value observed in the false positives, changing a threshold or stream, or improving the event summary template or description.

To see the flagged events behind a suggestion, open the Alerts & Events page and filter by Event Definition and Status. From an event's more actions menu, select Replay Search to review the messages that triggered it. See Alerts and Manage Event Definitions.

Apply a Tuning Suggestion

The agent does not change an event definition on its own. To act on a suggestion:

1. Open the event definition's tuning suggestions, as described in Review Tuning Suggestions.

2. Click Apply to apply the suggested change to the event definition right away, without re-entering it in the event definition wizard, or click Dismiss to reject it.

To make a different change from the one the agent suggested, update the event definition yourself:

1. Navigate to Alerts > Event Definitions.

2. Locate the event definition, then select More > Edit to open the event definition wizard.

3. Make your change. Depending on what you want to change, this might involve:

   • Refining the search query or aggregation on the Condition step. See Event Definitions for how conditions work.

   • Excluding a noisy value, such as a known internal IP address or service account, by adding a search filter. See Search Filters.

   • Maintaining an exclusion list that changes over time by filtering a Filter & Aggregation event definition with a dynamic list, such as a lookup table. See Filter Event Definitions with Dynamic Lists.

4. On the Summary step, review your changes and select Update event definition.

After you apply a suggestion or update the event definition, continue closing any remaining false positives. Each run recalculates its numbers from the last 24 hours and the configured lookback period, so false positives closed before your change continue to count until they fall outside the lookback period.

Hint: Illuminate-provided event definitions are mostly read-only. You can add search filters and notifications to them, but you cannot change their search query or other settings. Search filters you add are preserved through future Illuminate updates. If a suggestion for an Illuminate event definition calls for a different change, consider whether a search filter can achieve the same result. See Manage Event Definitions.

Troubleshooting and Common Issues

The following section outlines troubleshooting steps for common issues to assist you in resolving potential challenges you may encounter.

Further Reading

Explore the following additional resources and recommended readings to expand your knowledge on related topics:

• Event Definitions

• Create Event Definitions

• Manage Event Definitions

• Filter Event Definitions with Dynamic Lists

• Search Filters

• Alerts

• Security Events

• Asset Risk Review Agent Workflow

• Graylog Agents

• Graylog Agentic Framework