GenAI Foundation
This starter kit deploys an enterprise-ready Customer Support Agent on Amazon Bedrock AgentCore: an AgentCore Harness that answers from a Bedrock Knowledge Base and calls customer support tools through an AgentCore Gateway, with a Bedrock Guardrail and a multi-sync architecture for concurrent document processing.
Use Cases
- Customer support agent assistant with natural language interaction
- Knowledge base search and retrieval over internal documents
- Document processing and analysis with RAG (Retrieval Augmented Generation)
- Multi-modal content handling (text and images)
Capabilities
- AgentCore Harness agent with a managed agent loop, running in your VPC subnets
- AgentCore Gateway with AWS IAM auth, serving Lambda-backed customer support tools (over mock account and ticket data) and knowledge base search
- Knowledge Bases with vector stores for efficient retrieval, exposed to the agent as a gateway tool
- Guardrails for content safety
- Multi-sync architecture for concurrent file uploads
- KMS-encrypted S3 buckets for knowledge base data sources, and KMS-encrypted agent and gateway logs
- IAM roles with least-privilege Bedrock and AgentCore permissions
Architecture

Deployment
Prerequisites and Predeployment
- Authenticate to your target AWS account and region. Ensure the authenticated role has permissions to deploy resources via CDK.
- Bootstrap CDK in your target account and region.
- Choose a region where both the AgentCore harness and Bedrock Knowledge Bases are available. The harness is offered in fewer regions than the rest of AgentCore, so check its row in AgentCore supported Regions.
- Provision a VPC with three private subnets and a security group:
- The subnets must route outbound traffic through a NAT gateway. The agent harness and the vector store's password rotation function reach AWS services over it. For subnets without a NAT gateway, see Private VPC.
- Each subnet must be in an Availability Zone that AgentCore supports for VPC connectivity, or the harness fails to create.
- The security group must allow outbound HTTPS. The agent harness sessions use it.
- Choose the Bedrock models you set in
mdaa.yamlfrom the supported models, and make sure your account has access to them.
Additional info: PREDEPLOYMENT
Configure MDAA
-
Address all TODOs in
mdaa.yaml, specifically:- Set
organizationto a globally unique name (used in S3 bucket names and all resource prefixes) - Set
vpc_id,subnet_id_1,subnet_id_2,subnet_id_3to your VPC/subnet IDs - Set
security_group_idto the security group for the agent harness sessions - Set
llm_modelto the Bedrock model ID or inference profile ID the agent calls - Set
kb_embedding_modelandkb_parsing_model
- Set
-
Address all TODOs in module configs, specifically:
- CDK Nag suppressions in
roles.yaml. Uncomment each suppression only after reviewing the associated permissions and confirming they are acceptable for your environment.
- CDK Nag suppressions in
Deploy MDAA
Run the following from the starter kit directory (containing mdaa.yaml):
-
Optionally, run
npx @aws-mdaa/cli lsto understand what stacks will be deployed. -
Optionally, run
npx @aws-mdaa/cli synthand review the produced templates. -
Run
npx @aws-mdaa/cli deployto deploy all modules.
Additional info: DEPLOYMENT
Next Steps
See USAGE for post-deployment instructions including document upload and agent testing.
Modules Deployed
| Module | Purpose |
|---|---|
@aws-mdaa/roles |
IAM roles (data-admin, data-user, harness-execution, kb-execution, agent-lambda, kb-sync-lambda) |
@aws-mdaa/datalake |
KMS-encrypted S3 buckets for knowledge base data sources |
@aws-mdaa/bedrock-builder |
AgentCore Harness, AgentCore Gateway and its tools, Knowledge Base, and Guardrail |
Troubleshooting
-
Harness fails to create with a subnet or Availability Zone error: One of
subnet_id_1,subnet_id_2,subnet_id_3is in an Availability Zone AgentCore does not support. Check the subnets' Availability Zone IDs (aws ec2 describe-subnets --subnet-ids <id> --query "Subnets[].AvailabilityZoneId") against the supported list, and use subnets in supported zones. -
The agent never answers, or the invocation times out: The harness sessions cannot reach AWS. Check that the subnets route through a NAT gateway and that
security_group_idallows outbound HTTPS. For subnets without a NAT gateway, configure the Private VPC endpoints. -
Access Denied when calling Bedrock: Verify the
llm_modelin context values is correct and that model access is enabled. For cross-region inference, use the inference profile ID. -
Knowledge Base ingestion failures: Verify S3 bucket permissions and KMS key access. Check that documents are uploaded with proper encryption. Monitor CloudWatch logs for detailed error messages.
-
The agent answers without using its tools: Check the harness, gateway, and gateway target status in the Amazon Bedrock AgentCore console, and the support tools function's CloudWatch logs. A tool call that fails reaches the agent as a generic error, so the function's logs hold the details.