Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
120 lines (92 loc) · 3.19 KB

DEVELOPMENT.md

File metadata and controls

120 lines (92 loc) · 3.19 KB

Development Guide

Docker-Based Development Workflow

This project uses Docker for both local development and deployment to ensure consistency across environments.

Quick Start

Local Development with Docker

# Build and run locally with Docker
npm start

# This will:
# 1. Build the Docker image with your local bedrock-agentcore package
# 2. Run the container on port 8080

Local Development without Docker

# Run directly with Node.js (for faster iteration)
npm run dev

# Test the agent
npm run invoke

Deploy to AWS

# Deploy with your runtime ID and TypeScript SDK path
npm run deploy -- my-agent-service-XXXXXXXXXX ./bedrock-agentcore-sdk-typescript-private

# Example
npm run deploy -- my-agent-service-abc123def456 ./private-bedrock-agentcore-sdk-typescript-staging

Project Structure

├── src/
│   ├── index.ts          # Main agent handler
│   └── invoke.ts         # Test script for deployed agent
├── Dockerfile            # Docker configuration
├── build-docker.sh       # Docker build script
├── deploy.sh            # AWS deployment script
└── package.json         # Dependencies and scripts

Available Scripts

  • npm start - Build Docker image and run locally
  • npm run dev - Run locally without Docker (faster for development)
  • npm run build - Compile TypeScript
  • npm run invoke - Test the deployed agent
  • npm run deploy - Deploy to AWS (interactive)
  • npm run lint - Check code style
  • npm run format - Format code

Docker Configuration

The project uses a local bedrock-agentcore package via npm link. The Docker setup handles this by:

  1. package.json: Uses file:../bedrock-agentcore-sdk-typescript-private dependency
  2. Dockerfile: Copies the local package during build
  3. build-docker.sh: Handles path configuration via environment variables

Custom bedrock-agentcore Path

Ppass it to deploy script:

./deploy.sh my-runtime-id /custom/path

Testing

Local Testing

# Start the service
npm start

# In another terminal, test with curl
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -H "x-amzn-bedrock-agentcore-runtime-session-id: test-123" \
  -d '"What is 5 plus 3?"'

AWS Testing

# Test deployed agent
npm run invoke

Prerequisites

  • Docker Desktop - For containerized development
  • AWS CLI - Configured with appropriate permissions
  • Node.js 20+ - For local development
  • bedrock-agentcore TypeScript SDK - Must be copied into the same directory as the Dockerfile

Required AWS Resources

  • ECR repository (created automatically by deploy script)
  • IAM role BedrockAgentCoreRuntimeRole
  • Agent runtime deployed with known runtime ID

Troubleshooting

Docker Build Issues

  • Ensure bedrock-agentcore path exists
  • Check Docker Desktop is running
  • Verify npm link is working locally

Deployment Issues

  • Verify AWS CLI credentials
  • Check IAM role exists
  • Ensure runtime ID is correct

Local Development Issues

  • Run npm install to ensure dependencies
  • Check TypeScript compilation with npm run build
  • Verify bedrock-agentcore package is properly linked