Skip to content

GAIA Chatbot — Usage Guide

Deployed Resources

Once deployed, you should see the following in your AWS account:

Naming convention: <org>-<env>-<domain>-<module>-<resource>

SSM parameters: /<org>/<domain>/<module>/<resource-type>/<resource-name>/<attribute>

Resource Deployed Name / SSM Path Config Reference
Bedrock Knowledge Base <org>-dev-gaia-bedrock-builder-bedrock-knowledge-base
/<org>/gaia/bedrock-builder/knowledge-base/bedrock-knowledge-base/name		 knowledgeBases.bedrock-knowledge-base in config/bedrock-builder.yaml
OpenSearch Serverless Collection <org>-dev-gaia-bedrock-builder-knowledge-base-vector-store
/<org>/gaia/bedrock-builder/collection/knowledge-base-vector-store/name		 vectorStores.knowledge-base-vector-store in config/bedrock-builder.yaml
S3 Bucket <org>-dev-gaia-datalake-knowledge-base
/<org>/gaia/datalake/bucket/knowledge-base/name		 buckets.knowledge-base in config/datalake.yaml
CloudFront Distribution <org>-dev-gaia-gaia-chatbot
/<org>/gaia/gaia-chatbot/distribution/name		 configured in config/gaia.yaml
Cognito User Pool <org>-dev-gaia-gaia-chatbot
/<org>/gaia/gaia-chatbot/user-pool/name		 auth in config/gaia.yaml
IAM Role <org>-dev-gaia-roles-data-admin
/<org>/gaia/generated-role/data-admin/id		 generateRoles.data-admin in config/roles.yaml
IAM Role <org>-dev-gaia-roles-data-user
/<org>/gaia/generated-role/data-user/id		 generateRoles.data-user in config/roles.yaml

Post-Deployment Steps

After deployment:

  1. Upload documents to the knowledge base S3 bucket and sync in the Bedrock console.
  2. Get stack outputs (aws cloudformation describe-stacks) for Cognito and API configuration.
  3. Build a frontend that fetches /aws-exports.json from the CloudFront URL for auth and API config.

Frontend Development

To build a frontend that integrates with the deployed backend:

Configure MDAA for Local Development

Your gaia.yaml must include localhost in the OAuth URLs:

auth:
  cognitoDomain: "{{org}}-{{domain}}-{{env}}"
  cognitoAddAsIdentityProvider: true  # REQUIRED for email/password auth
  oAuthCallbackUrls:
    - http://localhost:5173
    - http://localhost:3000
  oAuthLogoutUrls:
    - http://localhost:5173
    - http://localhost:3000

Configure WAF (if enabled)

Add your IP addresses to the WAF allowlist. You need THREE types of IPs:

waf:
  allowedCidrs:
    # 1. Your IPv4 address (for browser requests)
    - 203.0.113.50/32           # curl -4 ifconfig.me
    # 2. Your IPv6 address (browsers may connect via IPv6)
    - 2001:db8:1234:5678::/64   # curl -6 ifconfig.me (use /64 prefix)
    # 3. NAT Gateway IP (REQUIRED for Lambda → AppSync responses)
    - 198.51.100.10/32          # aws ec2 describe-nat-gateways

Why IPv6? Many ISPs use dual-stack networking. Your browser may connect via IPv6 even if you only know your IPv4 address.

Why NAT Gateway IP? Lambda functions run in your VPC and send chat responses back through AppSync. These requests exit via the NAT Gateway, so WAF must allow that IP.

Fetch Configuration in Your Frontend

Your frontend should fetch /aws-exports.json from the CloudFront URL:

const config = await fetch('https://<cloudfront-url>/aws-exports.json').then(r => r.json());

// config contains:
// - Auth.Cognito.userPoolId
// - Auth.Cognito.userPoolClientId
// - API.Events.endpoint (WebSocket for chat)
  • AWS Amplify — Authentication and API integration
  • @aws-amplify/api-graphql — AppSync Events subscription for real-time chat
  • React Query / TanStack Query — REST API data fetching

AWS RAM Shared VPCs

If your VPC is shared via AWS RAM from a central network account:

  1. Add vpc_owner_account_id to your context in mdaa.yaml
  2. Reference it in gaia.yaml under vpc.vpcOwnerAccountId

This is needed because Lambda ENI creation requires the VPC ARN with the owning account ID. Without it, Lambda functions fail with authorization errors.

If your VPC is in the same account, remove vpcOwnerAccountId from gaia.yaml.

API Reference

WebSocket API (Real-time Chat)

Uses AWS AppSync Events for streaming chat responses.

Endpoint: Available in aws-exports.json as API.Events.endpoint

Flow: 1. Connect with Cognito token 2. Subscribe to chat/<session-id> channel 3. Publish messages to trigger AI responses 4. Receive streaming responses as events

REST API (Management Operations)

Base URL: https://<cloudfront-url>/api/v1

Authentication: Cognito JWT token in Authorization header.

Session Endpoints

Method Endpoint Description
GET /sessions List user's chat sessions
GET /sessions/<session_id> Get session with history
DELETE /sessions Delete all sessions
DELETE /sessions/<session_id> Delete specific session

Feedback Endpoints

Method Endpoint Description
POST /feedback Submit feedback
GET /feedback Get feedback history

Admin Endpoints

Method Endpoint Description
GET /admin/sessions List all sessions
GET /admin/feedback?start_date=...&end_date=... Get feedback in range

Bot Management Endpoints

Method Endpoint Description
GET /bot-management/health Health check
POST /bot-management/interruptions Activate interruption
DELETE /bot-management/interruptions/<type> Deactivate interruption

Service types: global, bedrock-rag, bedrock-invoke-model, bedrock-strands-agents

Authentication Flow

  1. Get Cognito configuration from aws-exports.json
  2. Authenticate via Cognito Hosted UI or SDK
  3. Include ID token in requests: Authorization: Bearer <id_token>

Configuration Reference

File Purpose
mdaa.yaml Main deployment config: region, org, VPC settings, resource tags
config/gaia.yaml Application config: auth, WAF, model selection
config/bedrock-builder.yaml Knowledge base and guardrails
config/roles.yaml IAM roles and policies
config/datalake.yaml S3 buckets and access policies