CounterAgent SDK

Detect, classify, and monitor autonomous AI agents interacting with your infrastructure.

CounterAgent maintains the largest database of AI agent TLS/HTTP fingerprints, covering major frameworks including LangChain, CrewAI, AutoGPT, Claude API, OpenAI SDK, and browser-based agents.

Installation

pip install counteragent

Quick Start

import counteragent

client = counteragent.Client(api_key="your-api-key")

# Detect if a request is from an AI agent
result = client.detect(
    user_agent="python-httpx/0.27.0",
    ja4="t13d13h12_...",
)

print(result.is_agent)       # True
print(result.agent_name)     # "LangChain"
print(result.confidence)     # 0.94

API Reference

Full documentation: docs.counteragent.io

Detection

# Detect agent from request metadata
result = client.detect(
    user_agent="...",
    ja4="...",           # JA4 TLS fingerprint
    ja4h="...",          # JA4H HTTP fingerprint
    headers={"...": "..."},
)

Fingerprint Lookup

# Look up a known fingerprint
signatures = client.lookup(ja4="t13d13h12_...")
for sig in signatures:
    print(f"{sig.agent_name}: {sig.fingerprint}")

List Known Agents

# Browse the agent database
agents = client.agents(category="llm-sdk")
for agent in agents:
    print(f"{agent.name} ({agent.category})")

Webhook Alerts

# Get notified when new agents are detected
client.webhooks.create(
    url="https://your-app.com/webhook",
    events=["new_agent", "new_signature"],
)

Fingerprint Types

Type	Layer	What It Captures
JA4	TLS ClientHello	TLS version, cipher suites, extensions
JA4S	TLS ServerHello	Server's chosen cipher and extensions
JA4H	HTTP Request	Method, headers, header order
JA4X	X.509 Certificate	Issuer, subject, extensions hash

API Endpoints

Endpoint	Method	Description
https://api.counteragent.io/v1/detect	POST	Detect if request is from an AI agent
https://api.counteragent.io/v1/fingerprint/lookup	GET	Look up a fingerprint
https://api.counteragent.io/v1/agents	GET	List known agent frameworks
https://api.counteragent.io/v1/signatures	GET	Browse signature database
https://api.counteragent.io/v1/webhooks	POST	Register webhook alerts

OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

• counteragent.io/openapi.yaml
• counteragent.io/.well-known/ai-plugin.json

Authentication

# Using API key
client = counteragent.Client(api_key="ca_live_...")

# Using OAuth2 client credentials
client = counteragent.Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
    token_url="https://auth.counteragent.io/oauth/token",
)

OIDC discovery: auth.counteragent.io/.well-known/openid-configuration

License

Apache 2.0

Links

• Website: counteragent.io
• API Docs: docs.counteragent.io
• OpenAPI Spec: counteragent.io/openapi.yaml
• Status: status.counteragent.io
• Contact: api@counteragent.io