---
title: Event Discovery Agent
description: "Event Discovery Agent reviews your web Autocapture data each week and suggests labeled events for the key interactions in your product, for you to review."
product: data
lang: en
last_updated: 2026-10-20
token_estimate: 4763
---
# Event Discovery Agent

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Event Discovery Agent reviews the web Autocapture data your project already collects, identifies your core product flows, and suggests labeled events for the key interactions in them. It runs weekly and places its suggestions on the Agent-Suggested tab for review. Amplitude adds nothing to your taxonomy until someone accepts a suggestion.

Use Event Discovery Agent when you run web Autocapture and want to find the interactions worth tracking without defining each event by hand. Use [Visual Labeling](https://amplitude.com/docs/data/visual-labeling) when you want to interactively select and name specific elements on your site yourself.

Event Discovery Agent is in Beta. If you have any questions, contact [Amplitude Support](https://gethelp.amplitude.com/hc/en-us). Contact your Amplitude representative to request access.

## How Event Discovery Agent works

Each run, Event Discovery Agent reads the Autocapture events in your project, such as `Page Viewed`, `Element Clicked`, and `Element Changed`. From those events, it identifies the sequences of interactions that make up your core product flows. For each interaction worth tracking, it drafts a labeled event: a name, a description, a category, and a definition that matches the element on your site. It then checks how reliable that definition is likely to be and how much the event matters to your analysis.

Suggestions don't add to your event volume. A labeled event is a definition layered on top of Autocapture data you already collect, so accepting a suggestion labels existing events instead of sending new ones. For more on how labeled events relate to volume, go to [Labeled events and event volume](https://amplitude.com/docs/data/visual-labeling#labeled-events-and-event-volume).

### Run schedule

During the beta, Event Discovery Agent runs once a week. A run usually takes 1 to 2 hours. The agent creates suggestions only when it finds interactions worth tracking, so a run can finish with no new suggestions.

### How the agent avoids duplicates

Before it suggests an event, Event Discovery Agent checks for overlap with:

- Events already in your taxonomy, including instrumented events, custom events, and labeled events.
- Suggestions that are still open on the Agent-Suggested tab.
- Suggestions someone dismissed.

The agent doesn't edit or delete existing events. If the agent finds more evidence for an interaction it suggested before, it can suggest a similar event in a later run, even if someone dismissed the earlier suggestion.

## Requirements

Event Discovery Agent works with web Autocapture data from the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). It reads page views and element interactions (`Element Clicked` and `Element Changed`). You can turn on element interactions and other Autocapture event types with [remote configuration](https://amplitude.com/docs/data/autocapture-remote-configuration). For the events the agent reads, go to [Web Autocapture Schema](https://amplitude.com/docs/data/web-autocapture-schema). The agent works best when your project has at least 10,000 web Autocapture events in the last 30 days.

To check your current Autocapture volume, use either method:

- In Amplitude Data, go to _Events_ and check the _30 Day Volume_ column for web Autocapture events such as `Page Viewed` and `Element Clicked`.
- Build an [Event Segmentation chart](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) that measures event totals for the web Autocapture events over the last 30 days.

## Permissions

What a user can do with Event Discovery Agent depends on their role in the project.

| Action | Who can do it |
| --- | --- |
| View the Event Discovery Agent settings page and the Agent-Suggested tab | Everyone with access to the project |
| Turn the agent on or off, change its settings, add context, and cancel or retry runs | Admins and managers |
| Edit, accept, dismiss, and restore suggestions | Admins and managers |
| Use open suggestions in event dropdowns across Amplitude, for example to test them in charts | Admins and managers always. Members and viewers only when an admin or manager turns on _Show suggestions in event dropdowns before they are accepted_. |

Open suggestions appear in event dropdowns only while Event Discovery Agent is on. When the agent is off, suggestions remain on the Agent-Suggested tab but don't appear in dropdowns for anyone.

## Turn on Event Discovery Agent

Event Discovery Agent runs per project. To turn it on for a project:

1. In Amplitude Data, go to _Event Discovery Agent_.
2. Turn on **Enable Event Discovery Agent**.
3. Review the confirmation, then click **Enable and start a run**.

The first run starts immediately and usually takes 1 to 2 hours. After that, the agent runs weekly. If a run is already in progress, or a run finished successfully in the last 12 hours, turning on the agent doesn't start another run. The next run starts on the weekly schedule.

To turn the agent on for another project, switch to that project and repeat these steps.

When you turn off **Enable Event Discovery Agent**, Amplitude stops any run in progress and cancels future runs. It also turns off **Show suggestions in event dropdowns before they are accepted**. Suggestions you already received stay on the Agent-Suggested tab.

### Control who sees suggestions outside Amplitude Data

The **Show suggestions in event dropdowns before they are accepted** setting controls whether open suggestions appear in event dropdowns across Amplitude, marked as agent-suggested.

- **On**: All users can find and use open suggestions in event dropdowns.
- **Off**: Members and viewers see suggestions only on the Agent-Suggested tab. Admins and managers can always use suggestions in event dropdowns to test them before wider rollout.

You can change this setting only while Event Discovery Agent is on.

## Give the agent context about your product

Context is optional, but it helps the agent name events the way your team does and focus on the parts of your product that matter. Add or change context at any time. Saved context applies to future runs, not runs already in progress.

Event Discovery Agent reads context from these sources:

- **Context instructions**: Free text you enter on the Event Discovery Agent settings page, up to 10,000 characters. Amplitude recommends 1,000 to 3,000 characters.
- **Context files**: Files you upload, such as data dictionaries, naming guides, or product specs. Supported formats are TXT, MD, HTML, DOC, DOCX, PDF, CSV, XLS, and XLSX, up to 25 MB per file.
- **AI Controls context**: The organization and project context set in [AI Controls](https://amplitude.com/docs/amplitude-ai/ai-controls#ai-context).

Context instructions and files are project-scoped. Other Amplitude AI agents in the project can use them too. Amplitude can also use uploaded files to add descriptions and context to your existing events and properties. To manage uploaded files, go to [AI Controls](https://amplitude.com/docs/amplitude-ai/ai-controls#file-uploads).

### Naming conventions

To name suggested events, the agent uses the first of these sources that states a naming convention:

1. Your Event Discovery Agent context instructions and context files.
2. The naming convention in your [Amplitude Data settings](https://amplitude.com/docs/data/amplitude-data-settings#naming-conventions).
3. Your AI Controls context files, then project context, then organization context.
4. The convention most of your existing events already follow.
5. A product area followed by the object and a past-tense action, in Title Case, for example `Projects | Project Created`.

### What to include in context instructions

Short, specific instructions work best. Useful topics include:

| Topic | Example |
| --- | --- |
| Naming conventions | Use Title Case with Object + Action, such as `Project Created` or `Plan Upgraded`. |
| Product terms | "Workspace" means a customer account. "Boards" are our dashboards. |
| Core flows | Sign up, onboarding checklist, create a project, invite teammates. |
| Level of detail | Track `Item Viewed` with the item type as a property, not a separate event per item such as `Shoes Viewed`. |
| Areas to ignore | Legacy admin pages with "Classic" in the page title. |
| Tracking preferences | When an element has both `data-track-id` and `data-testid`, use `data-track-id`. Don't use style classes in event definitions. |

To add context instructions:

1. In Amplitude Data, go to _Event Discovery Agent_.
2. On the _What should Event Discovery Agent know about your product and taxonomy?_ card, click **Edit**.
3. Enter your instructions in Markdown, or click **Upload markdown file**.
4. Click **Save**.

To add context files:

1. On the _Upload context files_ card, click **Upload file**.
2. Choose a file, then click **Upload**.

## Monitor runs

The _Recent runs_ table on the Event Discovery Agent settings page lists runs from the last 30 days and the next scheduled run time. Each run shows one of these statuses:

| Status | Meaning |
| --- | --- |
| Pending | The run is queued to start. |
| Running | The agent is reviewing your data. Suggestions appear after every step of the run finishes. |
| Completed | The run finished. The row shows how many suggestions it created. |
| Failed | The run stopped before it finished. Click **Retry run** to start it again. |
| Cancelled | Someone stopped the run before it finished. |

Click a run to view its progress through each step and download its reports.

To stop a pending or running run, click **Cancel run** on its row, then confirm. Amplitude keeps the steps the run already completed and their saved reports.

### Run reports

Each completed run produces reports you can download from the run's details. The reports explain what the agent found and why. Use them to review suggestions in bulk or to share the suggested events with your engineering team.

| Report | What it contains |
| --- | --- |
| Tracking Plan Export Bundle | A ZIP file of every report and data export from the run. |
| Taxonomy report | An HTML summary of the run: what it found, the user journeys the suggested events measure, the suggested events, and interactions the agent chose not to suggest, with the reason for each. |
| Implementation guide | A guide for engineers: the exact definition behind each suggested event, how reliable its selector is, the volume the agent measured, how to confirm the event fires on the element you expect, and where adding a fixed identifier to your code would make tracking more reliable. |
| Taxonomy events CSV | One row per suggested event with its name, source Autocapture event, and definition. |
| Taxonomy events JSON | The same event definitions in JSON. |
| Tracking plan | The questions the run worked from, the measured flows, the context the run read, and a full specification for each suggested event, including category, selector, durability, and analytical value. |

You can preview some reports in Amplitude before you download them.

## Get notified about new suggestions

Amplitude doesn't send notifications about Event Discovery Agent by default. To get an email or Slack message when new suggestions are available to review, opt in:

1. Go to _Settings > Notifications_.
2. Under _Updates about my data_, find _New Event Discovery Agent suggestions are available for review_.
3. Select **Email**, **Slack**, or both.

## Review suggestions

Each suggestion includes a description, a category, a definition, an analytical value rating, and a verdict on how reliable its definition is likely to be. Review each suggestion, edit it if needed, then accept the ones you want in your taxonomy and dismiss the rest.

### Find suggestions

1. In Amplitude Data, go to _Events_.
2. Click the **Agent-Suggested** tab.

The _Open_ view lists suggestions waiting for review. The _Dismissed_ view lists suggestions someone dismissed. A sparkle icon next to each name marks the event as agent-suggested.

For each suggestion, the table shows its name, category, analytical value, whether it's safe to accept, its occurrences in the selected date range, and when the agent created it. The list sorts by analytical value, highest first. To export open suggestions as a CSV file, click **Download**.

### Review a suggestion

Click a suggestion to open its details panel. The panel includes:

- **Analytical value**: The rating and why the agent assigned it.
- **Verdict note**: Whether the suggestion is safe to accept and why.
- **Description**: What triggers the event, the user journey it belongs to, and how you might use it in analysis.
- **Category**: An existing category from your taxonomy that fits, or a new one the agent proposes.
- **Occurrences**: How often the event occurred in the last 30 days.
- **Screenshot / GIF**: A visual of the interaction, when available.
- **Definition**: The Autocapture event and the element selector the labeled event matches.

Use the agent's evidence and verdict as a starting point. Then confirm that the description and definition accurately capture the interaction you want.

To build a screenshot or GIF, the agent loads the public page where the event occurs and highlights the control. If that doesn't work, for example because the page requires a login, it uses a frame from a [Session Replay](https://amplitude.com/docs/session-replay) recording, labeled _Inferred event match_. Some suggestions have no visual. Visuals are approximate representations of the event, so check the definition to confirm it tracks what you want.

#### Analytical value

Analytical value is the agent's estimate of how much an interaction is likely to matter for your analysis, based on how central it is to your core product flows.

| Rating | Meaning |
| --- | --- |
| High | The interaction is critical to a core user flow, such as activation, onboarding, or a primary conversion path. Tracking it is likely to have a significant impact on your analysis. |
| Medium | The interaction is part of an important but secondary flow. It may support product discovery, engagement, or feature adoption, and is worth tracking for comprehensive analysis. |
| Low | The interaction occurs in a supporting or peripheral flow. It may be useful for edge case analysis but is less likely to affect core metrics. |

#### Safe to accept

Each suggestion's definition relies on identifiers your site exposes, such as attributes, IDs, or classes on an element. Some identifiers are more stable than others. The _Safe to Accept?_ column shows how well the definition matches the event it names and how likely it is to keep working as your site changes.

The agent checks two things:

- **Durability**: Whether the identifier is likely to survive changes to your site.
- **Accuracy**: Whether the definition counts only the control the event name describes.

| Verdict | Meaning |
| --- | --- |
| Yes | The definition passes both checks. It's unlikely to break or lose data after you accept the suggestion. |
| Worth a check | The definition fails at least one check. It may stop matching after a site change, or it may count more than the control its name describes. Review the definition before you accept the suggestion. |

In the details panel, the verdict appears as _Safe to accept_ or _Check before accepting_, with a note that explains the reason in plain language. When the agent flags a suggestion, the note also suggests a fix, such as asking your engineering team to add a fixed identifier to the control.

A definition is more durable when it uses an identifier that's specific to the element and unlikely to change:

| More durable | Less durable |
| --- | --- |
| Attributes your team adds for testing or tracking, such as `data-testid` or `data-track`. | Identifiers the element shares with other elements, such as a class used on several buttons. |
| Stable `id` attributes on the element. | Style classes and build-generated class names or IDs, which can change on the next deploy or redesign. |
| A link destination (`href`) or a specific page route. | Visible text, labels such as `aria-label`, and values that contain prices or counts. |

Accuracy issues usually mean the definition is broader than the name. For example, the name calls the control a button, but the agent recorded the click on a container around it.

A _Yes_ verdict reflects your site at the time the agent reviewed it. The verdict can't guarantee long-term reliability, because changes to your site's code can still affect the definition. If an accepted event stops collecting data, go to [Repair a labeled event](https://amplitude.com/docs/data/visual-labeling#repair-a-labeled-event).

### Edit and test a suggestion

Before you accept a suggestion, you can update its name, description, category, and definition directly in the details panel.

To check the data before you accept a suggestion, click **Create Chart** in the details panel. Amplitude opens a chart with the suggested event so you can confirm the volume and trend match what you expect. Volume far above or below what you expect can mean the definition matches a different element.

Admins and managers can always chart a suggestion before it's accepted. Other users can chart it only when the **Show suggestions in event dropdowns before they are accepted** setting is on.

### Accept or dismiss a suggestion

- **Accept**: Click **Accept** in the details panel. Amplitude adds the event to your _Labeled Events_ tab and no longer marks it as agent-suggested.
- **Dismiss**: Click **Dismiss**. The suggestion moves to the _Dismissed_ view.

To restore a dismissed suggestion, open it from the _Dismissed_ view, click **Restore**, and confirm. The suggestion returns to the _Open_ view for review.

The agent checks dismissed suggestions so it doesn't suggest the same event again right away. If a later run finds more evidence for the interaction, the agent can suggest a similar event.

To work through a long list, click **Add Filter** to narrow the _Open_ view by category, 30 Day Occurrences, 30 Day Queries, Analytical Value, Safe to Accept?, or Created Date. For example, filter to High analytical value and _Yes_ to review the most valuable, most reliable suggestions first. To dismiss several suggestions at once, select them in the list, then click **Dismiss**.

## Share feedback

Amplitude's product team reads all feedback to shape Event Discovery Agent.

- **Rate a suggestion**: In the suggestion's details panel, click the thumbs icon and choose **Good suggestion**, **Neutral suggestion**, or **Not a good suggestion**. Add a comment, then click **Submit feedback**.
- **Share overall feedback**: On the Agent-Suggested tab, click **Give feedback** and answer the short survey about what's working and what isn't.