Agentcore Runtime

• Protocol Selection Guide
• Container Contract
• Deployment Workflow
• Agent Lifecycle Models
• Scaling
• Security Considerations

Protocol Selection Guide

AgentCore Runtime supports 4 protocols. You MUST select before building the container — each has a different contract.

Decision guide:

Refer to the latest AWS documentation on AgentCore Runtime protocols for current specifications.

Container Contract

Requirements that apply to ALL protocols:

See container build procedure for the full build workflow with Dockerfile examples.

Deployment Workflow

Constraints:

• You MUST select the protocol BEFORE building the container (Step 1 before Step 2)
• You MUST use ARM64 architecture — see container build procedure
• You MUST create the endpoint (Step 5) after the runtime (Step 4) — without an endpoint, the runtime cannot receive traffic
• You MUST verify health check passes after deployment
• For updates: use rolling update (default) or blue/green via alias switching
• For rollback: deploy previous container image version

Agent Lifecycle Models

Per-session agents use the Memory service for state persistence. See memory & observability.

Scaling

• Auto-scaling based on invocation count, latency, or custom metrics
• Configure min/max instances in Runtime configuration
• Cold start: first request to a new instance has higher latency
• For predictable high-volume: consider provisioned capacity
• Refer to the latest AWS documentation on AgentCore Runtime scaling for current configuration options

Security Considerations

IAM and access control:

• The --role-arn in create-agent-runtime defines what AWS resources the agent can access — scope to least-privilege permissions
• You MUST use IAM roles (not IAM users) for the runtime execution role
• Include aws:SourceArn and aws:SourceAccount conditions in the execution role trust policy to prevent confused deputy
• Separate runtime roles per agent — do not share a single role across multiple agents with different access needs

Network security:

• AgentCore terminates TLS at the load balancer — containers receive plaintext HTTP internally
• You MUST NOT expose container ports directly to the internet — all traffic must route through AgentCore
• Use VPC configuration in --network-configuration to restrict network access to required resources only
• You SHOULD use VPC mode ("networkMode":"VPC") for production workloads — PUBLIC mode exposes the endpoint to the internet and should only be used for development/testing in isolated accounts

Authentication:

• Configure --authorizer-configuration to require authentication for inbound requests
• You MUST NOT deploy production runtimes without an authorizer — unauthenticated endpoints are a security risk

Secrets and environment variables:

• You MUST NOT put secrets, API keys, or credentials in --environment-variables — these are visible in the runtime configuration via get-agent-runtime
• Use AWS Secrets Manager for secrets and reference them at runtime from your agent code
• Use --environment-variables only for non-sensitive configuration (feature flags, region overrides, log levels)

Logging and sensitive data:

• Agent runtimes log request and response payloads to CloudWatch automatically — these may contain PII
• You MUST encrypt the CloudWatch log group with a KMS key: configure kms-key-id on the /aws/bedrock-agentcore/runtimes/<agent-id> log group
• Configure CloudWatch Logs retention limits — do not retain logs indefinitely
• You MUST NOT log secrets or credentials in agent output

Monitoring:

• Enable CloudTrail for all bedrock-agentcore-control API calls to audit runtime creation, updates, and deletions

• Monitor runtime health via CloudWatch metrics — first discover the exact namespace (CloudWatch namespaces are case-sensitive):

  1. aws cloudwatch list-metrics --namespace "Bedrock-AgentCore" — if no results, try --namespace "Bedrock-Agentcore"
  2. Use the namespace that returns metrics in all subsequent alarm and query commands

• Configure alarms for error rates and latency degradation

• Refer to the latest AWS documentation on Bedrock AgentCore security best practices