Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
389 lines (277 loc) · 14.7 KB

DEPLOYMENT.md

File metadata and controls

389 lines (277 loc) · 14.7 KB
Raw

Deployment Guide

This guide walks you through deploying AgentCore Deep Research to AWS.

Prerequisites

Before deploying, ensure you have:

  • Node.js 20+ installed (see AWS guide for installing Node.js on EC2)
  • AWS CLI configured with credentials (aws configure) - see AWS CLI Configuration guide
  • AWS CDK CLI installed: npm install -g aws-cdk (see CDK Getting Started guide)
  • Python 3.10+ - required for deployment scripts
  • uv - Python package manager used for running scripts: curl -LsSf https://astral.sh/uv/install.sh | sh (see uv installation guide)
  • Docker - Required for all deployments. See Install Docker Engine. Verify with docker ps. Alternatively, Finch can be used on Mac. See below if you have a non-ARM machine.
  • An AWS account with sufficient permissions to create:
    • S3 buckets
    • CloudFront distributions
    • Cognito User Pools
    • Amplify Hosting projects
    • Bedrock AgentCore resources
    • IAM roles and policies

Configuration

1. Create Your Configuration File

The deployment configuration lives in infra-cdk/config.yaml. This file is gitignored (it may contain API keys and personal settings). Start by copying the example:

cp infra-cdk/.config_example.yaml infra-cdk/config.yaml

Then edit infra-cdk/config.yaml to customize your deployment:

stack_name_base: your-project-name  # Change this to your preferred stack name (max 35 chars)
region: null  # AWS region to deploy the stack (e.g., us-west-2). If null, uses your AWS CLI default region.

# Optional: List of Cognito user emails to create automatically. Each user
# receives a temporary password by email on first deployment.
# If empty, you'll need to manually create users via AWS Console.
user_emails:
  # - user@example.com

auto_deploy_frontend: true # Automatically deploy frontend after CDK deploy (when using npm run deploy)

backend:
  pattern: strands-deep-research
  deployment_type: docker # Available deployment types: docker (default), zip
  model_id: bedrock-model-id # Model ID for the agent (with cross-region prefix)

# Research tools configuration
# enabled: whether the tool is deployed and available (true/false)
# default_on: whether the tool is toggled on by default in the UI (true/false)
# required: fields that must be non-null for the tool to work
tools:
  alphavantage: # Commodity prices, economic indicators, and market news
    enabled: true
    default_on: false
    required:
      api_key: null # Get your key from https://www.alphavantage.co/
   ...

Important:

  • Change stack_name_base to a unique name for your project to avoid conflicts
  • Maximum length is 35 characters (due to AWS AgentCore runtime naming constraints)
  • Set region to deploy to a specific AWS region (e.g., us-west-2). If left as null, the deployment uses your AWS CLI default region
  • If config.yaml is not found, the deployment will fall back to .config_example.yaml defaults

2. API Keys and Data Sources

Some research tools require external API keys obtained through free registration. Others use public APIs or your AWS account directly. The table below summarizes what is needed for each tool:

Tool External API? API Key Required? Registration Needed? Provider
AlphaVantage ✅ Yes ✅ Yes Yes — sign up for API key alphavantage.co
ArXiv Search ✅ Yes ❌ No No arxiv.org
Bedrock Knowledge Base ❌ No (AWS) ❌ No (needs KB ID) No AWS
ClinicalTrials.gov Search ✅ Yes ❌ No No clinicaltrials.gov
FRED Economic Search ✅ Yes ✅ Yes Yes — sign up for API key fredaccount.stlouisfed.org
Nova Web Grounding ❌ No (AWS) ❌ No No AWS
OpenFDA Drug Search ✅ Yes ❌ No No open.fda.gov
PubMed Search ✅ Yes ❌ No No pubmed.ncbi.nlm.nih.gov
S3 File Reader ❌ No (AWS) ❌ No No AWS
SEC EDGAR Search ✅ Yes ❌ No No efts.sec.gov
Tavily Web Search ✅ Yes ✅ Yes Yes — sign up for API key tavily.com

For tools that require API keys, register at the links above, then add your keys to infra-cdk/config.yaml. The CDK deployment automatically stores these keys in AWS Secrets Manager. If you leave a key as null, the corresponding tool will deploy but fail at runtime when invoked.

Deployment Types

AgentCore Deep Research supports two deployment types for AgentCore Runtime. Set deployment_type in infra-cdk/config.yaml:

Type Description
docker (default) Builds container image, pushes to ECR
zip Packages code via Lambda, uploads to S3

Note: Docker is required for both deployment types. The zip option only affects how the agent runtime is packaged. Other Lambda functions in the stack still use Docker for dependency bundling.

Use Docker (default) when:

  • You need native C/C++ libraries without ARM64 wheels on PyPI
  • Your deployment package exceeds 250 MB
  • You need custom OS-level dependencies
  • You want maximum compatibility

Use ZIP when:

  • You want faster iteration during development
  • Your dependencies are pure Python or have ARM64 wheels available
  • You need higher session throughput

ZIP packaging includes: The patterns/ and gateway/ directories are bundled together with dependencies from requirements.txt. This matches the COPY commands in the Docker deployment's Dockerfile.

Deployment Steps

TL;DR version

Here are the commands to deploy backend and frontend:

cd infra-cdk
cp .config_example.yaml config.yaml  # Create your config (edit as needed)
npm install
cdk bootstrap # Once ever
npm run deploy

This runs cdk deploy and then automatically deploys the frontend if auto_deploy_frontend: true is set in config.yaml (enabled by default). To deploy them separately:

cdk deploy                    # Backend only
npm run deploy:frontend       # Frontend only

1. Install Dependencies

Install infrastructure dependencies:

cd infra-cdk
npm install

Note: Frontend dependencies are automatically installed during deployment via Docker bundling, so no separate frontend npm install is required.

2. Bootstrap CDK (First Time Only)

If this is your first time using CDK in this AWS account/region:

cdk bootstrap

3. Deploy backend and frontend

Build and deploy the complete stack:

npm run deploy

This will:

  1. Run cdk deploy to provision the backend (Cognito, AgentCore runtime, Gateway tools, etc.)
  2. If auto_deploy_frontend: true in config.yaml, automatically deploy the frontend to Amplify Hosting

The frontend deployment generates aws-exports.json from CDK stack outputs (including tool configuration), builds the React app, and uploads it to Amplify.

Note: The deployment takes approximately 5-10 minutes due to container building and AgentCore setup.

You will see the URL for the application in the script's output, which will look similar to this:

ℹ App URL: https://main.d123abc456def7.amplifyapp.com

To deploy backend or frontend independently:

cdk deploy                    # Backend only
npm run deploy:frontend       # Frontend only

4. Create a Cognito User (if necessary)

If you provided user_emails in config:

  • Each listed user receives an email with a temporary password
  • Sign in and change password on first login

If you didn't provide any emails:

  1. Go to the AWS Cognito Console
  2. Find your User Pool (named {stack_name_base}-user-pool)
  3. Click on the User Pool
  4. Go to "Users" tab
  5. Click "Create user"
  6. Fill in the user details:
    • Email: Your email address
    • Temporary password: Create a temporary password
    • Mark email as verified: Check this box
  7. Click "Create user"

5. Access the Application

  1. Open the Amplify Hosting URL in your browser
  2. Sign in with the Cognito user you created
  3. You'll be prompted to change your temporary password on first login

Post-Deployment

Updating the Application

To update both backend and frontend:

cd infra-cdk
npm run deploy

To update only the frontend (e.g., after changing tool flags in config.yaml):

cd infra-cdk
npm run deploy:frontend

To update only the backend:

cd infra-cdk
cdk deploy

Monitoring and Logs

  • Frontend logs: Check CloudFront access logs
  • Backend logs: Check CloudWatch logs for the AgentCore runtime
  • Build logs: Check CodeBuild project logs for container builds

Cleanup

To remove all resources:

cd infra-cdk
cdk destroy --force

Warning: This will delete all data including S3 buckets created during deployment and ECR images.

Troubleshooting

Common Issues

  1. cdk deploy fails with Docker errors

    • Ensure Docker is installed and the daemon is running: docker ps
    • On Mac, open Docker Desktop or start Finch: finch vm start
    • On Linux: sudo systemctl start docker

  2. "Architecture incompatible" or "exec format error" during Docker build

    • This occurs when deploying from a non-ARM machine without cross-platform build setup
    • Follow the "Docker Cross-Platform Build Setup" instructions in the Prerequisites section
    • Ensure you've installed QEMU emulation: docker run --privileged --rm tonistiigi/binfmt --install all
    • Verify ARM64 support: docker buildx ls should show linux/arm64 in platforms

  3. "Agent Runtime ARN not configured"

    • Ensure the backend stack deployed successfully
    • Check that SSM parameters were created correctly

  4. Authentication errors

    • Verify you created a Cognito user
    • Check that the user's email is verified

  5. Build failures

    • Check CodeBuild logs in the AWS Console
    • Ensure your agent code in patterns/ is valid

  6. Permission errors

    • Verify your AWS credentials have sufficient permissions
    • Check IAM roles created by the stack

Getting Help

  • Check CloudWatch logs for detailed error messages
  • Review the CDK deployment output for any warnings
  • Ensure all prerequisites are met

Security Considerations

  • The Cognito User Pool is configured with strong password policies
  • All communication uses HTTPS via CloudFront
  • AgentCore runtime uses JWT authentication
  • IAM roles follow least-privilege principles

For production deployments, consider:

  • Enabling MFA on Cognito users
  • Setting up custom domains with your own certificates
  • Configuring additional monitoring and alerting
  • Implementing backup strategies for any persistent data

Docker Cross-Platform Build Setup (Required for non-ARM machines)

Important: BedrockAgentCore Runtime only supports ARM64 architecture. If you're deploying from a non-ARM machine (x86_64/amd64), you need to enable Docker's cross-platform building capabilities.

Check your machine architecture:

uname -m

If the output is x86_64 (not aarch64 or arm64), run these commands:

  1. Install QEMU for ARM64 emulation:

    docker run --privileged --rm tonistiigi/binfmt --install all

  2. Enable Docker buildx and create a multi-platform builder:

    docker buildx create --use --name multiarch --driver docker-container
docker buildx inspect --bootstrap

  3. Verify ARM64 support is available:

    docker buildx ls

    You should see linux/arm64 in the platforms list.

Note: This setup is only required once per machine. The CDK deployment will automatically use these capabilities to build ARM64 containers.

Understanding aws-exports.json

The aws-exports.json file is a critical configuration file that enables the React frontend to communicate with AWS Cognito for authentication. This file is automatically generated during frontend deployment and contains the necessary configuration parameters for Cognito authentication.

What is aws-exports.json?

The aws-exports.json file contains authentication and tool configuration that the React application reads at runtime. It's created automatically by the frontend deployment script and placed in frontend/public/aws-exports.json.

Why is it necessary?

This configuration file is essential because:

  • It provides the React application with the correct Cognito User Pool and Client IDs
  • It specifies the authentication endpoints and redirect URIs
  • It configures the authentication flow parameters
  • It includes tool configuration (which tools are enabled and toggled on by default in the UI)
  • Without this file, Cognito authentication will not work and tool toggles will fall back to defaults

How is it created?

The file is automatically generated by deploy-frontend.py which:

  1. Extracts configuration from your deployed CDK stack outputs
  2. Automatically detects the AWS region from the CloudFormation stack ARN
  3. Retrieves the required values: CognitoClientId, CognitoUserPoolId, and AmplifyUrl
  4. Generates the configuration file with the following structure:
{
  "authority": "https://cognito-idp.region.amazonaws.com/user-pool-id",
  "client_id": "your-client-id",
  "redirect_uri": "https://your-amplify-url",
  "post_logout_redirect_uri": "https://your-amplify-url",
  "response_type": "code",
  "scope": "email openid profile",
  "automaticSilentRenew": true,
  "agentRuntimeArn": "arn:aws:bedrock-agentcore:region:account:runtime/runtime-id",
  "awsRegion": "us-east-1",
  "feedbackApiUrl": "https://your-api-gateway-url",
  "agentPattern": "strands-deep-research",
  "tools": {
    "tavily": { "enabled": true, "default_on": true },
    "nova": { "enabled": true, "default_on": true }
  }
}

Important: You should not manually edit this file as it's regenerated on each deployment. If authentication isn't working or tool toggles aren't reflecting your config.yaml changes, redeploy the frontend with npm run deploy:frontend (or use npm run deploy to deploy everything).

Note: config.yaml is gitignored because it may contain API keys and personal settings. The tracked .config_example.yaml provides safe defaults. If config.yaml is missing during deployment, the system will automatically fall back to .config_example.yaml and print a warning.