Identify Agents With Node.js

Overview

This guide shows you how to use the NPM package to call the Agent Identification API. Please contact us if you need help.

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: Identify Agent Requests

Call identifyAgent to identify a single incoming request:

const identification = await knownAgents.identifyAgent(request)

Call identifyAgents to identify multiple requests at once:

const identifications = await knownAgents.identifyAgents([
    {
        id: "request-1",
        request_headers: request1.headers
    },
    {
        id: "request-2",
        request_headers: request2.headers
    }
])

These methods return an object (or array of objects) with the following fields:

• id: The identifier from the request (if provided)
• result: The identification result:
  • "verified": The agent was identified and verified
  • "verification_failed": The agent was identified but failed verification (it was spoofed)
  • "not_verifiable": The agent was identified but could not be verified (no method available)
  • "unknown_agent": Not an agent, or the agent is not in the database
• agent_id: The unique ID of the agent (if identified)
• agent_token: The name of the agent (e.g. "Claude-User") (if identified)
• agent_url: The documentation URL of the agent (if identified)
• agent_type_name: The type of agent (e.g. "AI Assistant") (if identified)
• operator_name: The company operating the agent (e.g. "Anthropic") (if identified)