Vacation Planner — Enterprise Edition

AI-powered vacation planning built with CrewAI, Amazon Bedrock (Nova Pro), Amazon Bedrock AgentCore (Runtime, Gateway, Memory), DynamoDB, and Streamlit.

This repository is configuration-driven: no credentials or AWS resource IDs are hardcoded in application code. All secrets and endpoints are supplied via environment variables (.env locally, runtime env in Lambda/AgentCore, or AWS Secrets Manager in production).

---

Architecture

flowchart TB
    subgraph UI["Streamlit UI"]
        ST[streamlit_api.py]
    end

    subgraph AWS["AWS"]
        AC[AgentCore Runtime<br/>CrewAI + Bedrock]
        GW[AgentCore Gateway<br/>MCP]
        MEM[AgentCore Memory<br/>Short + Long term]
        DDB[(DynamoDB<br/>travel_packages)]
        COG[Cognito OAuth]
        L1[Lambda: travel packages]
        L2[Lambda: AgentCore proxy]
        APIGW[API Gateway HTTP]
        ECR[ECR Container]
    end

    ST -->|Direct invoke recommended| AC
    ST -.->|Optional, 29s timeout| APIGW --> L2 --> AC
    ST --> GW
    AC --> GW
    AC --> MEM
    GW --> COG
    GW --> L1 --> DDB
    ECR --> AC

| Component | Purpose | |-----------|---------| | AgentCore Runtime | Runs the CrewAI agent (Docker on ECR) | | AgentCore Gateway | Exposes DynamoDB lookup as MCP tool | | AgentCore Memory | Short-term events + long-term summarization | | DynamoDB | Curated travel packages (cost, duration, plan) | | Cognito | OAuth2 client-credentials for Gateway | | Streamlit | Web UI with memory explorer |

---

Prerequisites

• Python 3.10–3.13
• uv or pip
• AWS CLI v2 configured (aws configure or SSO)
• Docker Desktop (for AgentCore container build)
• Terraform >= 1.5 (for IaC deployment)
• IAM permissions for Bedrock, AgentCore, DynamoDB, Lambda, ECR, Cognito
• Bedrock model access: enable Amazon Nova Pro in your region (e.g. us-west-2)
• Serper API key: https://serper.dev (web search tool)

---

Quick Start (Local Development)

1. Clone and install

cd vacation_planner
pip install uv          # or: pip install -r requirements.txt
uv sync                 # or: pip install -e .

2. Configure environment

cp .env.example .env
# Edit .env — fill in all required values (see Configuration section)

3. Validate configuration

python scripts/validate-config.py streamlit
python scripts/validate-config.py memory-ui   # if using Agent Memory view

4. Run locally

Streamlit UI (production path — invokes AgentCore):

streamlit run streamlit_api.py

Crew only (no AWS invoke):

crewai run
# or
python src/vacation_planner/crew.py   # AgentCore runtime server on :8080

Test Gateway connectivity:

python gwtest.py Mumbai

---

Configuration

All settings are loaded from environment variables via src/vacation_planner/settings.py.

| Variable | Required | Description | |----------|----------|-------------| | AWS_DEFAULT_REGION | Yes | AWS region (e.g. us-west-2) | | AWS_ACCOUNT_ID | Recommended | Used by deploy scripts | | MODEL | Yes | LLM model id (default: bedrock/us.amazon.nova-pro-v1:0) | | SERPER_API_KEY | Yes | Serper.dev API key for web search | | GATEWAY_CLIENT_ID | Yes* | Cognito app client id | | GATEWAY_CLIENT_SECRET | Yes* | Cognito app client secret | | GATEWAY_TOKEN_URL | Yes* | Cognito token endpoint | | GATEWAY_URL | Yes* | AgentCore Gateway MCP URL | | MCP_PROTOCOL_VERSION | No | Default 2025-11-25 | | AGENT_RUNTIME_ARN | Yes** | AgentCore Runtime ARN | | AGENT_RUNTIME_QUALIFIER | No | Default DEFAULT | | AGENTCORE_MEMORY_ID | Yes*** | AgentCore Memory resource id | | AGENTCORE_MEMORY_STRATEGY_ID | Yes*** | Summarization strategy id | | AGENTCORE_MEMORY_ACTOR_ID | No | Default user | | TRAVEL_PACKAGES_TABLE | No | Default travel_packages | | USE_DIRECT_AGENTCORE | No | Default true (avoids API GW 29s timeout) | | API_URL | If not direct | API Gateway vacation planner endpoint |

* Required for DynamoDB package lookup via Gateway
** Required for Streamlit / Lambda proxy
*** Required for memory features

Copy .env.example as a checklist. Never commit .env to git.

---

Deployment Guide

Deployment is split into Terraform-managed resources and AgentCore console/CLI steps (AgentCore Runtime, Gateway, and Memory are not fully available in Terraform today).

Phase 1 — Terraform (foundation)

Provisions: DynamoDB (+ sample data), ECR, Cognito, Lambdas, API Gateway.

cd infra/terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars — set cognito_domain_prefix (globally unique)

terraform init
terraform plan
terraform apply

After apply, sync outputs to .env:

chmod +x ../../scripts/sync-env-from-terraform.sh
../../scripts/sync-env-from-terraform.sh >> ../../.env

Or inspect outputs manually:

terraform output ecr_repository_url
terraform output cognito_client_id
terraform output api_vacation_planner_endpoint
terraform output -raw cognito_client_secret

Phase 2 — Build and push AgentCore container

export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export AWS_DEFAULT_REGION=us-west-2
export ECR_REPOSITORY_NAME=vacation-planner-agentcore

chmod +x scripts/build-and-push-ecr.sh
./scripts/build-and-push-ecr.sh

First ARM64 build can take 20–30 minutes.

Phase 3 — AgentCore Runtime (manual / console)

1. Open Amazon Bedrock → AgentCore → Runtimes
2. Create runtime from ECR image (<account>.dkr.ecr.<region>.amazonaws.com/vacation-planner-agentcore:latest)
3. Set runtime environment variables (same as .env — especially SERPER_API_KEY, Gateway vars, AGENTCORE_MEMORY_ID)
4. Attach IAM role with: bedrock:InvokeModel, bedrock-agentcore:* (memory), CloudWatch logs
5. Copy Runtime ARN → set AGENT_RUNTIME_ARN in .env and re-run Terraform if using Lambda proxy:

cd infra/terraform
terraform apply -var='agent_runtime_arn=arn:aws:bedrock-agentcore:...'

1. Test:

curl http://localhost:8080/ping   # local
# or invoke via AWS CLI / console with payload: {"topic": "Paris"}

Phase 4 — AgentCore Gateway (manual / console)

1. Create Gateway in AgentCore console
2. Add Lambda target → select vacation-planner-dev-travel-packages (Terraform-created)
3. Configure Cognito OAuth using Terraform outputs (GATEWAY_CLIENT_ID, GATEWAY_CLIENT_SECRET, GATEWAY_TOKEN_URL)
4. Copy Gateway MCP URL → GATEWAY_URL in .env
5. Verify: python gwtest.py Mumbai

Phase 5 — AgentCore Memory (manual / console)

1. Create Memory resource in AgentCore console
2. Enable summarization strategy for long-term extraction
3. Set AGENTCORE_MEMORY_ID and AGENTCORE_MEMORY_STRATEGY_ID in .env and Runtime env

Phase 6 — Streamlit UI

Run locally (requires AWS credentials with bedrock-agentcore:InvokeAgentRuntime):

streamlit run streamlit_api.py

For production hosting, deploy Streamlit to ECS Fargate, App Runner, or EC2 with:

• IAM role (not static keys)
• .env replaced by task definition environment or Secrets Manager
• USE_DIRECT_AGENTCORE=true (recommended)

---

Project Structure

vacation_planner/
├── .env.example                 # Configuration template
├── src/vacation_planner/
│   ├── settings.py              # Central config loader
│   ├── crew.py                  # CrewAI + AgentCore entrypoint
│   ├── main.py                  # CLI entrypoints
│   └── config/
│       ├── agents.yaml
│       └── tasks.yaml
├── streamlit_api.py             # Production UI (AgentCore + Memory)
├── streamlitui.py               # Local-only UI
├── lambda_function.py           # API Gateway → AgentCore proxy
├── dynamodb_lambda_function.py  # Gateway target → DynamoDB
├── gwtest.py                    # Gateway smoke test
├── Dockerfile                   # AgentCore Runtime image
├── infra/terraform/             # IaC (DynamoDB, Lambda, Cognito, ECR, API GW)
└── scripts/
    ├── validate-config.py
    ├── build-and-push-ecr.sh
    └── sync-env-from-terraform.sh

---

Security Best Practices

• Store secrets in AWS Secrets Manager or SSM Parameter Store for production
• Rotate Cognito client secrets and Serper keys periodically
• Use IAM roles (not access keys) for Lambda, AgentCore Runtime, and Streamlit on AWS
• Restrict API Gateway with JWT authorizer or AWS WAF if exposing publicly
• Enable ECR image scanning (enabled in Terraform)
• Use Terraform remote state (S3 + DynamoDB lock) for team deployments — see commented block in infra/terraform/versions.tf
• Remove sample DynamoDB seed data in production (seed_sample_packages = false)

---

Enterprise Gaps & Recommended Next Steps

The repo is structured for enterprise use, but you may still want:

| Area | Status | Recommendation | |------|--------|----------------| | AgentCore Runtime/Gateway/Memory | Manual console steps | Automate when AWS Terraform/CDK resources mature; use deployment runbooks meanwhile | | CI/CD pipeline | Not included | Add GitHub Actions / CodePipeline: lint → test → terraform plan → ECR push | | Multi-environment | Single environment var | Separate terraform.tfvars per dev/staging/prod + remote state per env | | Secrets management | .env for local | Wire Secrets Manager → Lambda/ECS/AgentCore Runtime env at deploy time | | Streamlit auth | Open UI | Add Cognito Hosted UI, ALB OIDC, or CloudFront + Lambda@Edge | | API Gateway timeout | 29s hard limit | Keep USE_DIRECT_AGENTCORE=true; or use async pattern (SQS + polling UI) | | Monitoring | OTEL in Dockerfile | Add CloudWatch dashboards, alarms on Lambda errors, AgentCore latency | | Cost controls | Not included | AWS Budgets, Bedrock usage quotas, DynamoDB on-demand caps | | Automated tests | Minimal | Add unit tests for settings, gateway parsing, memory formatters | | DR / backup | Not included | DynamoDB PITR, cross-region ECR replication for prod | | Network isolation | Public Lambdas | Optional VPC endpoints for Bedrock/DynamoDB in regulated environments | | Compliance | Not included | CloudTrail, Config rules, data retention policies for memory events |

---

Troubleshooting

| Issue | Fix | |-------|-----| | Missing required environment variable | Run python scripts/validate-config.py full | | API Gateway 504 | Use USE_DIRECT_AGENTCORE=true | | Gateway auth failed | Verify Cognito client credentials and token URL | | MCP protocol error | Set MCP_PROTOCOL_VERSION=2025-11-25 | | No travel tool on gateway | Register DynamoDB Lambda as Gateway target | | Memory empty in UI | Plan a vacation first; long-term summaries are async | | Docker ARM64 build slow | Expected on first build; use docker buildx cache |

---

License & Support

Built with CrewAI and Amazon Bedrock AgentCore.

For CrewAI docs: https://docs.crewai.com