AI agent identification

Castle identifies supported AI agents and browser automation separately from risk scoring. When an agent is identified, your API response includes an optional top-level agent object.

{
  "agent": {
    "name": "ChatGPT agent",
    "operator": "openai",
    "category": "ai_agent",
    "identified_by": ["web_bot_auth"]
  }
}

Response fields

Field	Description
`name`	The agent's display name.
`operator`	The operator's identifier, such as `openai`.
`category`	`ai_agent`, `browser_automation`, or `ai_browser`.
`identified_by`	Matching methods: `web_bot_auth`, `fingerprint`, or `user_agent`. Multiple methods can match the same agent.

If Castle cannot identify an agent, the response omits agent. An omitted object does not establish that the request came from a human.

Identification methods

web_bot_auth: Castle successfully verified a Web Bot Auth signature for a supported signer.
fingerprint: Browser fingerprint evidence matched a supported agent.
user_agent: A recognized user-agent string identified the agent. User-agent strings can be spoofed and do not verify the operator's identity.

Verified signatures take precedence over fingerprint matches, which take precedence over user-agent matches. Agent identity is separate from signals. Identification does not change bot or abuse scores or existing enforcement decisions. A verified signature confirms the signer; it does not establish that the request is safe or prevent replay.

Forward headers for signature verification

Include these incoming request headers in context.headers when sending the event to Castle:

Header	What to forward
`Signature-Input`	The incoming signature parameters.
`Signature`	The incoming signature value.
`Signature-Agent`	The incoming signer identity.
`Host`	The original host requested by the agent, not your backend service's host or Castle's API host.

If your integration selects which headers to forward, ensure that it includes these headers. Missing headers can prevent signature verification. Castle may still identify the agent through another supported method.

See Bot detection for more information about bot scores.