AgentShield

Quick Start

Get AgentShield running in 5 minutes

5-Minute Setup

Choose your preferred integration method and follow the steps below.

Next.js Quick Start

1. Install the package

npm install @kya-os/agentshield-nextjs

2. Create middleware

Create middleware.ts in your project root:

import { agentShield } from '@kya-os/agentshield-nextjs';

export default agentShield({
  apiKey: process.env.AGENTSHIELD_API_KEY,
  onAgentDetected: 'block', // or 'log', 'redirect'
  confidenceThreshold: 0.8,
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

3. Add environment variable

# .env.local
AGENTSHIELD_API_KEY=your_api_key_here

4. Deploy

npm run build
npm run start

That's it! AgentShield is now protecting your Next.js application.

Express Quick Start

1. Install the package

npm install @kya-os/agentshield-express

2. Add middleware

import express from 'express';
import { agentShield } from '@kya-os/agentshield-express';

const app = express();

// Add AgentShield middleware
app.use(agentShield({
  apiKey: process.env.AGENTSHIELD_API_KEY,
  onAgentDetected: 'block',
  confidenceThreshold: 0.8,
}));

// Your routes
app.get('/', (req, res) => {
  res.send('Protected by AgentShield!');
});

app.listen(3000);

3. Add environment variable

# .env
AGENTSHIELD_API_KEY=your_api_key_here

4. Run your server

node app.js

Your Express application is now protected!

JavaScript Beacon Quick Start

1. Install the package

npm install @kya-os/agentshield-beacon

2. Initialize the beacon

import { AgentShieldBeacon } from '@kya-os/agentshield-beacon';

// Initialize beacon
const beacon = new AgentShieldBeacon({
  apiKey: 'your_api_key_here',
  // Optional: Enable debug mode in development
  debug: process.env.NODE_ENV === 'development',
});

// Start tracking
beacon.collect('pageview');

3. Track custom events (optional)

// Track user interactions
document.getElementById('signup-btn').addEventListener('click', () => {
  beacon.trackEvent('signup_attempt', {
    page: window.location.pathname,
  });
});

4. Using CDN (alternative)

<script src="https://cdn.jsdelivr.net/npm/@kya-os/agentshield-beacon/dist/beacon.min.js"></script>
<script>
  const beacon = new AgentShieldBeacon({
    apiKey: 'your_api_key_here',
  });
  beacon.collect('pageview');
</script>

The beacon is now tracking and detecting AI agents!

Google Tag Manager Quick Start

1. Import the template

  1. In GTM, go to TemplatesTag Templates
  2. Click NewImport
  3. Import the AgentShield template from our gallery

2. Create a new tag

  1. Go to TagsNew
  2. Choose AgentShield Pixel as the tag type
  3. Configure:
    • API Key: your_api_key_here
    • Detection Action: Block or Log
    • Confidence Threshold: 0.8

3. Set up triggers

  1. Add trigger: All Pages for basic protection
  2. Optional: Add custom triggers for specific events

4. Publish

  1. Click Submit in the top right
  2. Add version description
  3. Click Publish

AgentShield is now active through GTM!

Verify Installation

After installation, you can verify AgentShield is working:

Check Detection

  1. Open your browser's Developer Tools
  2. Go to the Network tab
  3. Look for requests to kya.vouched.id
  4. Check the Console for debug messages (if debug mode is enabled)

Test with User Agents

Try accessing your site with known bot user agents:

# Test with curl (often detected as automated)
curl -H "User-Agent: Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" \
     https://your-site.com

# Should return blocked response if configured to block

Testing Tip: Use our testing tool to simulate different types of agents accessing your site.

Common Configuration Options

API Key

Get your API key from the AgentShield Dashboard.

Detection Actions

  • log - Record detection but allow access (default)
  • block - Return 403 Forbidden
  • redirect - Redirect to a different URL
  • challenge - Show a challenge page

Confidence Threshold

  • 0.5 - Balanced (some false positives)
  • 0.7 - Recommended for most sites
  • 0.8 - Conservative (fewer false positives)
  • 0.9 - Very conservative

Environment Variables

We recommend using environment variables for sensitive configuration:

# .env or .env.local
AGENTSHIELD_API_KEY=your_api_key_here
AGENTSHIELD_ACTION=block
AGENTSHIELD_THRESHOLD=0.8
AGENTSHIELD_DEBUG=false

Then in your code:

const config = {
  apiKey: process.env.AGENTSHIELD_API_KEY,
  onAgentDetected: process.env.AGENTSHIELD_ACTION || 'log',
  confidenceThreshold: parseFloat(process.env.AGENTSHIELD_THRESHOLD || '0.8'),
  debug: process.env.AGENTSHIELD_DEBUG === 'true',
};

Next Steps

Now that AgentShield is running:

  1. Configure Advanced Options - Fine-tune detection settings
  2. Marketing Pixel - Learn about the no-code pixel option
  3. User Identification - Track authenticated users
  4. Package Selection - Explore other integration options

Troubleshooting

Not detecting agents?

  • Verify API key is correct
  • Check network requests in browser DevTools
  • Ensure middleware is properly configured
  • Review confidence threshold settings

Too many false positives?

  • Increase confidence threshold (e.g., 0.8 → 0.9)
  • Whitelist specific user agents
  • Review detection patterns in dashboard

Performance issues?

  • Enable WebWorker mode (beacon)
  • Use edge runtime (Next.js)
  • Implement caching strategies
  • Review the Beacon Worker Mode documentation

Get Help

Command Palette

Search for a command to run...