Package Selection Matrix
Understand limitations, use cases, and optimal combinations for AgentShield packages
Package Limitations & Why to Use
| Package | Limitations | Use When You Need |
|---|---|---|
| Marketing Pixel | • Cannot block agents (log only) • No access to auth/session data • Requires JavaScript execution • Limited to GTM capabilities | • Zero technical knowledge deployment • Marketing team autonomy • Quick testing/POC • Multiple sites from one GTM container |
| Beacon | • Client-side only (can be bypassed) • Cannot prevent initial page load • No server-side session access • Requires JavaScript enabled | • Static sites or JAMstack apps • Maximum browser fingerprinting • Non-blocking performance critical • Rich client-side analytics |
| Next.js | • Only works with Next.js 13+ • Adds ~5ms latency per request • Requires server/edge runtime • May conflict with other middleware | • Block agents before they access data • Protect authenticated routes • Detect agents using user credentials • Server-side rendering protection |
| Express | • Requires Node.js backend • Must modify server code • Adds processing overhead • Not suitable for serverless | • API endpoint protection • Custom response logic needed • Integration with existing Node.js auth • Detailed request analysis required |
| NoScript | • Limited data collection (headers only) • Cannot block (detection only) • Lower confidence scores • No behavioral analysis | • Catch AI agents that don't run JS • Detect curl/wget scrapers • Maximum coverage important • Complement existing detection |
Real-World Scenarios
SaaS Dashboard
Context: B2B SaaS with authenticated users, sensitive data, API endpoints
Recommended: Next.js + NoScript
Coverage: ~99%
Why: Blocks agents using stolen credentials, protects API routes, catches all agent types
News Website
Context: Public content, ad revenue model, SEO important
Recommended: Marketing Pixel (GTM) + NoScript
Coverage: ~94%
Why: Easy setup, doesn't block legitimate crawlers, tracks AI agents for analytics
E-commerce Site
Context: Product catalog, price scraping concerns, checkout protection
Recommended: Beacon (Catalog pages) + Next.js (Checkout)
Coverage: ~98%
Why: Performance for browsing, strict protection for transactions
REST API Service
Context: Pure API, no frontend, rate limiting needed
Recommended: Express Middleware only
Coverage: ~98%
Why: Server-side only solution, full request analysis, can enforce rate limits
Documentation Site
Context: Static site, public content, want metrics only
Recommended: Beacon only
Coverage: ~95%
Why: Lightweight, doesn't interfere with legitimate use, good analytics
Banking Platform
Context: Maximum security, compliance requirements, zero tolerance
Recommended: Next.js + Beacon + NoScript
Coverage: ~99.5%
Why: Multi-layer defense, maximum detection confidence, audit trail
Powerful Combinations
Maximum Coverage
Middleware + NoScriptCatches 99%+ of all agents, including those that don't execute JavaScript
Performance + Protection
Beacon (public) + Middleware (auth)Fast public pages with WebWorker, strict protection for authenticated areas
Progressive Enhancement
Pixel → Beacon → MiddlewareStart with GTM, add Beacon for better data, upgrade to Middleware for blocking
Multi-Property
Pixel (marketing sites) + Middleware (app)One GTM for all marketing sites, dedicated protection for main application
Defense in Depth
All packages combinedMultiple detection layers, cross-validation, highest confidence scores
A/B Testing
Pixel (control) + Beacon (test)Compare detection rates and performance impact before full rollout
Important: Using multiple packages on the same page may result in duplicate detections. Use our deduplication API or configure packages to work in complementary zones (e.g., Beacon for public, Middleware for authenticated).
Quick Decision Guide
| If you have... | Use this... |
|---|---|
| Next.js app | @kya-os/agentshield-nextjs |
| Express/Node.js app | @kya-os/agentshield-express |
| Static site or SPA | @kya-os/agentshield-beacon |
| WordPress/CMS | Marketing Pixel via GTM |
| Multiple properties | Marketing Pixel + specific integrations |
Performance Impact
| Package | Page Load | Per Request | Network |
|---|---|---|---|
| Pixel | < 10ms | Minimal | 1 req/page |
| Beacon | < 5ms | 0ms (WebWorker) | Batched |
| Next.js | 0ms | 2-5ms | None |
| Express | 0ms | 1-2ms | None |
| NoScript | 0ms | 0ms | 43 bytes |
Next Steps
- Identify your scenario from the examples above
- Choose your package(s) based on the recommendations
- Follow the installation guide for your selected package
- Monitor detections in your dashboard
- Add packages as needed for increased coverage