Identify Agents With Node.js

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([
    {
        request_id: "request-1",
        request_headers: request1.headers
    },
    {
        request_id: "request-2",
        request_headers: request2.headers
    }
])

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

• request_id: The identifier from the request (if provided)
• result: The identification result:
  • "verified": A known agent was identified and verified (its identity was confirmed as authentic)
  • "verification_failed": A known agent was identified, but failed verification (its identity may have been spoofed)
  • "not_verifiable": A known agent was identified, but its operator does not provide a known verification method
  • "not_identified": No known agent was identified (the request may have come from a human)
• 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)