Agent Census 🔍

Multi-Agent Observability System for AI Web Agents

Agent Census is a real multi-agent system built with CrewAI that monitors, validates, scores, and heals web scraping operations performed by other AI agents. It uses Bright Data's MCP Server for live web scraping and cross-checking.

Architecture

┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│   External   │────▶│ Shadow Tracer │────▶│ Live Validator │────▶│ Health Scorer│
│  AI Agents   │     │  (logs calls) │     │ (re-scrapes &  │     │ (4 metrics)  │
│  PriceBot    │     │               │     │  diffs data)   │     │              │
│  LeadBot     │     └──────────────┘     └───────┬───────┘     └─────────────┘
│  NewsBot     │                                   │
└─────────────┘                                   ▼
                                          ┌─────────────┐
                                          │ Auto-Healer  │
                                          │ (diagnoses & │
                                          │  fixes)      │
                                          └─────────────┘

4 Agents

Agent	Role	Key Tool
Shadow Tracer	Logs & classifies web calls	log_web_call
Live Validator	Re-scrapes & diffs extractions	validate_extraction
Health Scorer	Computes freshness/accuracy/coverage/cost	score_agent
Auto-Healer	Diagnoses failures & suggests fixes	heal_failure

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your API keys (or leave DEMO_MODE=true)

3. Run the Demo Pipeline

python -m agent_census.demo.demo_agents

4. Start the API Server

python agent_census/main.py
# → API at http://localhost:8000
# → Docs at http://localhost:8000/docs

5. Launch the Dashboard (Next.js)

cd dashboard-web
npm install
npm run dev
# → Next.js Dashboard at http://localhost:3000

6. (Optional) Launch Streamlit Dashboard

streamlit run agent_census/dashboard/app.py
# → Dashboard at http://localhost:8501

Demo Mode

With DEMO_MODE=true (default), the system uses mock scrapers that return realistic but varying data — no API keys needed. The demo:

1. Seeds 50 historical web calls across 3 simulated agents (PriceBot, LeadBot, NewsBot)
2. Validates a sample and detects stale data (changed prices, outdated job titles, old news)
3. Runs Auto-Healer on failures (bot blocking, rate limits, selector breaks)
4. Computes health scores per agent

API Endpoints

Method	Path	Description
POST	/api/log	Submit a web call to Shadow Tracer
POST	/api/validate/{log_id}	Trigger Live Validator
GET	/api/health/{agent_id}	Get health scorecard
POST	/api/heal/{log_id}	Trigger Auto-Healer
GET	/api/logs	List recent logs
GET	/api/reports	List validation reports
GET	/api/heals	List heal suggestions
POST	/api/demo/run	Run full demo pipeline
GET	/api/stats	Dashboard summary

Tech Stack

• CrewAI — Multi-agent orchestration
• FastAPI — REST API layer
• SQLite — Persistence (agent_logs, validation_reports, health_scores, heal_history)
• Next.js & React — Modern web observability dashboard
• Streamlit — Alternative Python observing dashboard
• Bright Data MCP — Web scraping & SERP verification
• Pydantic — Data models & validation

Dashboard Features

1. Agent Health Cards — 4 metrics per agent, color-coded (🟢 healthy / 🟡 degraded / 🔴 critical)
2. Live Validation Stream — Real-time log of validations with BEFORE/AFTER diffs
3. Failure Detection Alerts — Red banners when stale data detected
4. Auto-Heal Suggestions — Expandable diagnoses with confidence scores
5. Cost Tracker — API credits burned vs valid extractions chart

License

MIT