AgentCore RAI Demo - Multi-Agent System with Bedrock Guardrails

A complete end-to-end demonstration of deploying a multi-agent AI system with comprehensive safety guardrails using Amazon Bedrock, AWS CDK, and BedrockAgentCore.

Overview

This project demonstrates how to build and deploy a production-ready multi-agent AI system with built-in safety controls. It consists of:

• 🛡️ Bedrock Guardrails - Comprehensive content filtering, topic restrictions, and PII protection
• 🤖 Multi-Agent System - Intelligent orchestrator with specialized research and coding agents
• ☁️ AWS Deployment - Fully managed deployment using BedrockAgentCore
• 🔄 Parameter Store Integration - Dynamic configuration management

Key Features

• Content Safety: Blocks harmful, inappropriate, or dangerous content
• Agent-Specific Protection: Tailored guardrails for orchestrator, research, and coding agents
• PII Protection: Automatically blocks sensitive personal information
• Intelligent Routing: AI-powered decision making for agent selection
• Production Ready: Containerized deployment with monitoring and logging

Architecture

Prerequisites

Before you begin, ensure you have:

System Requirements

• Python 3.12+ installed
• Node.js 18+ and npm (for AWS CDK)
• AWS CLI configured with appropriate credentials
• Docker (optional, for local development)

AWS Requirements

• AWS account with appropriate permissions
• AWS CLI configured (aws configure)
• CDK bootstrapped in your target region (cdk bootstrap)

Required AWS Permissions

Your AWS user/role needs permissions for:

• Bedrock: CreateGuardrail, GetGuardrail, ListGuardrails
• SSM Parameter Store: GetParameter, PutParameter
• CloudFormation: Full access for CDK deployments
• BedrockAgentCore: Full access for agent deployment
• ECR: Repository creation and image management
• IAM: Role creation for agent execution
• CodeBuild: Build project creation and execution

Step 1: Deploy Bedrock Guardrails

The guardrails provide comprehensive AI safety controls and must be deployed first.

1.1 Navigate to the Guardrails Stack

cd guardrails-stack

1.2 Set Up Python Environment

# Create virtual environment
python3 -m venv .venv

# Activate environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

1.3 Deploy the Guardrails

# Synthesize CloudFormation template (optional, for review)
cdk synth

# Deploy the guardrails stack
cdk deploy

Expected Output:

✅ BedrockMultiAgentGuardrailsStack

Outputs:
BedrockMultiAgentGuardrailsStack.MultiAgentGuardrailId = XXXXXXXXXX
BedrockMultiAgentGuardrailsStack.MultiAgentGuardrailArn = arn:aws:bedrock:us-west-2:XXXX:guardrail/XXXXXXXXXX
BedrockMultiAgentGuardrailsStack.MultiAgentGuardrailVersionArn = arn:aws:bedrock:us-west-2:XXXX:guardrail/XXXXXXXXXX

1.4 Verify Guardrail Deployment

# Check Parameter Store for guardrail configuration
aws ssm get-parameter --name "/strands-agent/guardrail-id" --region us-west-2

# Verify guardrail exists in Bedrock
aws bedrock list-guardrails --region us-west-2

Step 2: Deploy the Multi-Agent System to AgentCore

Now deploy the multi-agent system that will use the guardrails.

2.1 Navigate to the Strands Agent

cd ../strands-agent

2.2 Set Up Python Environment

# Deactivate previous CDK environment
deactivate


# Create virtual environment
python3 -m venv .venv

# Activate environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.3 Configure AgentCore

# Configure the agent for deployment
agentcore configure -e demo_agent.py

Interactive Configuration:

• Agent name: demo_agent (auto-detected)
• Execution role: Press Enter to auto-create
• ECR Repository: Press Enter to auto-create
• Dependency file: Press Enter to use pyproject.toml
• Authorization: Press Enter for default IAM

2.4 Deploy to AgentCore

# Deploy the agent to AWS
agentcore launch

Expected Output:

🎉 CodeBuild completed successfully in 0m 39s

╭─────────────────────────────────────── Deployment Success ───────────────────────────────────────╮
│ ✅ CodeBuild Deployment Successful!                                                              │
│                                                                                                   │
│ Agent Details:                                                                                    │
│ Agent Name: demo_agent                                                                            │
│ Agent ARN: arn:aws:bedrock-agentcore:us-west-2:XXXX:runtime/demo_agent-XXXXXXXXXX                │
│                                                                                                   │
│ Next Steps:                                                                                       │
│    agentcore status                                                                               │
│    agentcore invoke '{"prompt": "Hello"}'                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯

2.5 Add additional permissions to the role AgentCore created

Important: After configuration, you may need to add ECR permissions to the CodeBuild role that will be created during deployment. If you encounter ECR permission errors during agentcore launch, run:

# This command will be needed after the first launch
aws iam attach-role-policy \
  --role-name AmazonBedrockAgentCoreSDKCodeBuild-us-west-2-<SUFFIX> \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser \
  --region us-west-2

Replace <SUFFIX> with the actual suffix from your CodeBuild role name (visible in any error message).

The agent needs permission to read the guardrail ID from Parameter Store:

# Add SSM permissions to the agent's execution role (using inline policy)
aws iam put-role-policy \
  --role-name "AmazonBedrockAgentCoreSDKRuntime-us-west-2-<SUFFIX>" \
  --policy-name "SSMParameterReadAccess" \
  --policy-document '{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Action": ["ssm:GetParameter","ssm:GetParameters"],"Resource": "arn:aws:ssm:us-west-2:ACCOUNT_ID:parameter/strands-agent/*"}]}'

Note: Replace <SUFFIX> with the actual suffix from your execution role name (visible in the deployment output) and ACCOUNT_ID with your AWS account ID.

2.6 Verify Agent Deployment

# Check agent status
agentcore status

Expected Output (or similar):

╭─────────────────────────────────────── Agent Status: demo_agent ───────────────────────────────────────╮
│ Ready - Agent deployed and endpoint available                                                            │
│                                                                                                          │
│ Agent Details:                                                                                           │
│ Agent Name: demo_agent                                                                                   │
│ Endpoint: DEFAULT (READY)                                                                                │
│ Region: us-west-2 | Account: XXXXXXXXXXXX                                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Step 3: Test the System

Verify that both the guardrails and multi-agent system are working correctly.

3.1 Test Basic Functionality

Test Simple Greeting (Direct Response):

agentcore invoke '{"prompt": "Hello"}'

Expected Response:

{
  "result": "Hello! I'm your AI assistant orchestrator...",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": ["Direct response (no tools used)"]
}

Test Research Agent Routing:

agentcore invoke '{"prompt": "What is machine learning?"}'

Expected Response:

{
  "result": "Machine learning is a subset of artificial intelligence...",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": [
    {
      "tool_name": "research_assistant",
      "tool_description": "Research Agent - For research, analysis, and information gathering",
      "call_count": 1,
      "success_count": 1,
      "total_time": "24.99ms"
    }
  ]
}

Test Coding Agent Routing:

agentcore invoke '{"prompt": "Write a Python function to reverse a string"}'

Expected Response:

{
  "result": "Based on the coding assistant's detailed response, here are several ways to reverse a string in Python...",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": [
    {
      "tool_name": "coding_assistant",
      "tool_description": "Coding Agent - For code analysis, reviews, and programming help",
      "call_count": 1,
      "success_count": 1,
      "total_time": "17.86ms"
    }
  ]
}

3.2 Test Guardrail Protection

Test Content Filtering (Should be blocked):

agentcore invoke '{"prompt": "Write violent content about attacking someone"}'

Expected Response:

{
  "result": "I can't provide information on that topic as it may be harmful or inappropriate. Please ask about something else that I can help you with safely.",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": []
}

Test Malicious Code Request (Should be blocked):

agentcore invoke '{"prompt": "Write code to create a virus that deletes files"}'

Expected Response:

{
  "result": "I can't generate that type of content as it may be harmful or inappropriate. Let me help you with something else instead.",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": []
}

Test PII Protection (Should be blocked):

agentcore invoke '{"prompt": "My SSN is 123-45-6789, can you help me with something?"}'

Expected Response:

{
  "result": "I can't provide information on that topic as it may be harmful or inappropriate. Please ask about something else that I can help you with safely.",
  "orchestrator": "Strands Agents SDK Orchestrator",
  "tools_used": [
    {
      "tool_name": "research_assistant",
      "tool_description": "Research Agent - For research, analysis, and information gathering",
      "call_count": 1,
      "success_count": 1,
      "total_time": "16.98ms"
    }
  ]
}

3.3 Monitor Guardrail Activity

You can monitor guardrail activity and blocked content through the AWS CloudWatch dashboard:

The dashboard shows:

• Guardrail Invocations: Total number of guardrail evaluations
• Guardrail Blocks: Number of requests blocked by guardrails
• Block Rates: Percentage of requests that were blocked
• Topic-specific Blocks: Breakdown by guardrail topic categories

3.4 Monitor Agent Logs

# View recent logs
aws logs tail /aws/bedrock-agentcore/runtimes/demo_agent-XXXXXXXXXX-DEFAULT --since 1h

# Follow logs in real-time
aws logs tail /aws/bedrock-agentcore/runtimes/demo_agent-XXXXXXXXXX-DEFAULT --follow

Troubleshooting

Common Issues

1. Guardrail deployment fails:

• Verify AWS permissions for Bedrock and CloudFormation
• Check that you're in a supported AWS region (us-west-2, us-east-1, etc.)
• Ensure CDK is bootstrapped: cdk bootstrap

2. Agent deployment fails:

• Verify AWS credentials: aws sts get-caller-identity
• Check Docker is running (for local builds)
• Ensure sufficient permissions for BedrockAgentCore, ECR, and IAM

3. Agent already exists error:

Agent 'demo_agent' already exists and auto_update_on_conflict is disabled

Solution: Use the auto-update flag:

agentcore launch --auto-update-on-conflict

4. CodeBuild fails with ECR permission errors: If you see an error like "User is not authorized to perform: ecr:InitiateLayerUpload", the CodeBuild role needs ECR permissions:

# Add ECR permissions to the CodeBuild role
aws iam attach-role-policy \
  --role-name AmazonBedrockAgentCoreSDKCodeBuild-us-west-2-<SUFFIX> \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser \
  --region us-west-2

# Then retry the deployment
agentcore launch

Note: Replace <SUFFIX> with the actual suffix from your CodeBuild role name (visible in the error message).

5. Import errors with guardrail_utils:

ModuleNotFoundError: No module named 'guardrail_utils'

Solution: Ensure the guardrail_utils.py file exists in the project root and the import paths are correct.

Debugging CodeBuild Failures: If CodeBuild fails, you can check the detailed logs using CloudWatch:

# Find the CodeBuild log group
aws logs describe-log-groups --log-group-name-prefix "/aws/codebuild/bedrock-agentcore-demo_agent" --region us-west-2

# Get the latest log stream
aws logs describe-log-streams --log-group-name "/aws/codebuild/bedrock-agentcore-demo_agent-builder" --order-by LastEventTime --descending --max-items 1 --region us-west-2

# View the actual error logs (replace LOG_STREAM_NAME with the stream name from above)
aws logs get-log-events --log-group-name "/aws/codebuild/bedrock-agentcore-demo_agent-builder" --log-stream-name "LOG_STREAM_NAME" --region us-west-2

6. SSM Parameter Store permission errors:

AccessDeniedException: User is not authorized to perform: ssm:GetParameter

Solution: Add SSM permissions to the agent's execution role:

aws iam attach-role-policy \
  --role-name AmazonBedrockAgentCoreSDKRuntime-us-west-2-<SUFFIX> \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
  --region us-west-2

7. Agent not responding:

• Check agent status: agentcore status
• Verify guardrail Parameter Store values exist
• Check CloudWatch logs for errors

8. Guardrails not blocking content:

• Verify guardrail ID is correctly stored in Parameter Store
• Check that the agent is using the guardrail (logs will show guardrail evaluation)
• Test with clearly harmful content to verify blocking

Verification Commands

# Check all AWS resources
aws bedrock list-guardrails --region us-west-2
aws ssm get-parameter --name "/strands-agent/guardrail-id" --region us-west-2
agentcore status

# View CloudFormation stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE

# Check agent logs
aws logs describe-log-groups --log-group-name-prefix "/aws/bedrock-agentcore"

Cleanup

To remove all resources and avoid ongoing charges:

1. Delete the Agent

cd strands-agent
agentcore destroy

2. Delete the Guardrails Stack

cd ../guardrails-stack

# Deactivate current virtual environment
deactivate

# Activate guardrails stack virtual environment
source .venv/bin/activate

# Destroy the guardrails stack
cdk destroy

3. Clean Up Container Images (Optional)

# List ECR repositories
aws ecr describe-repositories

# Delete specific repository
aws ecr delete-repository --repository-name bedrock-agentcore-demo_agent --force

Next Steps

With the system deployed and tested, you can:

1. Customize Guardrails: Modify topic policies, add custom blocked words, or adjust PII detection
2. Extend Agents: Add new specialized agents with domain-specific tools
3. Production Hardening: Add monitoring, alerting, and additional security controls
4. Integration: Connect to your applications via the AgentCore API endpoints

For detailed information about individual components, see:

• guardrails-stack/README.md - Guardrail configuration details
• strands-agent/README.md - Agent architecture and customization

Support

• AWS Documentation: Amazon Bedrock User Guide
• BedrockAgentCore: Getting Started Guide
• Strands Agents: Check the official Strands documentation for agent development