Skip to content

README.md

Latest commit

 

History

History
295 lines (215 loc) · 7.66 KB

README.md

File metadata and controls

295 lines (215 loc) · 7.66 KB

Basic AgentCore Runtime - CDK

This CDK stack deploys a basic Amazon Bedrock AgentCore Runtime with a simple Strands agent. This is the simplest possible AgentCore deployment, perfect for getting started and understanding the core concepts without additional complexity.

Table of Contents

Overview

This CDK stack creates a minimal AgentCore deployment that includes:

  • AgentCore Runtime: Hosts a simple Strands agent
  • ECR Repository: Stores the Docker container image
  • IAM Roles: Provides necessary permissions
  • CodeBuild Project: Automatically builds the ARM64 Docker image
  • Lambda Functions: Custom resources for automation

This makes it ideal for:

  • Learning AgentCore basics
  • Quick prototyping
  • Understanding the core deployment pattern
  • Building a foundation before adding complexity

Architecture

Basic AgentCore Runtime Architecture

The architecture consists of:

  • User: Sends questions to the agent and receives responses
  • AWS CodeBuild: Builds the ARM64 Docker container image with the agent code
  • Amazon ECR Repository: Stores the container image
  • AgentCore Runtime: Hosts the Basic Agent container
    • Basic Agent: Simple Strands agent that processes user queries
    • Invokes Amazon Bedrock LLMs to generate responses
  • IAM Roles:
    • IAM role for CodeBuild (builds and pushes images)
    • IAM role for Agent Execution (runtime permissions)

Prerequisites

AWS Account Setup

  1. AWS Account: You need an active AWS account with appropriate permissions

  2. AWS CLI: Install and configure AWS CLI with your credentials

    aws configure

  3. Python 3.10+ and AWS CDK v2 installed

    # Install CDK
npm install -g aws-cdk

# Verify installation
cdk --version

  4. CDK version 2.220.0 or later (for BedrockAgentCore support)

  5. Bedrock Model Access: Enable access to Amazon Bedrock models in your AWS region

  6. Required Permissions: Your AWS user/role needs permissions for:

    • CloudFormation stack operations
    • ECR repository management
    • IAM role creation
    • Lambda function creation
    • CodeBuild project creation
    • BedrockAgentCore resource creation

Deployment

CDK vs CloudFormation

This is the CDK version of the basic AgentCore runtime. If you prefer CloudFormation, see the CloudFormation version.

Option 1: Quick Deploy (Recommended)

# Install dependencies
pip install -r requirements.txt

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy
cdk deploy

Option 2: Step by Step

# 1. Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Bootstrap CDK in your account/region (first time only)
cdk bootstrap

# 4. Synthesize the CloudFormation template (optional)
cdk synth

# 5. Deploy the stack
cdk deploy --require-approval never

# 6. Get outputs
cdk list

Deployment Time

  • Expected Duration: 8-12 minutes
  • Main Steps:
    • Stack creation: ~2 minutes
    • Docker image build (CodeBuild): ~5-8 minutes
    • Runtime provisioning: ~1-2 minutes

Testing

Using AWS CLI

# Get the Runtime ARN from CDK outputs
RUNTIME_ARN=$(aws cloudformation describe-stacks \
  --stack-name BasicAgentDemo \
  --region us-east-1 \
  --query 'Stacks[0].Outputs[?OutputKey==`AgentRuntimeArn`].OutputValue' \
  --output text)

# Invoke the agent
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn $RUNTIME_ARN \
  --qualifier DEFAULT \
  --payload $(echo '{"prompt": "Hello, how are you?"}' | base64) \
  response.json

# View the response
cat response.json

Using AWS Console

  1. Navigate to Bedrock AgentCore Console
  2. Go to "Runtimes" in the left navigation
  3. Find your runtime (name starts with BasicAgentDemo_)
  4. Click on the runtime name
  5. Click "Test" button
  6. Enter test payload: 
    {
  "prompt": "Hello, how are you?"
}
  7. Click "Invoke"

Sample Queries

Try these queries to test your basic agent:

  1. Simple Greeting:

    {"prompt": "Hello, how are you?"}

  2. Question Answering:

    {"prompt": "What is the capital of France?"}

  3. Creative Writing:

    {"prompt": "Write a short poem about clouds"}

  4. Problem Solving:

    {"prompt": "How do I bake a chocolate cake?"}

Cleanup

Using CDK (Recommended)

cdk destroy

Using AWS CLI

aws cloudformation delete-stack \
  --stack-name BasicAgentDemo \
  --region us-east-1

# Wait for deletion to complete
aws cloudformation wait stack-delete-complete \
  --stack-name BasicAgentDemo \
  --region us-east-1

Using AWS Console

  1. Navigate to CloudFormation Console
  2. Select the BasicAgentDemo stack
  3. Click "Delete"
  4. Confirm deletion

Cost Estimate

Monthly Cost Breakdown (us-east-1)

Service Usage Monthly Cost
AgentCore Runtime 1 runtime, minimal usage ~$5-10
ECR Repository 1 repository, <1GB storage ~$0.10
CodeBuild Occasional builds ~$1-2
Lambda Custom resource executions ~$0.01
CloudWatch Logs Agent logs ~$0.50
Bedrock Model Usage Pay per token Variable*

Estimated Total: ~$7-13/month (excluding Bedrock model usage)

*Bedrock costs depend on your usage patterns and chosen models. See Bedrock Pricing for details.

Cost Optimization Tips

  • Delete when not in use: Use cdk destroy to remove all resources
  • Monitor usage: Set up CloudWatch billing alarms
  • Choose efficient models: Select appropriate Bedrock models for your use case

Troubleshooting

CDK Bootstrap Required

If you see bootstrap errors:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION

Permission Issues

Ensure your IAM user/role has:

  • CDKToolkit permissions or equivalent
  • Permissions to create all resources in the stack
  • iam:PassRole for service roles

Python Dependencies

Install dependencies in the project directory:

pip install -r requirements.txt

Build Failures

Check CodeBuild logs in the AWS Console:

  1. Go to CodeBuild console
  2. Find the build project (name contains "basic-agent-build")
  3. Check build history and logs

Runtime Issues

If the runtime fails to start:

  1. Check CloudWatch logs for the runtime
  2. Verify the Docker image was built successfully
  3. Ensure IAM permissions are correct

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.