AgentCore Runtime versioning and endpoints

Understanding agent runtime Versioning

Each agent runtime in Amazon Bedrock AgentCore is automatically versioned:

• When you create an agent runtime, AgentCore Runtime automatically creates version 1 (V1)

• Each update to the agent runtime creates a new version with a complete, self-contained configuration

• Versions are immutable once created

• Each version contains all the configuration needed for execution

How endpoints reference versions

Endpoints provide a way to reference specific versions of your agent runtime:

• The "DEFAULT" endpoint automatically points to the latest version of your agent runtime

• Endpoints can point to specific versions, allowing you to maintain different environments (e.g., development, staging, production)

• When you update an agent runtime, the "DEFAULT" endpoint is automatically updated to point to the new version

• Endpoints must be explicitly updated to point to new versions

Example Updating an endpoint to a New Version

bedrock_agentcore_client = boto3.client('bedrock-agentcore', region_name='us-west-2')

response = bedrock_agentcore_client.update_agent_runtime_endpoint(
    agentRuntimeId='agent-runtime-12345',
    endpointName='production-endpoint',
    agentRuntimeVersion='v2.1',
    description='Updated production endpoint'
)

print(response)
            

Versioning scenarios

The following table illustrates how versioning and endpoints interact during the lifecycle of an agent runtime:

Agent Runtime Versioning Scenarios

Change Type	Version Creation Behavior	Latest Version	Endpoint Behavior
Initial Creation	Creates Version 1 (V1) automatically	V1	DEFAULT points to V1
Protocol Change	Creates a new version with updated protocol settings	V2	DEFAULT automatically updates to V2
Create "PROD" endpoint with V2	No new version created	V2	PROD endpoint points to V2
Container Image Update	Creates a new version with new container reference	V3	DEFAULT updates to V3, PROD remains on V2
Update "PROD" to V3	No new version created	V3	PROD updates to V3
Network Settings Modification	Creates a new version with updated security parameters	V4	DEFAULT updates to V4, PROD remains on V3

Endpoint lifecycle states

AgentCore Runtime endpoints go through various states during their lifecycle:

CREATING

Initial state when an endpoint is being created

CREATE_FAILED

Indicates creation failure due to permissions, container, or other issues

READY

Endpoint is ready to accept requests

UPDATING

Endpoint is being updated to a new version

UPDATE_FAILED

Indicates update operation failure

Listing AgentCore Runtime versions and endpoints

You can list all versions of an AgentCore Runtime by calling the ListAgentRuntimeVersions operation. To list the endpoints for an AgentCore Runtime, call ListAgentRuntimeEndpoints.