Amazon Bedrock AgentCore Deployment

Overview

Deploy AI agents to Amazon Bedrock AgentCore using multiple approaches: starter toolkit for rapid deployment, direct code deployment for customization, and container deployment for complex dependencies. Includes CI/CD patterns and infrastructure as code.

Purpose: Deploy agents from development to production with best practices

Pattern: Workflow-based (4 deployment methods)

Key Principles (validated by AWS December 2025):

1. Zero Infrastructure - Managed compute, no servers to manage
2. arm64 Architecture - All deployments use arm64
3. Session Isolation - Complete isolation between sessions
4. Multiple Entry Points - SDK decorator or REST endpoints
5. Observability Built-in - CloudWatch and OTel integration
6. Framework Agnostic - Works with any Python agent framework

Quality Targets:

• Deployment time: < 5 minutes
• Cold start: < 2 seconds
• Package size: 250MB (zip), 750MB (unzipped)

---

When to Use

Use bedrock-agentcore-deployment when:

• Deploying agent code to production
• Setting up CI/CD pipelines for agents
• Migrating from development to production
• Managing multiple agent versions
• Implementing blue-green deployments

When NOT to Use:

• Local development/testing (use local server)
• Standard Bedrock Agents with action groups

---

Prerequisites

Required

• AWS account with AgentCore access
• Python 3.10+ (recommended: 3.13)
• IAM role with AgentCore permissions
• Foundation model access enabled

Recommended

• AWS CLI configured
• Docker (for container deployments)
• GitHub Actions or GitLab CI (for CI/CD)

---

Deployment Method 1: Starter Toolkit (Fastest)

Time: 2-5 minutes Complexity: Low Best For: Rapid deployment, simple agents

Step 1: Install Toolkit

pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

# Verify
agentcore --help

Step 2: Create Agent

# main.py
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent(model="anthropic.claude-sonnet-4-20250514-v1:0")

@app.entrypoint
def invoke(payload):
    prompt = payload.get("prompt", "Hello!")
    result = agent(prompt)
    return {"response": result.message}

if __name__ == "__main__":
    app.run()

Step 3: Configure

# Initialize configuration
agentcore configure -e main.py -n my-production-agent

# This creates .bedrock_agentcore.yaml

Step 4: Test Locally

# Start local server
python main.py &

# Test
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, world!"}'

# Stop local server
pkill -f main.py

Step 5: Deploy

# Deploy to AWS
agentcore deploy

# Output: Agent ARN
# arn:aws:bedrock-agentcore:us-east-1:123456789012:agent-runtime/my-production-agent

Step 6: Test Deployed

# Test via CLI
agentcore invoke '{"prompt": "Hello from production!"}'

# Test via boto3
python -c "
import boto3
client = boto3.client('bedrock-agentcore')
response = client.invoke_agent_runtime(
    agentRuntimeArn='arn:...',
    runtimeSessionId='test-1',
    payload={'prompt': 'Hello!'}
)
print(response['payload'])
"

---

Deployment Method 2: Direct Code Deploy

Time: 10-15 minutes Complexity: Medium Best For: Custom dependencies, specific configurations

Step 1: Project Structure

my-agent/
├── main.py              # Entry point
├── agent/
│   ├── __init__.py
│   └── logic.py         # Agent logic
├── pyproject.toml       # Dependencies
└── requirements.txt     # Alternative deps format

Step 2: Create Entry Point

# main.py - REST endpoint pattern
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/invocations', methods=['POST'])
def invoke():
    payload = request.get_json()
    prompt = payload.get('prompt', '')

    # Your agent logic here
    from agent.logic import process_request
    result = process_request(prompt)

    return jsonify({'response': result})

@app.route('/ping', methods=['GET'])
def ping():
    return 'OK', 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

Step 3: Package for arm64

# Create virtual environment
uv init agent-deploy --python 3.13
cd agent-deploy

# Install dependencies for arm64
uv pip install \
    --python-platform aarch64-manylinux2014 \
    --python-version 3.13 \
    --target=deployment_package \
    --only-binary=:all: \
    -r requirements.txt

# Create ZIP
cd deployment_package
zip -r ../deployment_package.zip .
cd ..

# Add main.py
zip deployment_package.zip main.py

# Add agent module
zip -r deployment_package.zip agent/

Step 4: Upload to S3

aws s3 cp deployment_package.zip s3://my-bucket/agents/v1.0.0/package.zip

Step 5: Create Agent Runtime

import boto3

control = boto3.client('bedrock-agentcore-control')

response = control.create_agent_runtime(
    name='my-custom-agent',
    description='Production agent with custom dependencies',
    agentRuntimeArtifact={
        's3': {
            'uri': 's3://my-bucket/agents/v1.0.0/package.zip'
        }
    },
    roleArn='arn:aws:iam::123456789012:role/AgentCoreExecutionRole',
    pythonRuntime='PYTHON_3_13',
    entryPoint=['main.py'],
    environmentVariables={
        'LOG_LEVEL': 'INFO',
        'CUSTOM_CONFIG': 'production'
    }
)

agent_arn = response['agentRuntimeArn']
print(f"Deployed: {agent_arn}")

---

Deployment Method 3: Container Deploy

Time: 15-30 minutes Complexity: High Best For: Complex dependencies, custom runtimes, large packages

Step 1: Create Dockerfile

# Dockerfile
FROM public.ecr.aws/lambda/python:3.13-arm64

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

# Copy agent code
COPY main.py .
COPY agent/ agent/

# Set entry point
ENV PORT=8080
EXPOSE 8080

CMD ["main.py"]

Step 2: Build Image

# Login to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Build for arm64
docker buildx build \
  --platform linux/arm64 \
  -t 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:v1.0.0 \
  --push .

Step 3: Create Agent Runtime

response = control.create_agent_runtime(
    name='my-container-agent',
    description='Agent deployed via container',
    agentRuntimeArtifact={
        'container': {
            'imageUri': '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:v1.0.0'
        }
    },
    roleArn='arn:aws:iam::123456789012:role/AgentCoreExecutionRole'
)

---

Deployment Method 4: Infrastructure as Code (Terraform)

Time: 20-30 minutes setup, then automated Complexity: High Best For: Production environments, team deployments

Terraform Configuration

# main.tf

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

# IAM Role for Agent
resource "aws_iam_role" "agentcore_execution" {
  name = "agentcore-execution-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action = "sts:AssumeRole"
      Effect = "Allow"
      Principal = {
        Service = "bedrock-agentcore.amazonaws.com"
      }
    }]
  })
}

resource "aws_iam_role_policy" "agentcore_policy" {
  name = "agentcore-policy"
  role = aws_iam_role.agentcore_execution.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "bedrock:InvokeModel",
          "bedrock:InvokeModelWithResponseStream"
        ]
        Resource = "arn:aws:bedrock:*::foundation-model/*"
      },
      {
        Effect = "Allow"
        Action = [
          "logs:CreateLogGroup",
          "logs:CreateLogStream",
          "logs:PutLogEvents"
        ]
        Resource = "*"
      },
      {
        Effect = "Allow"
        Action = [
          "s3:GetObject"
        ]
        Resource = "${aws_s3_bucket.agent_artifacts.arn}/*"
      }
    ]
  })
}

# S3 Bucket for Agent Artifacts
resource "aws_s3_bucket" "agent_artifacts" {
  bucket = "my-agentcore-artifacts-${data.aws_caller_identity.current.account_id}"
}

# Upload agent package
resource "aws_s3_object" "agent_package" {
  bucket = aws_s3_bucket.agent_artifacts.id
  key    = "agents/${var.agent_version}/package.zip"
  source = "${path.module}/deployment_package.zip"
  etag   = filemd5("${path.module}/deployment_package.zip")
}

# Note: AgentCore resources may require custom provider or AWS CLI
# Use null_resource with local-exec as workaround

resource "null_resource" "create_agent_runtime" {
  triggers = {
    package_etag = aws_s3_object.agent_package.etag
  }

  provisioner "local-exec" {
    command = <<-EOT
      aws bedrock-agentcore-control create-agent-runtime \
        --name ${var.agent_name} \
        --description "Terraform-managed agent" \
        --agent-runtime-artifact '{"s3":{"uri":"s3://${aws_s3_bucket.agent_artifacts.id}/agents/${var.agent_version}/package.zip"}}' \
        --role-arn ${aws_iam_role.agentcore_execution.arn} \
        --python-runtime PYTHON_3_13 \
        --entry-point '["main.py"]'
    EOT
  }

  depends_on = [aws_s3_object.agent_package]
}

data "aws_caller_identity" "current" {}

variable "agent_name" {
  default = "my-production-agent"
}

variable "agent_version" {
  default = "1.0.0"
}

---

CI/CD Pipeline: GitHub Actions

# .github/workflows/deploy-agent.yml
name: Deploy AgentCore Agent

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  AWS_REGION: us-east-1
  AGENT_NAME: my-production-agent

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest

      - name: Run tests
        run: pytest tests/

      - name: Test local server
        run: |
          python main.py &
          sleep 5
          curl -f http://localhost:8080/ping
          curl -X POST http://localhost:8080/invocations \
            -H "Content-Type: application/json" \
            -d '{"prompt": "test"}'
          pkill -f main.py

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/GitHubActionsRole
          aws-region: ${{ env.AWS_REGION }}

      - name: Install AgentCore toolkit
        run: pip install bedrock-agentcore-starter-toolkit

      - name: Configure agent
        run: agentcore configure -e main.py -n ${{ env.AGENT_NAME }}

      - name: Deploy agent
        run: agentcore deploy

      - name: Verify deployment
        run: |
          agentcore invoke '{"prompt": "Health check"}'

---

CI/CD Pipeline: GitLab CI

# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  AWS_REGION: us-east-1
  AGENT_NAME: my-production-agent

test:
  stage: test
  image: python:3.13
  script:
    - pip install -r requirements.txt
    - pip install pytest
    - pytest tests/

build:
  stage: build
  image: python:3.13
  script:
    - pip install uv
    - uv pip install --python-platform aarch64-manylinux2014 --python-version 3.13 --target=deployment_package --only-binary=:all: -r requirements.txt
    - cd deployment_package && zip -r ../package.zip . && cd ..
    - zip package.zip main.py
  artifacts:
    paths:
      - package.zip

deploy:
  stage: deploy
  image: amazon/aws-cli
  script:
    - aws s3 cp package.zip s3://${ARTIFACT_BUCKET}/agents/${CI_COMMIT_SHA}/package.zip
    - |
      aws bedrock-agentcore-control update-agent-runtime \
        --agent-runtime-id ${AGENT_RUNTIME_ID} \
        --agent-runtime-artifact "{\"s3\":{\"uri\":\"s3://${ARTIFACT_BUCKET}/agents/${CI_COMMIT_SHA}/package.zip\"}}"
  only:
    - main

---

Version Management

Blue-Green Deployment

def blue_green_deploy(agent_name, new_version):
    """Deploy new version alongside old, then switch"""

    # Get current (blue) version
    blue = control.get_agent_runtime(name=f"{agent_name}-blue")

    # Deploy new (green) version
    green = control.create_agent_runtime(
        name=f"{agent_name}-green",
        agentRuntimeArtifact={'s3': {'uri': f's3://bucket/agents/{new_version}/package.zip'}},
        roleArn=blue['roleArn'],
        pythonRuntime='PYTHON_3_13',
        entryPoint=['main.py']
    )

    # Test green
    test_result = run_smoke_tests(green['agentRuntimeArn'])

    if test_result.passed:
        # Update endpoint to point to green
        control.update_agent_runtime_endpoint(
            endpointId='production-endpoint',
            agentRuntimeArn=green['agentRuntimeArn']
        )
        # Delete old blue
        control.delete_agent_runtime(name=f"{agent_name}-blue")
        # Rename green to blue
        # (Note: actual rename may require recreate)
    else:
        # Rollback - delete failed green
        control.delete_agent_runtime(name=f"{agent_name}-green")
        raise Exception("Green deployment failed tests")

Rollback

# Quick rollback via CLI
agentcore rollback --to-version v1.0.0

# Via boto3
control.update_agent_runtime(
    agentRuntimeId='runtime-xxx',
    agentRuntimeArtifact={
        's3': {'uri': 's3://bucket/agents/v1.0.0/package.zip'}
    }
)

---

Related Skills

• bedrock-agentcore: Core platform features
• bedrock-agentcore-evaluations: Pre-deployment testing
• terraform-aws: Infrastructure as code
• ecs-deployment: Alternative deployment patterns

---

References

• references/iam-policies.md - IAM policy templates
• references/troubleshooting.md - Common deployment issues
• references/performance-tuning.md - Optimization guide

---

Sources

• AgentCore Runtime Quickstart
• Direct Code Deploy
• AgentCore Starter Toolkit