Quickstart Guide

CounterAgent detects AI agents by analyzing their TLS handshake fingerprints (JA4/JA4S), HTTP header patterns (JA4H), and certificate signatures (JA4X). This guide gets you running in under 5 minutes.

1. Get Your API Key

Sign up at counteragent.io/docs/authentication to get your API key. Free tier includes 1,000 detections per day.

export COUNTERAGENT_API_KEY="ca_live_..."

2. Detect an Agent

Send a POST request to the detection endpoint with the user-agent and optional JA4 fingerprint:

curl -X POST https://api.counteragent.io/v1/detect \
  -H "Authorization: Bearer $COUNTERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_agent": "python-httpx/0.27.0",
    "ja4": "t13d3514h2_bfa337485184_97a66a8f4cb1"
  }'

Response

{
  "is_agent": true,
  "confidence": 0.95,
  "agent_name": "Python httpx",
  "agent_category": "llm-sdk",
  "fingerprints": {
    "ja4": "t13d3514h2_bfa337485184_97a66a8f4cb1",
    "match_type": "exact"
  }
}

3. SDK Installation

Python

pip install counteragent
from counteragent import Client
client = Client(api_key="ca_live_...")
result = client.detect(user_agent="Go-http-client/2.0", ja4="t13d131100_f57a46bbacb6_e5728521abd4")
print(result.agent_name)  # "Go net/http"

Node.js

npm install @counteragent/sdk
import { CounterAgent } from '@counteragent/sdk';
const ca = new CounterAgent({ apiKey: 'ca_live_...' });
const result = await ca.detect({ userAgent: 'langchain-python/0.2.0' });
console.log(result.agentName);  // "LangChain"

Go

go get github.com/counteragent/counteragent-go
client := counteragent.NewClient("ca_live_...")
result, _ := client.Detect(ctx, counteragent.DetectRequest{
    UserAgent: "CrewAI/0.30.0",
})
fmt.Println(result.AgentName)  // "CrewAI"

4. Integration Guides

5. Next Steps