AWS Bedrock Guardrails Implementation Guide

Overview

This document describes the complete Bedrock Guardrails implementation for Vell AgentCore. The system allows platform admins, teams, and individual users to apply AWS Bedrock Guardrails to AI agent executions for content safety, compliance, and responsible AI governance.

Architecture

Database Schema

1. bedrock_guardrails Table

Stores guardrail configurations synced from AWS or manually created.

Key Fields: - guardrail_id: AWS Bedrock guardrail identifier - scope: platform, user, or team - content_filters: Hate, violence, sexual, insults, misconduct, prompt_attack - denied_topics: Custom topic-based filtering - word_filters: Profanity and custom word filtering - sensitive_info_filters: PII detection (SSN, credit cards, etc.) - contextual_grounding: For RAG use cases (hallucination detection)

2. ext_content_manager_agents Table (Updated)

New guardrail fields added: - guardrail_id: Reference to the guardrail to use - guardrail_version: Version (e.g., DRAFT, 1, 2) - guardrail_enabled: Boolean to enable/disable - guardrail_trace_enabled: Enable detailed trace logging

3. settings_two Table (Updated)

Platform-wide settings: - bedrock_default_guardrail_id: Default guardrail for new agents - bedrock_guardrails_enabled_by_default: Auto-enable for new agents - bedrock_require_guardrails: Force all agents to use guardrails

---

Access Models

Guardrails work with all three Bedrock access models:

1. Platform Mode

• Admin manages platform-wide guardrails
• All users share the same AWS account's guardrails
• Guardrails created in platform AWS account

2. User Keys Mode (BYOC)

• Users bring their own AWS credentials
• Each user can create guardrails in their AWS account
• Sync personal guardrails from user's Bedrock account

3. User Role Mode (BYOC)

• Users provide IAM role ARN for cross-account access
• Platform assumes role to access user's guardrails
• Most secure BYOC approach

---

Components

Backend Services

GuardrailService (app/Services/Bedrock/GuardrailService.php)

Main service for managing guardrails: - listFromAWS(): List guardrails from AWS Bedrock - getFromAWS($id, $version): Get guardrail details - syncFromAWS($scope, $userId, $teamId): Sync from AWS to database - getAvailableGuardrails($user): Get guardrails available to user

BedrockRuntimeService (app/Services/Bedrock/BedrockRuntimeService.php)

Updated to support guardrail parameters:

$bedrockService->invokeModel($modelId, $prompt, [
    'guardrail_id' => 'gr-abc123',
    'guardrail_version' => 'DRAFT',
    'guardrail_trace' => true,
]);

AgentOrchestrator (app/Extensions/ContentManager/System/Services/AgentCore/AgentOrchestrator.php)

Automatically passes guardrail config from Agent to WorkflowPlanner if enabled.

WorkflowPlanner (app/Extensions/ContentManager/System/Services/AgentCore/WorkflowPlanner.php)

Passes guardrail options to BedrockRuntimeService during workflow planning.

Models

BedrockGuardrail (app/Models/BedrockGuardrail.php)

• availableForUser($user): Get guardrails available to a user
• isEditableBy($user): Check if user can edit guardrail
• Scopes: platform(), user(), team(), active()

Agent (app/Extensions/ContentManager/System/Models/Agent.php)

Updated with guardrail fields in $fillable and $casts.

Controllers

Admin\GuardrailController (app/Http/Controllers/Admin/GuardrailController.php)

Admin panel for managing platform guardrails: - index(): List all guardrails - sync(): Sync from AWS Bedrock - store(): Create manual guardrail entry - update(): Update guardrail - destroy(): Delete guardrail

User\GuardrailController (app/Http/Controllers/User/GuardrailController.php)

User panel for managing personal guardrails (BYOC mode): - index(): View available guardrails - sync(): Sync from user's AWS account - store(): Add personal guardrail - destroy(): Remove personal guardrail

---

Usage Workflow

For Platform Admins

1. Create Guardrail in AWS Bedrock Console

# Navigate to AWS Console > Bedrock > Guardrails
# Create a new guardrail with desired policies
# Note the Guardrail ID (e.g., gr-abc123xyz)

2. Sync to Vell Platform

# Via Admin UI (recommended)
POST /admin/guardrails/sync

# Or manually via API
curl -X POST https://your-vell-instance.com/admin/guardrails/sync \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"scope": "platform"}'

3. Set as Default (Optional)

# Update settings_two table
UPDATE settings_two
SET bedrock_default_guardrail_id = 'gr-abc123xyz',
    bedrock_guardrails_enabled_by_default = true
WHERE id = 1;

4. Assign to Agents

# Via Agent edit UI
# Select guardrail from dropdown
# Enable "Use Guardrails" checkbox

For AWS Partners (BYOC Mode)

1. Deploy CloudFormation Template

# Use updated template with guardrail permissions
aws cloudformation create-stack \
  --stack-name vell-agentcore-bedrock \
  --template-body file://vell-agentcore-bedrock-role.yaml \
  --parameters ParameterKey=ExternalId,ParameterValue=<external-id> \
  --capabilities CAPABILITY_IAM

2. Configure BYOC in Vell

# Set bedrock_access_model to 'user_role'
# Provide Role ARN and External ID

3. Create Guardrails in Your AWS Account

# Use AWS Bedrock console in your account
# Create guardrails with your organization's policies

4. Sync to Vell

# Via User Settings > Guardrails
POST /user/guardrails/sync

5. Use in Agents

# Your personal guardrails will appear in agent configuration
# Select and enable for agents you create

---

UI Integration Points

Admin Panel

Location: resources/views/panel/admin/guardrails/index.blade.php

Features Needed: - [ ] Table listing all guardrails (platform, user, team) - [ ] "Sync from AWS" button → calls /admin/guardrails/sync - [ ] Add manual guardrail form - [ ] Edit guardrail modal - [ ] Delete confirmation - [ ] Filter by scope (platform/user/team) - [ ] View guardrail details (content filters, denied topics, etc.)

Example UI Structure:

<div class="guardrails-page">
  <div class="header">
    <h1>Bedrock Guardrails</h1>
    <button onclick="syncFromAWS()">Sync from AWS</button>
    <button onclick="showAddModal()">Add Manual Guardrail</button>
  </div>

  <div class="tabs">
    <button class="tab active">Platform Guardrails</button>
    <button class="tab">User Guardrails</button>
    <button class="tab">Team Guardrails</button>
  </div>

  <table class="guardrails-table">
    <thead>
      <tr>
        <th>Name</th>
        <th>Guardrail ID</th>
        <th>Version</th>
        <th>Status</th>
        <th>Scope</th>
        <th>Usage Count</th>
        <th>Last Used</th>
        <th>Actions</th>
      </tr>
    </thead>
    <tbody>
      <!-- Loop through guardrails -->
    </tbody>
  </table>
</div>

Agent Configuration UI

Location: Add to agent create/edit forms (e.g., resources/views/panel/admin/agents/form.blade.php)

Features Needed: - [ ] Guardrail selection dropdown - [ ] "Enable Guardrails" checkbox - [ ] "Enable Trace Logging" checkbox (for debugging) - [ ] Version selector (DRAFT, 1, 2, etc.) - [ ] Preview guardrail policies

Example Form Fields:

<div class="form-group">
  <label class="switch">
    <input type="checkbox" name="guardrail_enabled" id="guardrail_enabled">
    <span class="slider"></span>
  </label>
  <label for="guardrail_enabled">Enable Bedrock Guardrails</label>
</div>

<div class="form-group" id="guardrail-config" style="display:none;">
  <label>Select Guardrail</label>
  <select name="guardrail_id" id="guardrail_id">
    <option value="">-- Select Guardrail --</option>
    @foreach($availableGuardrails as $guardrail)
      <option value="{{ $guardrail->guardrail_id }}">
        {{ $guardrail->display_name }}
      </option>
    @endforeach
  </select>

  <label>Version</label>
  <select name="guardrail_version">
    <option value="DRAFT">DRAFT</option>
    <option value="1">Version 1</option>
    <option value="2">Version 2</option>
  </select>

  <label class="switch">
    <input type="checkbox" name="guardrail_trace_enabled">
    <span class="slider"></span>
  </label>
  <label>Enable trace logging (for debugging)</label>
</div>

<script>
document.getElementById('guardrail_enabled').addEventListener('change', function() {
  document.getElementById('guardrail-config').style.display =
    this.checked ? 'block' : 'none';
});
</script>

User Settings (BYOC Mode)

Location: resources/views/panel/user/guardrails/index.blade.php

Features Needed: - [ ] View available guardrails (platform + personal) - [ ] "Sync My Guardrails" button (only in BYOC mode) - [ ] Add personal guardrail form - [ ] Delete personal guardrails - [ ] View guardrail details

---

API Routes

Add these routes to routes/web.php:

// Admin routes (requires admin middleware)
Route::middleware(['auth', 'admin'])->prefix('admin')->group(function () {
    Route::get('/guardrails', [Admin\GuardrailController::class, 'index'])
        ->name('admin.guardrails.index');
    Route::post('/guardrails/sync', [Admin\GuardrailController::class, 'sync'])
        ->name('admin.guardrails.sync');
    Route::get('/guardrails/aws-list', [Admin\GuardrailController::class, 'listFromAWS'])
        ->name('admin.guardrails.aws-list');
    Route::post('/guardrails', [Admin\GuardrailController::class, 'store'])
        ->name('admin.guardrails.store');
    Route::get('/guardrails/{guardrail}', [Admin\GuardrailController::class, 'show'])
        ->name('admin.guardrails.show');
    Route::put('/guardrails/{guardrail}', [Admin\GuardrailController::class, 'update'])
        ->name('admin.guardrails.update');
    Route::delete('/guardrails/{guardrail}', [Admin\GuardrailController::class, 'destroy'])
        ->name('admin.guardrails.destroy');
});

// User routes (requires auth middleware)
Route::middleware(['auth'])->prefix('user')->group(function () {
    Route::get('/guardrails', [User\GuardrailController::class, 'index'])
        ->name('user.guardrails.index');
    Route::get('/guardrails/available', [User\GuardrailController::class, 'available'])
        ->name('user.guardrails.available');
    Route::post('/guardrails/sync', [User\GuardrailController::class, 'sync'])
        ->name('user.guardrails.sync');
    Route::post('/guardrails', [User\GuardrailController::class, 'store'])
        ->name('user.guardrails.store');
    Route::delete('/guardrails/{guardrail}', [User\GuardrailController::class, 'destroy'])
        ->name('user.guardrails.destroy');
});

// API routes for agent configuration (get available guardrails)
Route::middleware(['auth'])->prefix('api')->group(function () {
    Route::get('/guardrails/available', [Admin\GuardrailController::class, 'available'])
        ->name('api.guardrails.available');
});

---

Migration Instructions

1. Run Migrations

php artisan migrate

This will: - Add guardrail columns to ext_content_manager_agents - Create bedrock_guardrails table - Add platform settings to settings_two

2. Update IAM Role (for BYOC users)

# Users need to update their CloudFormation stack
aws cloudformation update-stack \
  --stack-name vell-agentcore-bedrock \
  --template-body file://vell-agentcore-bedrock-role.yaml \
  --capabilities CAPABILITY_IAM

3. Sync Existing Guardrails (Optional)

# Via artisan command (create this):
php artisan bedrock:sync-guardrails --scope=platform

# Or via admin UI

---

Monitoring & Logging

Guardrail Interventions

When a guardrail blocks content, it's logged:

// In Laravel logs
[2025-11-19 12:34:56] WARNING: Bedrock Guardrail Intervention
{
  "model_id": "anthropic.claude-3-sonnet-20240229-v1:0",
  "user_id": 42,
  "action": "INTERVENED",
  "outputs": [
    {
      "type": "CONTENT_FILTER",
      "filter": "VIOLENCE",
      "action": "BLOCKED"
    }
  ],
  "guardrail_id": "gr-abc123xyz"
}

Usage Tracking

Track guardrail usage in bedrock_guardrails table: - usage_count: Incremented on each use - last_used_at: Timestamp of last use

Agent Execution Results

Store guardrail interventions in ext_content_manager_agent_executions.step_results:

{
  "step": 1,
  "capability": "generate_text",
  "guardrail_intervention": {
    "blocked": true,
    "reason": "Content filter: VIOLENCE",
    "details": { ... }
  }
}

---

Testing

Manual Testing

1. Test Platform Guardrail

# Create guardrail in AWS console
# Sync to Vell
# Create agent with guardrail enabled
# Execute agent with content that should be blocked
# Verify guardrail intervention logged

2. Test BYOC Guardrail

# Configure user_role access model
# User creates guardrail in their AWS account
# User syncs via /user/guardrails/sync
# User creates agent with personal guardrail
# Execute and verify

3. Test Trace Logging

# Enable guardrail_trace_enabled on agent
# Execute agent
# Check logs for detailed guardrail traces

Automated Testing

Create tests in tests/Feature/GuardrailTest.php: - Test guardrail sync from AWS - Test agent execution with guardrails - Test guardrail intervention logging - Test BYOC guardrail access

---

Security Considerations

IAM Permissions

Platform Mode: - Requires bedrock:GetGuardrail - Requires bedrock:ListGuardrails - Requires bedrock:ApplyGuardrail

BYOC Mode: - Users cannot modify guardrails via Vell - Users can only use existing guardrails from their account - CloudFormation template explicitly denies CreateGuardrail, UpdateGuardrail, DeleteGuardrail

Data Privacy

• Guardrail traces may contain user prompts
• Store traces securely
• Consider GDPR/compliance requirements for logging

---

Troubleshooting

Common Issues

1. "Guardrail validation failed" - Check guardrail ID is correct - Verify guardrail version exists - Ensure IAM role has GetGuardrail permission

2. "Failed to sync guardrails" - Verify AWS credentials are valid - Check bedrock_access_model setting - Ensure user has ListGuardrails permission

3. Guardrail not appearing in agent dropdown - Check guardrail status is 'active' - Verify scope (platform guardrails available to all, user guardrails only to owner) - Refresh guardrail list

4. Guardrail not being applied - Verify guardrail_enabled is true on agent - Check guardrail_id is not null - Review logs for BedrockRuntimeService errors

---

Future Enhancements

• Bulk guardrail sync across teams
• Guardrail effectiveness reporting
• Custom guardrail templates
• Guardrail version management UI
• Integration with compliance reporting
• Guardrail testing sandbox

---

Support

For issues or questions: - Check Laravel logs: storage/logs/laravel.log - Review AWS CloudWatch logs (for BYOC) - Contact platform admin - Refer to AWS Bedrock Guardrails documentation