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
- In GTM, go to Templates → Tag Templates
- Click New → Import
- Import the AgentShield template from our gallery
2. Create a new tag
- Go to Tags → New
- Choose AgentShield Pixel as the tag type
- Configure:
- API Key:
your_api_key_here
- Detection Action:
Block
orLog
- Confidence Threshold:
0.8
- API Key:
3. Set up triggers
- Add trigger: All Pages for basic protection
- Optional: Add custom triggers for specific events
4. Publish
- Click Submit in the top right
- Add version description
- Click Publish
AgentShield is now active through GTM!
Verify Installation
After installation, you can verify AgentShield is working:
Check Detection
- Open your browser's Developer Tools
- Go to the Network tab
- Look for requests to
kya.vouched.id
- 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 Forbiddenredirect
- Redirect to a different URLchallenge
- 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:
- Configure Advanced Options - Fine-tune detection settings
- Marketing Pixel - Learn about the no-code pixel option
- User Identification - Track authenticated users
- 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