Create Docker & AgentCore Deployment Guide

[aarora79]

Parent Issue: #195

Objective

Create comprehensive Docker containerization and AgentCore deployment guide for Travel Assistant and Flight Booking agents.

Implementation References

• AgentCore Deployment: https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/02-use-cases/SRE-agent
• Strands Agent Architecture: https://github.com/aarora79/amazon-bedrock-agentcore-samples/tree/feature/demo1-simple-dual-observability/01-tutorials/06-AgentCore-observability/07-simple-dual-observability

Phase 1: Docker Containerization

Dockerfile Template (for both agents)

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy agent code
COPY src/ /app/src/

# Create SQLite directory
RUN mkdir -p /app/data

# Expose port
EXPOSE 8001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD python -c "import requests; requests.get('http://localhost:8001/api/health')"

# Run agent
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8001"]

requirements.txt

fastapi==0.104.0
uvicorn==0.24.0
pydantic==2.5.0
sqlite3==3.44.0
aiohttp==3.9.0
python-dotenv==1.0.0

Docker Build Script

#!/bin/bash
set -e

AGENT_NAME="${1:-travel-assistant}"
AGENT_VERSION="${2:-1.0.0}"
REGISTRY="${3:-localhost:5000}"

echo "Building Docker image for $AGENT_NAME v$AGENT_VERSION"

docker build \
  -t "$REGISTRY/$AGENT_NAME:$AGENT_VERSION" \
  -t "$REGISTRY/$AGENT_NAME:latest" \
  -f Dockerfile \
  .

docker push "$REGISTRY/$AGENT_NAME:$AGENT_VERSION"
docker push "$REGISTRY/$AGENT_NAME:latest"

echo "Successfully built and pushed: $REGISTRY/$AGENT_NAME:$AGENT_VERSION"

docker-compose.yml (for local testing)

version: '3.8'

services:
  travel-assistant:
    image: localhost:5000/travel-assistant:latest
    ports:
      - "8001:8001"
    environment:
      - REGISTRY_URL=http://registry:5000
      - LOG_LEVEL=INFO
    volumes:
      - ./data/travel-assistant:/app/data
    depends_on:
      - registry
    networks:
      - agents

  flight-booking:
    image: localhost:5000/flight-booking:latest
    ports:
      - "8002:8002"
    environment:
      - REGISTRY_URL=http://registry:5000
      - LOG_LEVEL=INFO
    volumes:
      - ./data/flight-booking:/app/data
    depends_on:
      - registry
    networks:
      - agents

  registry:
    image: mcp-gateway-registry:latest
    ports:
      - "5000:5000"
    volumes:
      - ./registry-data:/app/registry/agents
    networks:
      - agents

networks:
  agents:
    driver: bridge

Phase 2: AgentCore Deployment

AgentCore Agent Configuration

{
  "name": "Travel Assistant Agent",
  "version": "1.0.0",
  "description": "Plans trips and searches flights",
  "image": "registry.example.com/travel-assistant:latest",
  "port": 8001,
  "env": {
    "REGISTRY_URL": "http://registry:5000",
    "LOG_LEVEL": "INFO",
    "MAX_WORKERS": "4"
  },
  "resources": {
    "cpu": "500m",
    "memory": "512Mi"
  },
  "health_check": {
    "path": "/api/health",
    "interval": "30s",
    "timeout": "10s",
    "retries": 3
  },
  "readiness_probe": {
    "path": "/api/ready",
    "initial_delay": "5s"
  },
  "registration": {
    "registry_url": "http://registry:5000/api/v0.1/agents",
    "tags": ["travel", "planning", "flights"],
    "ttl": "3600s"
  }
}

AgentCore Deployment Script

#!/bin/bash
set -e

AGENT_NAME="$1"
IMAGE="$2"
PORT="$3"
REGISTRY_URL="${4:-http://registry:5000}"

echo "Deploying $AGENT_NAME to AgentCore"

# Create AgentCore deployment
agentcore deploy \
  --name "$AGENT_NAME" \
  --image "$IMAGE" \
  --port "$PORT" \
  --registry-url "$REGISTRY_URL" \
  --health-check-path /api/health \
  --log-level INFO

# Verify deployment
echo "Waiting for agent to be ready..."
sleep 5

agentcore status "$AGENT_NAME"

echo "Successfully deployed: $AGENT_NAME"

Phase 3: Local Testing with Docker Compose

Setup Steps

# 1. Build agent images
./scripts/build-agents.sh

# 2. Start services
docker-compose up -d

# 3. Verify services are running
docker-compose ps

# 4. Check agent health
curl http://localhost:8001/api/health
curl http://localhost:8002/api/health

# 5. Verify agent registration
curl http://localhost:5000/api/v0.1/agents

# 6. Test agent-to-agent communication
curl -X POST http://localhost:8001/api/search-flights \
  -H "Content-Type: application/json" \
  -d '{"from": "SF", "to": "NY", "date": "2025-11-15"}'

Monitoring and Logs

# View agent logs
docker-compose logs -f travel-assistant
docker-compose logs -f flight-booking

# Monitor resource usage
docker stats travel-assistant flight-booking

# Check container health
docker inspect --format='{{json .State.Health}}' travel-assistant

Phase 4: Production Deployment on AgentCore

Prerequisites

• AgentCore cluster running
• Container registry configured
• Service mesh (optional, for observability)

Deployment Steps

# 1. Build and push images to registry
docker build -t registry.example.com/travel-assistant:1.0.0 .
docker push registry.example.com/travel-assistant:1.0.0

# 2. Deploy agents to AgentCore
agentcore deploy -f travel-assistant-config.json
agentcore deploy -f flight-booking-config.json

# 3. Verify deployments
agentcore list agents

# 4. Check inter-agent communication
agentcore logs travel-assistant -f

# 5. Perform smoke tests
agentcore test travel-assistant --endpoint http://travel-assistant:8001

Environment Variables

Travel Assistant Agent

REGISTRY_URL=http://registry:5000
LOG_LEVEL=INFO
PORT=8001
MAX_WORKERS=4
BOOKING_AGENT_TIMEOUT=30
BOOKING_AGENT_RETRIES=3

Flight Booking Agent

REGISTRY_URL=http://registry:5000
LOG_LEVEL=INFO
PORT=8002
DB_PATH=/app/data/flights.db
MAX_CONCURRENT_RESERVATIONS=10
PAYMENT_TIMEOUT=15

Container Configuration Best Practices

Resource Limits

resources:
  limits:
    cpu: "1000m"
    memory: "1Gi"
  requests:
    cpu: "500m"
    memory: "512Mi"

Security

security_context:
  run_as_non_root: true
  run_as_user: 1000
  read_only_root_filesystem: true

Networking

networks:
  - agents  # Internal service mesh
ports:
  - "8001:8001"  # API port only, not exposed externally

Persistence

Data Volumes

• Agent data persisted in /app/data/
• SQLite databases backed by named volumes
• Volume mounts survive container restarts

Database Initialization

# Initialize schema on first run
python -m src.db init --db-path /app/data/flights.db

# Load seed data
python -m src.db load-seed-data --db-path /app/data/flights.db

Troubleshooting

Agent won't start

# Check logs
docker logs travel-assistant

# Verify image exists
docker images | grep travel-assistant

# Test manually
docker run -it travel-assistant:latest /bin/bash

Agent can't reach registry

# Verify network connectivity
docker exec travel-assistant curl http://registry:5000/api/health

# Check environment variables
docker inspect travel-assistant | grep -A 10 Env

Agent registration fails

# Check registry logs
docker logs registry

# Verify agent is running
curl http://localhost:8001/api/health

# Manual registration
curl -X POST http://localhost:5000/api/v0.1/agents \
  -H "Content-Type: application/json" \
  -d @agent-config.json

Acceptance Criteria

• Dockerfile created for both agents
• docker-compose.yml configured for local testing
• Build scripts automate image creation
• AgentCore deployment configs created
• Local testing passes with Docker Compose
• Deployment scripts tested end-to-end
• Monitoring and health checks working
• Documentation complete with examples