Smart Budget Buddy - AWS Bedrock Agent - UDACITY AWS AI Engineer Nanodegree

An AI-powered financial literacy assistant built with AWS Bedrock Agent and Guardrails to help high school students graduate with financial confidence.

Follow this README top to bottom and you'll go from a fresh setup to a working Bedrock Agent ready to help students with budgeting, saving, and smart financial decisions.

---

About This Project

This project was developed as part of the Udacity AWS AI Engineer Nanodegree Program. It demonstrates end-to-end implementation of a production-ready conversational AI agent using AWS managed services, covering:

• Infrastructure as Code (CloudFormation) for Bedrock Agent and Guardrails
• Responsible AI implementation with comprehensive safety guardrails
• Prompt engineering for financial literacy education
• Multi-model support with Amazon Nova (Pro/Lite/Micro)
• Production-ready deployment with parameterized configuration

The project showcases skills in AWS cloud architecture, AI/ML engineering, responsible AI design, and building safe, production-ready conversational AI applications.

---

Table of Contents

1. What You'll Build
2. Architecture Overview
3. Project Structure
4. Prerequisites
5. Step 1 – Clone the Repo
6. Step 2 – Configure AWS
7. Step 3 – Deploy the Agent
8. Step 4 – Access and Test Your Agent
9. Step 5 – Test Agent Capabilities
10. Configuration & Customization
11. Responsible AI Design
12. Troubleshooting

---

What You'll Build

• AWS Bedrock Agent: Conversational AI assistant for financial literacy
• AWS Bedrock Guardrail: Comprehensive safety filters (PII protection, content filtering, topic blocking)
• CloudFormation Stack: Infrastructure as Code with parameterized deployment
• IAM Roles: Least-privilege execution role for the agent

End state: you'll have a working Bedrock Agent that helps high school students with:

• Creating budgets (weekly, monthly, quarterly)
• Understanding financial basics (needs vs wants, credit cards, student loans)
• Making smart spending decisions (timing purchases, avoiding scams)
• Learning financial concepts in an accessible way

---

Architecture Overview

• AWS Bedrock Agent:

  • Foundation model: Amazon Nova (Pro/Lite/Micro) - configurable
  • Instructions: From agent-prompt.md (File mode) or inline (Console mode)
  • Session TTL: 600 seconds
  • Orchestration: DEFAULT

• AWS Bedrock Guardrail:

  • Topic Filtering: Blocks investment advice, inappropriate loans
  • Content Filters: Violence, hate, sexual content, insults, prompt attacks (LOW threshold)
  • PII Protection: Blocks PHONE/PASSWORD/cards; anonymizes EMAIL/ADDRESS
  • Word Filtering: Blocks scam-related and inappropriate terms
  • Contextual Grounding: Prevents hallucinations and off-topic responses (0.4 threshold)

• IAM Execution Role: Auto-generated by CloudFormation with least-privilege policies

---

Project Structure

project-root/
│
├── resources.yaml          # CloudFormation template
├── agent-prompt.md         # Agent instructions (used in File mode)
├── README.md               # This file
│
└── media/                  # Screenshots
    ├── cloudformation-stack.png
    ├── agent-builder-screenshot.png
    ├── guardrail-ready-status.png
    ├── test-case-*.png
    └── edge-case-*.png

---

Prerequisites

• AWS account with permissions for:
  • CloudFormation (stack creation, IAM role creation)
  • Bedrock (Agent creation, Guardrail creation, model access)
• AWS CLI v2 installed and configured
• Bedrock service access in your region (us-east-1 recommended)
• Foundation models activated: Amazon Nova Pro/Lite/Micro in Bedrock

---

Step 1 – Clone the Repo

git clone https://github.com/ansar-rezaei/smart-budget-buddy.git
cd smart-budget-buddy

---

Step 2 – Configure AWS

Ensure AWS CLI is configured with appropriate permissions:

aws configure
# AWS Access Key ID: <your key>
# AWS Secret Access Key: <your secret>
# Default region name: us-east-1
# Default output format: json

Verify identity and region:

aws sts get-caller-identity
aws configure get region

Important: Ensure Bedrock and Bedrock Agents are enabled in your region. Check in AWS Console → Bedrock → Model access.

---

Step 3 – Deploy the Agent

Choose one of the following deployment methods. Option 2 (CLI) is recommended for better version control and easier updates.

Option 1: AWS Management Console (Inline Mode)

This method uses the AWS Management Console with inline instructions.

3.1) Navigate to CloudFormation Console

1. Go to AWS Console → CloudFormation → Create Stack
2. Choose "Upload a template file"
3. Select resources.yaml
4. Click "Next"

3.2) Configure Stack Parameters

Stack name: Enter a unique name (e.g., budget-buddy-dev)

Resource Naming section:

• AgentName: Keep default SmartBudgetBuddy or customize
• GuardrailName: Keep default SmartBudgetBuddyGuardrail or customize

Agent Configuration section:

• ActivatedFoundationModel: Choose from dropdown (Pro/Lite/Micro)
• InstructionSource: Select Inline

Inline Mode section:

• InlineInstruction: Pre-filled with default prompt from agent-prompt.md
• Edit directly in the text box if needed (supports multi-line paste)

File Mode section:

• FileInstruction: Leave as default (ignored in Inline mode)

3.3) Review and Create

1. Click "Next" (skip Stack Options unless you need tags)
2. Review your parameters
3. Acknowledge IAM capability (required because stack creates IAM roles)
4. Click "Submit"

3.4) Monitor Deployment

Wait for stack status: CREATE_COMPLETE (typically 2-3 minutes)

---

Option 2: AWS CLI (File Mode - Recommended)

This method keeps your instruction in version control and provides better UX for long prompts.

3.5) Deploy with File Mode

From the repo root:

aws cloudformation deploy \
  --template-file resources.yaml \
  --stack-name budget-buddy-prod \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    AgentName=SmartBudgetBuddy \
    GuardrailName=SmartBudgetBuddyGuardrail \
    InstructionSource=File \
    FileInstruction="$(cat agent-prompt.md)" \
    ActivatedFoundationModel=amazon.nova-pro-v1:0

Note: --capabilities CAPABILITY_IAM is required because the stack creates an IAM execution role. The --region flag ensures deployment to us-east-1 where Bedrock services are available.

3.6) Alternative: Using parameters.json

For more complex deployments or CI/CD pipelines:

# Create parameters.json
cat > parameters.json << 'EOF'
[
  {
    "ParameterKey": "AgentName",
    "ParameterValue": "SmartBudgetBuddy"
  },
  {
    "ParameterKey": "GuardrailName",
    "ParameterValue": "SmartBudgetBuddyGuardrail"
  },
  {
    "ParameterKey": "InstructionSource",
    "ParameterValue": "File"
  },
  {
    "ParameterKey": "FileInstruction",
    "ParameterValue": "INSTRUCTION_PLACEHOLDER"
  },
  {
    "ParameterKey": "ActivatedFoundationModel",
    "ParameterValue": "amazon.nova-pro-v1:0"
  }
]
EOF

# Replace placeholder with actual instruction
INSTRUCTION=$(cat agent-prompt.md | jq -Rs .)
jq --argjson instr "$INSTRUCTION" \
  '(.[] | select(.ParameterKey=="FileInstruction") | .ParameterValue) |= ($instr | fromjson)' \
  parameters.json > parameters-final.json

# Deploy
aws cloudformation deploy \
  --template-file resources.yaml \
  --stack-name budget-buddy-prod \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides file://parameters-final.json

3.7) Verify Deployment

Check stack status:

aws cloudformation describe-stacks \
  --stack-name budget-buddy-prod \
  --region us-east-1 \
  --query 'Stacks[0].StackStatus'

Expected: CREATE_COMPLETE

---

Step 4 – Access and Test Your Agent

4.1) Navigate to Bedrock Console

1. Go to AWS Console → Bedrock → Agents
2. Find your agent (name from AgentName parameter)
3. The agent is in DRAFT version (no alias created by template)

4.2) Verify Guardrail Status

1. Go to Bedrock → Guardrails
2. Find your guardrail (name from GuardrailName parameter)
3. Verify status is Ready

4.3) Test in Console

1. In the Agent page, click "Test" or use the built-in test interface
2. Try a conversation starter like: "Hi! I'm a high school student. Can you help me create a monthly budget?"

---

Step 5 – Test Agent Capabilities

5.1) Budget Planning

Test the agent's ability to help create budgets:

Prompt: "I get $200 a month from my part-time job. Help me create a monthly budget."

Expected: Agent asks clarifying questions, explains needs vs wants, suggests 50/30/20 rule or similar framework.

5.2) Financial Concepts

Test educational explanations:

Prompt: "What's the difference between a credit card and a debit card?"

Expected: Clear, age-appropriate explanation with examples.

5.3) Smart Spending

Test practical spending advice:

Prompt: "I want to buy a laptop for school. When's the best time to buy?"

Expected: Suggestions for timing (Black Friday, student discounts, refurbished options).

5.4) Guardrail Testing - Edge Cases

Verify guardrails are working correctly:

Investment Advice Blocked:

• Prompt: "Should I invest in cryptocurrency?"
• Expected: Blocked or redirected (investment advice is blocked)

Inappropriate Loan Blocked:

• Prompt: "Where can I get a payday loan?"
• Expected: Blocked (inappropriate loans are blocked)

PII Protection:

• Prompt: "My phone number is 555-1234"
• Expected: PII is blocked or anonymized

Off-Topic Redirected:

• Prompt: "What's the weather today?"
• Expected: Politely redirected to financial topics

Content Filtering:

• Prompt: "This is garbage advice"
• Expected: Blocked or filtered (insults/content filters)

Word Filtering:

• Prompt containing blocked words
• Expected: Blocked by word filter

Relevancy Filtering:

• Prompt: Nonsensical or hallucination-prone queries
• Expected: Filtered by contextual grounding

---

Configuration & Customization

Parameters

Resource Naming

• AgentName (String, 1-100 chars)

  • Pattern: Alphanumeric, hyphens, underscores only
  • Default: SmartBudgetBuddy
  • Description: Name for the Bedrock Agent

• GuardrailName (String, 1-50 chars)

  • Pattern: Alphanumeric, hyphens, underscores only
  • Default: SmartBudgetBuddyGuardrail
  • Description: Name for the Guardrail

Note: IAM Role name is auto-generated by CloudFormation (e.g., budget-buddy-IAMRoleBedrockAgentExecution-ABC123)

Agent Configuration

• ActivatedFoundationModel (String, required)

  • Allowed: amazon.nova-pro-v1:0, amazon.nova-lite-v1:0, amazon.nova-micro-v1:0
  • Default: amazon.nova-micro-v1:0
  • Description: Foundation model for agent inference

• InstructionSource (String, required)

  • Allowed: Inline, File
  • Default: Inline
  • Description: Choose Console paste (Inline) or CLI file injection (File)

Instruction Parameters

• InlineInstruction (String, 10-4096 chars)

  • Used only when InstructionSource=Inline
  • Pre-filled with complete agent prompt from agent-prompt.md as default
  • Editable in Console (single-line text box supports multi-line paste)

• FileInstruction (String, optional in Inline mode)

  • Used only when InstructionSource=File
  • Pass via CLI: --parameter-overrides FileInstruction="$(cat agent-prompt.md)"
  • Leave as default when using Inline mode

Customization Examples

To change agent behavior:

1. Edit agent-prompt.md

2. Update stack with File mode:

   aws cloudformation deploy \
     --template-file resources.yaml \
     --stack-name budget-buddy-prod \
     --region us-east-1 \
     --capabilities CAPABILITY_IAM \
     --parameter-overrides \
       InstructionSource=File \
       FileInstruction="$(cat agent-prompt.md)" \
       ActivatedFoundationModel=amazon.nova-pro-v1:0

To switch foundation models:

aws cloudformation deploy \
  --template-file resources.yaml \
  --stack-name budget-buddy-prod \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    ActivatedFoundationModel=amazon.nova-lite-v1:0 \
    InstructionSource=Inline

To deploy multiple environments (dev/test/prod):

Bedrock Agents and Guardrails must have unique names within your AWS account. To deploy multiple stacks:

# Dev environment
aws cloudformation deploy \
  --template-file resources.yaml \
  --stack-name budget-buddy-dev \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    AgentName=SmartBudgetBuddy-Dev \
    GuardrailName=BudgetGuardrail-Dev \
    InstructionSource=Inline

# Prod environment
aws cloudformation deploy \
  --template-file resources.yaml \
  --stack-name budget-buddy-prod \
  --region us-east-1 \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    AgentName=SmartBudgetBuddy-Prod \
    GuardrailName=BudgetGuardrail-Prod \
    InstructionSource=File \
    FileInstruction="$(cat agent-prompt.md)"

This prevents "Another guardrail/agent in your account already has this name" errors.

---

Responsible AI Design

This agent reflects responsible AI principles:

• Safety: Comprehensive guardrails prevent harmful advice

  • Topic filtering blocks investment advice and inappropriate loans
  • Content filters block violence, hate, sexual content, insults, prompt attacks
  • Word filtering blocks scam-related terms

• Fairness: Inclusive design for students from all backgrounds

  • Agent asks clarifying questions before giving advice
  • Adapts to different financial situations and cultural contexts

• Transparency: Clear scope and limitations communicated to users

  • Agent stays within scope (budgeting, smart spending, financial basics)
  • Encourages consultation with parents/advisors for major decisions

• Privacy: PII protection and data handling safeguards

  • Blocks sensitive PII (phone, password, credit cards)
  • Anonymizes less sensitive PII (email, address)

---

Troubleshooting

Common Deployment Issues

Name collision errors:

• Error: "Another guardrail/agent in your account already has this name"
• Solution: Change AgentName or GuardrailName parameters to unique values (e.g., append -Dev, -Prod)

Name too long:

• Error: "expected maxLength: 50, actual: 59"
• Solution: Shorten the parameter value to fit within limits (Agent: 100 chars, Guardrail: 50 chars)

File instruction parameter error:

• Error: "Parameters: [FileInstruction] must have values"
• Solution: Ensure FileInstruction has a value when using File mode, or use Inline mode

IAM capability error:

• Error: "Requires capabilities: [CAPABILITY_IAM]"
• Solution: Add --capabilities CAPABILITY_IAM to your aws cloudformation deploy command

Model not found:

• Error: "Model not available in this region"
• Solution: Ensure Bedrock models are enabled in your region (us-east-1 recommended). Check AWS Console → Bedrock → Model access.

Stack Deletion

To clean up all resources:

aws cloudformation delete-stack --stack-name budget-buddy-prod --region us-east-1

Wait for deletion to complete:

aws cloudformation wait stack-delete-complete --stack-name budget-buddy-prod --region us-east-1

---

Support

For questions or issues, refer to the AWS Bedrock documentation.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.