AI safety guardrails for VoltAgent: THSP protocol validation, OWASP protection, and PII detection for autonomous AI agents
npm install @sentinelseed/voltagentbash
npm install @sentinelseed/voltagent
`
Quick Start
The simplest way to add Sentinel protection to your VoltAgent agent:
`typescript
import { Agent } from "@voltagent/core";
import { createSentinelGuardrails } from "@sentinelseed/voltagent";
// Create guardrails with preset configuration
const { inputGuardrails, outputGuardrails } = createSentinelGuardrails({
level: "strict",
enablePII: true,
});
// Add to your agent
const agent = new Agent({
name: "safe-agent",
inputGuardrails,
outputGuardrails,
});
`
Configuration Presets
| Level | Description |
|-------|-------------|
| permissive | Log only, no blocking. Good for development. |
| standard | Block unsafe content, THSP + OWASP enabled. Recommended for production. |
| strict | All validations, block on any issue. For high-security applications. |
Usage Examples
$3
`typescript
import { createSentinelInputGuardrail } from "@sentinelseed/voltagent";
const inputGuard = createSentinelInputGuardrail({
enableTHSP: true,
enableOWASP: true,
blockUnsafe: true,
});
const agent = new Agent({
inputGuardrails: [inputGuard],
});
`
$3
`typescript
import { createSentinelOutputGuardrail } from "@sentinelseed/voltagent";
const outputGuard = createSentinelOutputGuardrail({
enablePII: true,
redactPII: true,
});
const agent = new Agent({
outputGuardrails: [outputGuard],
});
// Input: "Contact john@example.com or call 555-123-4567"
// Output: "Contact [EMAIL] or call [PHONE]"
`
$3
`typescript
import {
createChatGuardrails,
createAgentGuardrails,
createPrivacyGuardrails,
} from "@sentinelseed/voltagent";
// For chat applications (jailbreak prevention)
const chatGuards = createChatGuardrails();
// For agent applications (tool call protection)
const agentGuards = createAgentGuardrails();
// For privacy-sensitive applications (full PII protection)
const privacyGuards = createPrivacyGuardrails();
`
$3
`typescript
const guard = createSentinelInputGuardrail({
customPatterns: [
{
pattern: /internal\s+only/i,
name: "Internal content restriction",
gate: "scope",
severity: "high",
},
],
});
`
THSP Protocol
The THSP protocol validates content against four safety gates:
| Gate | Description | Example Violations |
|------|-------------|-------------------|
| Truth | Factual accuracy | Fake documents, impersonation |
| Harm | Potential for harm | Violence, malware, theft |
| Scope | Operational boundaries | Jailbreaks, persona switching |
| Purpose | Legitimate intent | Purposeless destruction |
OWASP Protection
Detects common security vulnerabilities:
- SQL Injection
- Cross-Site Scripting (XSS)
- Command Injection
- Path Traversal
- Server-Side Request Forgery (SSRF)
- Prompt Injection
- Sensitive Data Exposure
PII Types Detected
- Email addresses
- Phone numbers
- Social Security Numbers
- Credit card numbers
- IP addresses
- Dates of birth
- API keys / AWS keys
- Private keys
- JWT tokens
- Passport numbers
- Driver license numbers
Streaming Support
For streaming responses, use the stream handler:
`typescript
import { createSentinelPIIRedactor } from "@sentinelseed/voltagent";
const piiRedactor = createSentinelPIIRedactor({
enablePII: true,
piiTypes: ["EMAIL", "PHONE", "SSN"],
});
const guardrail = {
name: "pii-stream-redactor",
handler: async (args) => ({ pass: true }),
streamHandler: piiRedactor,
};
`
API Reference
$3
| Function | Description |
|----------|-------------|
| createSentinelGuardrails(config) | Create complete input/output guardrail bundle |
| createChatGuardrails() | Preset for chat applications |
| createAgentGuardrails() | Preset for agent applications |
| createPrivacyGuardrails() | Preset for privacy-focused applications |
| createDevelopmentGuardrails(logger) | Permissive preset for development |
$3
| Function | Description |
|----------|-------------|
| createSentinelInputGuardrail(config) | Main input guardrail factory |
| createStrictInputGuardrail() | Strict preset |
| createPermissiveInputGuardrail(logger) | Log-only preset |
| createTHSPOnlyGuardrail() | THSP validation only |
| createOWASPOnlyGuardrail() | OWASP validation only |
$3
| Function | Description |
|----------|-------------|
| createSentinelOutputGuardrail(config) | Main output guardrail factory |
| createPIIOutputGuardrail(options) | PII-focused output guardrail |
| createStrictOutputGuardrail() | Block on any sensitive content |
| createPermissiveOutputGuardrail(logger) | Redact only, no blocking |
$3
| Function | Description |
|----------|-------------|
| createSentinelPIIRedactor(config) | Streaming PII redactor |
| createStrictStreamingRedactor(config) | Abort on sensitive content |
| createPermissiveStreamingRedactor(types) | PII redaction only |
| createMonitoringStreamHandler(logger) | Detection without modification |
$3
| Function | Description |
|----------|-------------|
| validateTHSP(content, context, patterns) | Run THSP validation |
| validateOWASP(content, checks, patterns) | Run OWASP validation |
| detectPII(content, types, patterns) | Detect PII in content |
| redactPII(content, types, format) | Redact PII from content |
| quickCheck(content) | Fast THSP check |
| quickOWASPCheck(content) | Fast OWASP check |
| hasPII(content) | Quick PII detection |
Configuration Options
`typescript
interface SentinelGuardrailConfig {
// Behavior
blockUnsafe?: boolean; // Block unsafe content (default: true)
logChecks?: boolean; // Enable logging (default: false)
logger?: (msg, data) => void; // Custom logger function
// Validation modules
enableTHSP?: boolean; // Enable THSP (default: true)
enableOWASP?: boolean; // Enable OWASP (default: true)
enablePII?: boolean; // Enable PII detection (default: false)
// THSP options
customPatterns?: PatternDefinition[];
skipActions?: string[];
minBlockLevel?: RiskLevel; // 'low' | 'medium' | 'high' | 'critical'
// OWASP options
owaspChecks?: OWASPViolationType[];
customOWASPPatterns?: OWASPPatternDefinition[];
// PII options
piiTypes?: PIIType[];
redactPII?: boolean;
redactionFormat?: string | ((type, value) => string);
// Performance
maxContentLength?: number; // Max content length (default: 100000)
timeout?: number; // Timeout in ms (default: 5000)
}
`
Requirements
- Node.js >= 18.0.0
- VoltAgent >= 0.1.0 (tested with @voltagent/core v1.5.2)
Development
This package depends on @anthropic/sentinel-core which provides the THSP validation patterns. When developing locally, the dependency is resolved via file:../core in the monorepo structure.
For production npm installations, the core patterns are bundled during the build process. If you're building from source, ensure you have the full monorepo cloned:
`bash
git clone https://github.com/sentinel-seed/sentinel.git
cd sentinel
npm install
npm run build -w packages/core
npm run build -w packages/voltagent
`
Related Packages
- sentinelseed: Python package
- @sentinelseed/elizaos-plugin`: ElizaOS integration