Skip to content

kiarashplusplus/AgentRank.it

BranchesTags

Repository files navigation

AgentRank.it

The Page Speed for the Agentic Web

License npm Node.js TypeScript

AgentRank.it measures how reliably an AI agent can navigate your website. While Google Page Speed measures how fast a site loads for humans, we measure the Agent Visibility Score β€” a 0-100 rating of how well AI agents can understand and interact with your site.

🌐 Try it live at agentrank.it

πŸš€ Quick Start

# Run directly with npx (no install required)
npx agentrank audit https://example.com

# Or install globally
npm install -g agentrank
agentrank audit https://example.com

# Or add to your project
npm install agentrank

Programmatic Usage

import { scanUrl } from 'agentrank';

const result = await scanUrl({ url: 'https://example.com' });
console.log(`Agent Score: ${result.agentScore}/100`);

πŸ“Š Agent Visibility Score

The score is composed of 5 weighted signals:

Signal Weight What It Measures
Permissions 20% robots.txt analysis
Structure 25% Semantic HTML density (div soup detection)
Accessibility 25% Accessibility tree depth & ARIA labeling
Hydration 15% Time-to-Interactive for JS rendering
Hostility 15% Bot-blockers (CAPTCHA, Cloudflare, etc.)

πŸ—οΈ Architecture: Two-Speed Design

AgentRank uses a Reactive Escalation architecture to balance cost and accuracy:

Level 1: Speed Reader (Default)

  • Engine: Playwright via Browser Use
  • Input: Structured Accessibility Tree (text-only tokens)
  • Cost: ~$0.002/scan
  • Speed: <5 seconds

Level 2: Visual Resolver (Deep Mode)

  • Trigger: --mode=deep or interaction failures
  • Engine: browser-use with Vision-LLM
  • Cost: ~$0.02/scan
  • Speed: 30-90 seconds

πŸ”§ Deep Mode Setup

Deep mode requires a self-hosted browser-use engine with Vision-LLM capabilities.

Requirements

  • Docker
  • An LLM API key (one of the following):
    • Azure OpenAI (recommended for data privacy)
    • OpenAI API key
    • Anthropic API key

1. Configure Environment

Create a .env file in the project root:

# Option A: Azure OpenAI (recommended - Zero Data Retention)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-azure-key
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Option B: OpenAI
OPENAI_API_KEY=sk-your-openai-key

# Option C: Anthropic
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Optional: Custom browser-use engine endpoint (default: http://localhost:8001)
BROWSER_USE_ENDPOINT=http://localhost:8001

# Optional: Cloudflare R2 for session replay video storage
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY=your-r2-access-key
R2_SECRET_KEY=your-r2-secret-key
R2_BUCKET_NAME=agentrank-replays
R2_PUBLIC_URL=https://replays.yourdomain.com

2. Install Playwright Dependencies (Dev Containers/Codespaces)

If you're running in a dev container or GitHub Codespaces, you need to install Playwright's system dependencies:

npx playwright install-deps chromium

3. Set Directory Permissions

Ensure the Docker container can write to the recordings and data directories:

sudo chown -R 1000:1000 recordings engine-data

4. Start the Engine

docker-compose -f docker-compose.yml up -d --build

This starts the browser-use engine on http://localhost:8001.

5. Run Deep Mode Audit

npx agentrank audit https://example.com --mode=deep

Verify Engine Status

curl http://localhost:8001/health
# Expected: {"status":"ok","video_recording":true,"streaming":true}

Stop the Engine

docker-compose -f docker-compose.yml down

πŸ’» CLI Usage

# Quick scan (default)
agentrank audit https://example.com

# Deep scan with Vision-LLM
agentrank audit https://example.com --mode deep

# JSON output
agentrank audit https://example.com --json

# Start MCP server for IDE integration
agentrank mcp --port 3000

πŸ“¦ Advanced Programmatic Usage

import { scanUrl, calculateScore, getGrade } from 'agentrank';

// Full options
const result = await scanUrl({
  url: 'https://example.com',
  mode: 'deep',           // 'quick' (default) or 'deep'
  timeout: 60000,         // Timeout in ms (default: 30000)
  skipEscalation: false,  // Skip visual fallback (default: false)
  verbose: true,          // Enable verbose logging
});

// Access individual signals
result.signals.permissions.status;  // 'pass' | 'warn' | 'fail'
result.signals.structure.score;     // 0-100
result.signals.accessibility.recommendations; // string[]

// Get grade
const grade = getGrade(result.agentScore); // 'A' | 'B' | 'C' | 'D' | 'F'

πŸ”Œ MCP Integration

AgentRank exposes an MCP server for IDE integration with Cursor and Claude Desktop:

agentrank mcp --port 3000
POST /mcp
{
  "action": "audit",
  "url": "https://example.com",
  "mode": "quick"
}

πŸ› οΈ Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- audit https://example.com

# Run tests
npm test

# Type check
npm run typecheck

πŸ“ Project Structure

src/
β”œβ”€β”€ cli/              # CLI entry point (Commander.js)
β”œβ”€β”€ core/
β”‚   β”œβ”€β”€ scanner.ts    # Main scanner orchestrator
β”‚   └── score.ts      # Score calculation
β”œβ”€β”€ analyzers/        # Signal analyzers (5 modules)
β”œβ”€β”€ engines/
β”‚   β”œβ”€β”€ browser-use.ts       # Level 1: Playwright
β”‚   └── browser-use-server.ts # Level 2: Vision fallback
β”œβ”€β”€ mcp/              # MCP server for IDE integration
β”œβ”€β”€ transcript/       # Think-Aloud narrative generator
└── types/            # TypeScript interfaces

apps/
└── web/              # Next.js web application (agentrank.it)

πŸ›£οΈ Roadmap

  • Respect robots.txt β€” Read and enforce robots.txt directives; refuse to scan pages disallowed by robots.txt

οΏ½πŸ“œ License

Copyright 2025 Kiarash Adl

Licensed under the Apache License, Version 2.0. See LICENSE for details.

About

The PageSpeed Insights for the Agentic Web

agentrank.it

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors 2

  •  
  •  

Languages