Verify Agents With Node.js

Overview

Use the NPM package to identify and verify legitimate AI agents, crawlers, and bots from a network request. Known Agents verifies agents using Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This can be useful for implementing access policies based on verified agent identity. Please contact us if you need help getting set up.

Step 1: Install the NPM Package

Download the package from NPM using the command line.

npm install @knownagents/sdk

Step 2: Initialize the Client

In your code, create an instance of KnownAgents with your project's access token.

import { KnownAgents } from "@knownagents/sdk"
            
const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")

• Navigate to the Known Agents Projects page and open your project
• Copy your access token from the Settings page
• Back in your code, swap in your access token where it says YOUR_ACCESS_TOKEN

Step 3: Verify an Agent Request

Use the verifyAgent function to check if a request is from a legitimate agent by passing in the incoming request object.

const verification = await knownAgents.verifyAgent(request)

if (verification.result === "verified") {
    // Agent is allowed
} else if (verification.result === "verification_failed") {
    // Agent is not allowed
}

The function returns an object with the following fields:

• result: The verification result:
  • "verified": The agent is identified and verified
  • "verification_failed": The agent was identified but could not be verified
  • "unknown_agent": The agent is not in our database
  • "not_verifiable": The agent cannot be verified (no verification method available)
• agent_id: The unique ID of the agent (if identified)
• agent_token: The name of the agent (e.g. "Googlebot") (if identified)
• agent_url: The documentation URL of the agent (if identified)
• agent_type_name: The type of agent (e.g. "AI Agent") (if identified)
• operator_name: The company behind the agent (e.g. "Google") (if identified)