IsAgent

Documentation

Complete SDK reference and usage guide for the IsAgent SDK. Learn how to detect and handle AI agents in your React applications.

# Overview

The IsAgent SDK enables you to detect whether a client is likely an AI agent or a human user using an agent detection API from Stytch on the frontend. It provides the core JavaScript function isAgent, as well as high-level React hooks/components for seamless integration into your application.

# Quick Start

0. Prerequisites

You'll need to sign up for a free Stytch account if you don't already have one.


  1. Visit the Stytch Dashboard and sign up to create a free account.
  2. Create a new Workspace by clicking "Create Workspace" and entering your details.
  3. Select B2B SaaS as your project type and click "Create account".

Once you've created your account, scroll down to the Project ID & API keys section and copy the public_token.

1. Install the SDK

2. Initialize the context

Set up the agent detection context with your Stytch public_token, get your token here:

3. Use the components

Render different content for agents vs humans:

4. Or use the hook directly

For custom behavior and state management:

# SDK Reference

createAgentContext(publicToken: string)

Initializes the agent-detection context.

Parameters:

  • publicToken — Your Stytch public token.

Returns:

An object with:

  • useIsAgent — React hook for agent detection.
  • IsAgent — Component rendering children only for detected agents.
  • IsHuman — Component rendering children only for detected humans.
<IsAgent> Component

Renders children only when isAgentClientHint is true.

Props:

  • loadingComponent?: React.ReactNode — Shown during loading.
  • errorComponent?: React.ReactNode | ((props: { error: Error }) => React.ReactNode) — Shown on error.
  • children: React.ReactNode — Content for agents.
<IsHuman> Component

Renders children only when isAgentClientHint is false.

Props:

  • loadingComponent?: React.ReactNode — Shown during loading.
  • errorComponent?: React.ReactNode | ((props: { error: Error }) => React.ReactNode) — Shown on error.
  • children: React.ReactNode — Content for humans.
useIsAgent(): AgentState

React hook providing detection state.

Returns:

An object:

  • loading: boolean — Detection in progress.
  • error: Error | null — Any error encountered.
  • isAgentClientHint: boolean | null — true if client likely an agent.
  • identity: string | null — Detected identity if available.

# Helpers

From isAgent.ts:

IsAgentError

Error thrown when the API call fails, containing details:

  • status_code
  • error_type
  • error_message
  • error_url
  • request_id (optional)
  • error_details (optional)
isAgent(publicToken: string)

Low-level function that checks agent status via Stytch API. Returns a promise resolving to detection result.

Returns:

Promise resolving to:

  • is_agent_client_hint: boolean — true if client likely an agent
  • identity: string | null — Detected identity if available

Throws:

IsAgentError — When the API call fails

# Exports

From index.ts:

# API Response Format

The SDK makes calls to https://api.isagent.dev/is_agent and returns the following response format:

Sample API Response

Success Response:

Response Fields:

  • identity: string — Detected identity ("human" if no agent was detected)
  • is_agent_client_hint: boolean — true if client likely an agent
  • request_id: string — Unique request identifier for tracking
  • status_code: number — HTTP status code (200 for success)

Note:

The SDK processes this raw API response and provides a simplified interface through the useIsAgent hook. The raw response format is documented here for reference and debugging purposes.

# Requirements

  • React 17.0.0 or higher.
  • A valid Stytch public_token. You may get one by signing up for a Stytch account here.

# Get Help

If you want to report a bug or misclassification, open an issue on GitHub.

If you need help with anything else, just contact us at isagent@stytch.com.