AWS AgentCore Workshop - Returns & Refunds Agent

A comprehensive workshop demonstrating how to build a production-ready AI agent using AWS Bedrock AgentCore with Memory, Gateway, and Knowledge Base integration.

Overview

This project showcases a complete returns and refunds customer service agent that demonstrates:

• AgentCore Memory: Persistent customer preferences and conversation history
• AgentCore Gateway: Secure MCP-based tool integration with Lambda functions
• Knowledge Base: RAG-based access to policy documents
• Custom Tools: Business logic for return eligibility and refund calculations
• Production Deployment: Full deployment to AgentCore Runtime with observability

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AgentCore Runtime                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Returns Agent                           │  │
│  │  - Claude Sonnet 4.5                                 │  │
│  │  - Custom Tools (eligibility, refunds, formatting)   │  │
│  │  - Memory Integration                                │  │
│  │  - Gateway Integration                               │  │
│  │  - Knowledge Base Integration                        │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
           │              │              │
           ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │  Memory  │   │ Gateway  │   │    KB    │
    │          │   │          │   │          │
    │ Semantic │   │   MCP    │   │  Policy  │
    │Preferences│  │ Lambda   │   │   Docs   │
    │ Summary  │   │  OAuth   │   │          │
    └──────────┘   └──────────┘   └──────────┘

Repository Structure

.
├── chat_with_agent.py              # Interactive CLI chat interface
├── HOW_TO_USE_AGENT.md            # Detailed usage guide
├── ui/                            # Web interface
│   ├── app.py                     # Flask application
│   ├── templates/
│   │   └── index.html            # Chat UI
│   ├── requirements.txt          # UI dependencies
│   ├── RUN_UI.sh                 # Startup script
│   └── README.md                 # UI documentation
├── 01_returns_refunds_agent.py    # Phase 1: Basic agent
├── 02_test_agent.py
├── 03_create_memory.py            # Phase 2: Memory integration
├── 04_seed_memory.py
├── 05_test_memory.py
├── 06_memory_enabled_agent.py
├── 07_test_memory_agent.py
├── 08_create_cognito.py           # Phase 3: Gateway setup
├── 09_create_gateway_role.py
├── 10_create_lambda.py
├── 11_create_gateway.py
├── 12_add_lambda_to_gateway.py
├── 13_list_gateway_targets.py
├── 14_full_agent.py               # Phase 4: Full integration
├── 15_test_full_agent.py
├── 16_create_runtime_role.py      # Phase 5: Production deployment
├── 17_runtime_agent.py
├── 19_deploy_agent.py
├── 20_check_status.py
├── 21_invoke_agent.py
├── 22_get_dashboard.py
├── 23_get_logs_info.py
├── 24_cleanup_aws.py              # Phase 6: Cleanup
├── 25_cleanup_files.py
├── requirements.txt               # Python dependencies
├── Dockerfile                     # Runtime container
├── .bedrock_agentcore.yaml       # Runtime configuration
└── README.md                      # This file

Workshop Steps

Phase 1: Basic Agent (Scripts 01-02)

• 01_returns_refunds_agent.py - Create basic agent with custom tools
• 02_test_agent.py - Test the basic agent locally

Phase 2: Memory Integration (Scripts 03-07)

• 03_create_memory.py - Create AgentCore Memory with 3 strategies
• 04_seed_memory.py - Seed with sample customer conversations
• 05_test_memory.py - Test memory retrieval
• 06_memory_enabled_agent.py - Agent with Memory + KB integration
• 07_test_memory_agent.py - Test memory-enabled agent

Phase 3: Gateway Setup (Scripts 08-13)

• 08_create_cognito.py - Set up OAuth authentication
• 09_create_gateway_role.py - Create IAM role for Gateway
• 10_create_lambda.py - Create order lookup Lambda function
• 11_create_gateway.py - Create AgentCore Gateway
• 12_add_lambda_to_gateway.py - Add Lambda as Gateway target
• 13_list_gateway_targets.py - Verify Gateway configuration

Phase 4: Full Integration (Scripts 14-15)

• 14_full_agent.py - Agent with Memory + Gateway + KB
• 15_test_full_agent.py - Test full integration locally

Phase 5: Production Deployment (Scripts 16-23)

• 16_create_runtime_role.py - Create IAM role for Runtime
• 17_runtime_agent.py - Runtime-ready agent code
• 19_deploy_agent.py - Deploy to AgentCore Runtime
• 20_check_status.py - Monitor deployment status
• 21_invoke_agent.py - Invoke deployed agent
• 22_get_dashboard.py - Get observability dashboard
• 23_get_logs_info.py - Get CloudWatch logs information

Phase 6: Cleanup (Scripts 24-25)

• 24_cleanup_aws.py - Delete all AWS resources
• 25_cleanup_files.py - Delete all generated files

Prerequisites

• AWS Account with appropriate permissions
• Python 3.9+
• AWS CLI configured
• Bedrock model access (Claude Sonnet 4.5)

Installation

# Install dependencies
pip install -r requirements.txt

# Configure AWS credentials
aws configure

Usage

Interact with the Deployed Agent

Once deployed (after running scripts 01-21), you have three ways to interact with your agent:

1. Interactive CLI Chat (Recommended)

python3 chat_with_agent.py

Features:

• Real-time interactive chat in your terminal
• Color-coded messages for better readability
• Commands: exit, quit, clear, help, status
• No server needed - direct connection to deployed agent

2. Web Interface

cd ui
bash RUN_UI.sh

Then open in your browser:

• http://localhost:5001

Features:

• Beautiful chat interface
• Session management with unique user IDs
• Easy to share and demonstrate
• Perfect for presentations

3. Single Test Query

python3 21_invoke_agent.py

Runs a predefined test query with detailed verification results.

See HOW_TO_USE_AGENT.md for detailed usage instructions.

---

Run the Complete Workshop

Execute scripts in order (01-23) to build and deploy the complete agent:

# Phase 1: Basic Agent
python3 01_returns_refunds_agent.py
python3 02_test_agent.py

# Phase 2: Memory Integration
python3 03_create_memory.py
python3 04_seed_memory.py
python3 05_test_memory.py
python3 06_memory_enabled_agent.py
python3 07_test_memory_agent.py

# Phase 3: Gateway Setup
python3 08_create_cognito.py
python3 09_create_gateway_role.py
python3 10_create_lambda.py
python3 11_create_gateway.py
python3 12_add_lambda_to_gateway.py
python3 13_list_gateway_targets.py

# Phase 4: Full Integration
python3 14_full_agent.py
python3 15_test_full_agent.py

# Phase 5: Production Deployment
python3 16_create_runtime_role.py
python3 19_deploy_agent.py
python3 20_check_status.py
python3 21_invoke_agent.py
python3 22_get_dashboard.py
python3 23_get_logs_info.py

Cleanup

# Delete AWS resources
python3 24_cleanup_aws.py

# Delete generated files
python3 25_cleanup_files.py

Key Features

Interactive Interfaces

CLI Chat (chat_with_agent.py)

• Real-time interactive terminal chat
• Color-coded output for better readability
• Session management with unique actor IDs
• Built-in commands: exit, quit, clear, help, status
• Direct connection to deployed agent (no server needed)

Web UI (ui/)

• Modern, responsive chat interface
• Built with Flask and vanilla JavaScript
• Session persistence across page reloads
• Runs on port 5001 (configurable)
• Easy to share and demonstrate

Both interfaces use the same Runtime class to connect to your deployed agent, ensuring consistent behavior.

AgentCore Memory

• Semantic Memory: Stores factual information about customer interactions
• User Preferences: Captures customer preferences (e.g., email notifications)
• Summary Memory: Maintains conversation context and summaries

AgentCore Gateway

• MCP Protocol: Model Context Protocol for tool integration
• OAuth 2.0: Secure authentication with Cognito
• Lambda Integration: Serverless function execution

Custom Tools

• check_return_eligibility: Validates return eligibility based on purchase date
• calculate_refund_amount: Calculates refund amounts with restocking fees
• format_policy_response: Formats policy information for customers

Knowledge Base

• RAG-based retrieval of Amazon return policies
• Semantic search across policy documents
• Accurate, grounded responses

Configuration Files

Configuration files are generated during execution and stored as JSON:

• memory_config.json - Memory resource ID
• gateway_config.json - Gateway ID and URL
• cognito_config.json - OAuth credentials
• lambda_config.json - Lambda function details
• runtime_config.json - Deployed agent ARN

Note: These files contain sensitive information and are excluded from git via .gitignore

Observability

CloudWatch Dashboard

Access the GenAI Observability dashboard for:

• Request traces and latency
• Tool invocation metrics
• Memory operations
• Error analysis

CloudWatch Logs

View agent logs with:

aws logs tail /aws/bedrock-agentcore/runtimes/<agent-id>-DEFAULT --follow

Architecture Decisions

Why AgentCore Memory?

• Persistent customer context across sessions
• Automatic extraction of preferences and facts
• Semantic search for relevant memories

Why AgentCore Gateway?

• Secure, authenticated tool access
• MCP protocol for standardized integration
• OAuth 2.0 for enterprise security

Why AgentCore Runtime?

• Zero infrastructure management
• Auto-scaling and high availability
• Built-in observability and monitoring

Cost Considerations

• Bedrock Models: Pay per token (input/output)
• AgentCore Memory: Pay per storage and retrieval
• AgentCore Gateway: Pay per request
• AgentCore Runtime: Pay per request and compute time
• Lambda: Pay per invocation and duration
• Cognito: Free tier available, then pay per MAU

Security

• IAM roles with least-privilege permissions
• OAuth 2.0 authentication for Gateway
• Secrets stored in AWS Secrets Manager
• VPC isolation (optional)

Troubleshooting

Common Issues

Memory not retrieving data

• Check memory_id in configuration
• Verify actor_id matches between seed and retrieval
• Allow 20-30 seconds for memory processing

Gateway authentication failures

• Verify Cognito client credentials
• Check discovery URL format (use IDP domain)
• Ensure OAuth scopes are configured

Runtime deployment failures

• Check IAM role permissions
• Verify requirements.txt includes all dependencies
• Review CloudWatch logs for errors

Contributing

This is a workshop project. Feel free to:

• Extend with additional tools
• Add more memory strategies
• Integrate additional AWS services
• Improve error handling

License

MIT License - See LICENSE file for details

Resources

• AWS Bedrock AgentCore Documentation
• Strands Agents Framework
• Model Context Protocol (MCP)

Support

For issues or questions:

• Check CloudWatch logs for errors
• Review configuration files for correctness
• Consult AWS Bedrock documentation
• Open an issue in this repository