From 80a9a80e4c29d6d40ec85a39f7c89904d7a8f7d8 Mon Sep 17 00:00:00 2001 From: Ian Streeter Date: Wed, 10 Jun 2026 10:50:58 +0100 Subject: [PATCH] Agent classification enrichment --- .../agent-classification-enrichment/index.md | 126 ++++++++++++++++++ .../available-enrichments/index.md | 1 + 2 files changed, 127 insertions(+) create mode 100644 docs/pipeline/enrichments/available-enrichments/agent-classification-enrichment/index.md diff --git a/docs/pipeline/enrichments/available-enrichments/agent-classification-enrichment/index.md b/docs/pipeline/enrichments/available-enrichments/agent-classification-enrichment/index.md new file mode 100644 index 000000000..31706f95a --- /dev/null +++ b/docs/pipeline/enrichments/available-enrichments/agent-classification-enrichment/index.md @@ -0,0 +1,126 @@ +--- +title: "Agent classification enrichment" +sidebar_position: 9.5 +sidebar_label: Agent classification +description: "Identify AI crawlers and automated agents by classifying them by operator and purpose." +keywords: ["agent classification", "AI crawler", "bot classification", "YAUAA"] +date: "2026-06-10" +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import SchemaProperties from "@site/docs/reusable/schema-properties/_index.md" + +:::note[Availability] +This enrichment is available since version 6.12.0 of Enrich. +::: + +The agent classification enrichment identifies automated agents — AI crawlers, bots, and other non-human clients — by matching the agent name parsed by the [YAUAA enrichment](/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md) against a lookup of known agents. For each match, it adds an [entity](/docs/fundamentals/entities/index.md) to the event identifying the operator (e.g. `OpenAI`) and, where known, the agent's purpose (e.g. `AI crawler`). + +## Prerequisites + +To use this enrichment, you need to enable the [YAUAA enrichment](/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md). The agent classification enrichment reads the `agentName` field from the YAUAA entity. If YAUAA is not active, no agent classification entity is attached. + +## Configuration + +The enrichment takes these parameters: + +| Parameter | Required | Description | +| --- | --- | --- | +| `classificationFile` | ❌ | Location of a JSON file mapping YAUAA agent names to classification records. Already provided for CDI customers. | +| `classification` | ❌ | Inline classification records, keyed by YAUAA agent name. Takes precedence over matching entries in `classificationFile`. | + +At least one of `classificationFile` or `classification` must be present. + + + + +Configure the parameters in the Console enrichment editor. Keep the Console defaults for the `database` and `uri` fields. For example: + +```json +{ + "classificationFile": { + "uri": "", + "database": "" + }, + "classification": { + "MyInternalBot": {"operator": "Acme Corp", "purpose": "Monitoring"} + } +} +``` + + + + +For Self-Hosted, [provide a complete JSON](/docs/pipeline/enrichments/managing-enrichments/terraform/index.md). For example: + +```json +{ + "schema": "iglu:com.snowplowanalytics.snowplow.enrichments/agent_classification_enrichment_config/jsonschema/1-0-0", + "data": { + "name": "agent_classification_enrichment_config", + "vendor": "com.snowplowanalytics.snowplow.enrichments", + "enabled": true, + "parameters": { + "classificationFile": { + "uri": "", + "database": "agent-classifications.json" + }, + "classification": { + "MyInternalBot": {"operator": "Acme Corp", "purpose": "Monitoring"} + } + } + } +} +``` + + + + +```mdx-code-block +import TestingWithMicro from "@site/docs/reusable/test-enrichment-with-micro/_index.md" + + +``` + +### `classificationFile` + +:::tip[Snowplow CDI] +If you're using Snowplow CDI, you don't need to configure this. Use the default values provided in Console. +::: + +Points to a JSON file containing the agent-to-classification mapping. The file must be a JSON object where the keys are YAUAA `agentName` values and the values are objects with `operator` (required) and `purpose` (optional). For example: + +```json +{ + "ChatGPT-User": {"operator": "OpenAI", "purpose": "AI data retrieval"}, + "GPTBot": {"operator": "OpenAI", "purpose": "AI crawler"}, + "ClaudeBot": {"operator": "Anthropic"} +} +``` + +| Field | Type | Description | +| --- | --- | --- | +| `uri` | string | Base URI where the file is hosted. Supports `http:`, `s3:`, and `gs:` schemes. Must not end with a trailing slash. | +| `database` | string | The JSON filename. | + +### `classification` + +An inline map of agent names to classification records, keyed by YAUAA `agentName`. Each record must include `operator` (the vendor operating the agent) and optionally `purpose` (the agent's purpose, if known). Records defined here take precedence over any matching entry in `classificationFile`. + +## Output + +This enrichment adds an `agent_classification` entity to events where the YAUAA `agentName` matches a known agent. + +This enrichment won't produce any output if: +* The YAUAA enrichment is not enabled +* The YAUAA entity does not contain an `agentName` field +* The `agentName` is not found in the classification lookup + + diff --git a/docs/pipeline/enrichments/available-enrichments/index.md b/docs/pipeline/enrichments/available-enrichments/index.md index bd6f0411b..7ae6ffaed 100644 --- a/docs/pipeline/enrichments/available-enrichments/index.md +++ b/docs/pipeline/enrichments/available-enrichments/index.md @@ -30,6 +30,7 @@ You can only configure one instance of each enrichment. | [Cookie Extractor](/docs/pipeline/enrichments/available-enrichments/cookie-extractor-enrichment/index.md) | Extract values of specific cookies into extra entities. | | [HTTP Header Extractor](/docs/pipeline/enrichments/available-enrichments/http-header-extractor-enrichment/index.md) | Extract values of specific HTTP headers into extra entities. | | [YAUAA](/docs/pipeline/enrichments/available-enrichments/yauaa-enrichment/index.md) | Parse the user agent string and attach an entity with detailed user agent information. | +| [Agent Classification](/docs/pipeline/enrichments/available-enrichments/agent-classification-enrichment/index.md) | Identify AI crawlers and automated agents by classifying them by operator and purpose using the YAUAA agent name. | | [IP Lookup](/docs/pipeline/enrichments/available-enrichments/ip-lookup-enrichment/index.md) | Look up useful data on the IP address in the MaxMind database. | | [ASN Lookup](/docs/pipeline/enrichments/available-enrichments/asn-lookup-enrichment/index.md) | Flag bot traffic by checking ASNs against known bad ASN lists. | | [Bot Detection](/docs/pipeline/enrichments/available-enrichments/bot-detection-enrichment/index.md) | Consolidate bot signals from YAUAA, IAB, and ASN lookup into a single entity. |