> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI assistant detection

> ShieldLabs AI assistant detection recognizes supported assistants visiting your website. Identify the provider and read identity verification results.

## What is ShieldLabs AI assistant detection?

ShieldLabs AI assistant detection recognizes supported assistants retrieving information from your website. It returns the AI Bot detection, the provider when available and optional metadata about the client name and identity verification.

AI assistants use large language models (LLMs) to answer questions, compare information and summarize what they find. To prepare a response, an assistant can request pages from your website. ChatGPT, Claude and Perplexity are examples; the [supported client list](#supported-ai-bots-and-assistants) shows the requests ShieldLabs recognizes.

Use the assistant name, provider and available verification results with the Risk Score to distinguish recognized AI traffic from risky automation. For agents that navigate pages and interact with forms, read [ShieldLabs AI agent detection](https://docs.shieldlabs.ai/features/ai-agents.md).

## How AI assistant detection and verification work

ShieldLabs combines recognized client identity with the network evidence available for the identification. Supported traffic can identify itself by its request headers; provider address information can establish additional attribution.

Recognition and verification answer different questions:

| Result | What it establishes |
| - | - |
| A recognized identity claim | The request presents a known bot or assistant identity |
| Verified provider attribution | Available evidence confirms the provider |
| AI bot detection | ShieldLabs classifies the identification as recognized AI-bot traffic |

A recognized name is not proof that a request came from that provider. Check `client_identity.verified` when your application requires confirmed attribution. For GPTBot and ChatGPT-User, supported verification includes the provider's published IP ranges.

AI assistant detection analyzes activity received through your [ShieldLabs integration](https://docs.shieldlabs.ai/quickstart.md). Make sure the assistant reaches that integration so its request appears in your results.

## Event payload

The following illustrative excerpt shows a recognized ChatGPT-User identification inside a scored webhook's `data` object:

```json theme={null}
{
  "identification_id": "13f84f05-7c2a-4e9b-9f1d-2a6b8c0e4d11",
  "risk_score": 0,
  "signals": [{ "name": "ai_bot", "weight": 0 }],
  "detection_flags": { "ai_bot": true },
  "ai_bot_owner": "OpenAI"
}
```

These are JSON fields inside `data` of an `identification.scored` event. The excerpt omits other fields and false detection flags for readability. Read the result after [verifying the webhook signature](https://docs.shieldlabs.ai/setup/webhooks.md#verify-and-store-the-event):

| Field inside `data` | Type | Meaning |
| - | - | - |
| `detection_flags.ai_bot` | boolean | Recognized AI-bot traffic, including supported assistant fetchers and AI crawlers |
| `ai_bot_owner` | string, optional | Provider of the active AI Bot detection; omitted when the name is unavailable |
| `signals` | array | Includes `ai_bot` with weight 0 when the detection is active |
| `risk_score` | integer | Recognized good-bot traffic scores 0 |
| `client_identity` | object, optional | Identity claims, verified attribution and assessment results |

### Read the assistant name

When available, `client_identity.claims` identifies the recognized profile, its provider, the agent name and its purpose. This shortened example shows the claim for ChatGPT-User:

```json theme={null}
{
  "client_identity": {
    "claims": [{
      "profile_id": "openai-chatgpt-user",
      "provider_id": "openai",
      "provider_name": "OpenAI",
      "agent_name": "ChatGPT-User",
      "client_kind": "fetcher",
      "purpose": "user_fetch",
      "source": "http_ua"
    }]
  }
}
```

`user_fetch` describes retrieval for a user request. `training` describes a content-collection crawler. Search-oriented profiles use `search` and can appear under the [Search bot detection](https://docs.shieldlabs.ai/features/bot-directory.md#search-bots-and-crawlers).

The `claims` list records presented identities. It does not replace the separate `verified` attribution list.

### Interpret identity assessments

`client_identity.assessments` supplies context for recognized claims and verification attempts. Interpret each assessment with its profile and the available attribution:

| `status` | Meaning |
| - | - |
| `verified` | A verification check succeeded within its stated scope |
| `unverified` | A known identity was recognized without that assessment establishing verification |
| `unknown` | The available input did not establish a verification result |
| `conflict` | The identity claims or evidence disagree |

A provider can have verified attribution while a name claim remains unverified. Read the scope in `client_identity.verified`; do not infer a single verification state from one assessment. Missing `client_identity` means this metadata was not supplied.

In a scored webhook, the array is at `data.client_identity.assessments`. A `candidate_profile_id` links an entry to a claim's `profile_id`; an entry without it reports a general assessment. Empty or unavailable assessments do not establish a human visitor or a verified client. See [Identity assessment](https://docs.shieldlabs.ai/glossary-integration.md#identity-assessment) for the field definitions.

## Supported AI bots and assistants

ShieldLabs supports the following AI bots and assistants:

| Name | Provider | Activity |
| - | - | - |
| GPTBot | OpenAI | AI content crawler |
| ChatGPT-User | OpenAI | Retrieval for a user request |
| ClaudeBot | Anthropic | AI content crawler |
| Claude-User | Anthropic | Retrieval for a user request |
| Perplexity-User | Perplexity | Retrieval for a user request |
| MistralAI-User | Mistral AI | Retrieval for a user request |
| DuckAssistBot | DuckDuckGo | Retrieval for AI-assisted answers |

Search-oriented AI crawlers, including OAI-SearchBot, Claude-SearchBot and PerplexityBot, appear in the [bot directory](https://docs.shieldlabs.ai/features/bot-directory.md). The directory separates product detections from the purpose suggested by a crawler's name.

## Using AI assistant detection results

Use the AI bot flag to separate recognized AI traffic from human activity and other automation. Use verified attribution when access depends on a particular provider.

| Result | How to use it |
| - | - |
| `ai_bot: true`, provider supplied | Attribute recognized AI traffic to that provider |
| Verified provider attribution | Apply provider-specific access conditions when appropriate |
| A known name without verification | Keep recognition separate from confirmed identity |
| Conflicting identity evidence | Review the conflict before granting provider-specific access |
| No recognized AI bot | Read the other risk signals and Risk Score for this identification |

The dashboard groups recognized AI bots under **Good bot**. Their Risk Score is always 0. Use identity verification and account context when granting access to protected content or actions.

## View AI traffic in the dashboard

Open [Analytics](https://docs.shieldlabs.ai/dashboard/analytics.md) and inspect an identification's signals. **AI Bot** displays the provider when available; **Good bot** combines AI bots, AI browsers and search bots in aggregate views.

For backend automation, read `ai_bot` and `ai_bot_owner` from the [scored webhook](https://docs.shieldlabs.ai/api/webhook-identification.md). History can include optional `client_identity`, but it does not return those two fields. See [bot results in webhooks and History](https://docs.shieldlabs.ai/features/bot-detection.md#bot-results-in-webhooks-and-history).

## Next steps

> **[AI agent detection](https://docs.shieldlabs.ai/features/ai-agents.md)**
>
> Read browser-platform detection and signed infrastructure attribution.

> **[Bot directory](https://docs.shieldlabs.ai/features/bot-directory.md)**
>
> Browse supported AI bots, browser platforms and crawlers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.