Amazon Bedrock Agent Versioning Complete Guide
This comprehensive guide explains how Amazon Bedrock Agent versioning works with CloudFormation, based on extensive testing and real-world examples.
aidin
Amazon Employee
Published Apr 8, 2025
This comprehensive guide explains how Amazon Bedrock Agent versioning works with CloudFormation, based on extensive testing and real-world examples.
Understanding Agent Versions and Aliases
When you create an Amazon Bedrock Agent, it starts with a `DRAFT` version. This is the working version that you can modify and test. When you're ready to deploy your agent to production, you create a numbered version (e.g., `1`, `2`, etc.) which is an immutable snapshot of your agent's configuration.
I have tested it and my CloudFormation deployment created:
- A DRAFT version (automatically created)
- A version 1 (automatically created when an alias points to a version)
- Versions 2 through 7 (automatically created when updating the agent via CloudFormation)
Aliases are pointers to specific versions of your agent. They allow you to:
- Maintain a stable endpoint for your applications while updating the underlying agent version
- Implement blue/green deployments by gradually shifting traffic between versions
- Maintain different environments (dev, test, prod) pointing to different versions
Our CloudFormation deployment created:
- A `prod` alias pointing to version `1` (created by our template)
- An `AgentTestAlias` pointing to the `DRAFT` version (automatically created)
With each update to our agent via CloudFormation:
- A new version was automatically created
- The `prod` alias was automatically updated to point to the latest version
- The `AgentTestAlias` continued to point to the `DRAFT` version
AWSTemplateFormatVersion: '2010-09-09'
Description: 'CloudFormation template for an Amazon Bedrock Agent with an alias'
Parameters:
AgentName:
Type: String
Default: SimpleBedrockAgent
Description: Name of the Amazon Bedrock Agent
ModelId:
Type: String
Default: anthropic.claude-3-sonnet-20240229-v1:0
Description: The foundation model ID to use for the agent
AgentDescription:
Type: String
Default: A simple Amazon Bedrock Agent created via CloudFormation
Description: Description of the Amazon Bedrock Agent
AliasName:
Type: String
Default: prod
Description: Name of the agent alias
Resources:
BedrockAgentRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: bedrock.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AmazonBedrockFullAccess
Path: /service-role/
BedrockAgent:
Type: AWS::Bedrock::Agent
Properties:
AgentName: !Ref AgentName
AgentResourceRoleArn: !GetAtt BedrockAgentRole.Arn
Description: !Ref AgentDescription
FoundationModel: !Ref ModelId
IdleSessionTTLInSeconds: 1800
Instruction: "You are a helpful assistant that provides information about AWS services."
Tags:
CreatedBy: CloudFormation
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName}"
Tags:
CreatedBy: CloudFormation
Outputs:
AgentId:
Description: The ID of the created Bedrock Agent
Value: !Ref BedrockAgent
AliasId:
Description: The ID of the created Agent Alias
Value: !Ref BedrockAgentAlias
Description: 'CloudFormation template for an Amazon Bedrock Agent with an alias'
Parameters:
AgentName:
Type: String
Default: SimpleBedrockAgent
Description: Name of the Amazon Bedrock Agent
ModelId:
Type: String
Default: anthropic.claude-3-sonnet-20240229-v1:0
Description: The foundation model ID to use for the agent
AgentDescription:
Type: String
Default: A simple Amazon Bedrock Agent created via CloudFormation
Description: Description of the Amazon Bedrock Agent
AliasName:
Type: String
Default: prod
Description: Name of the agent alias
Resources:
BedrockAgentRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: bedrock.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AmazonBedrockFullAccess
Path: /service-role/
BedrockAgent:
Type: AWS::Bedrock::Agent
Properties:
AgentName: !Ref AgentName
AgentResourceRoleArn: !GetAtt BedrockAgentRole.Arn
Description: !Ref AgentDescription
FoundationModel: !Ref ModelId
IdleSessionTTLInSeconds: 1800
Instruction: "You are a helpful assistant that provides information about AWS services."
Tags:
CreatedBy: CloudFormation
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName}"
Tags:
CreatedBy: CloudFormation
Outputs:
AgentId:
Description: The ID of the created Bedrock Agent
Value: !Ref BedrockAgent
AliasId:
Description: The ID of the created Agent Alias
Value: !Ref BedrockAgentAlias
AWSTemplateFormatVersion: '2010-09-09'
Description: 'CloudFormation template for an Amazon Bedrock Agent with an alias pointing to a specific version'
Parameters:
AgentName:
Type: String
Default: SimpleBedrockAgent
Description: Name of the Amazon Bedrock Agent
ModelId:
Type: String
Default: anthropic.claude-3-sonnet-20240229-v1:0
Description: The foundation model ID to use for the agent
AgentDescription:
Type: String
Default: A simple Amazon Bedrock Agent created via CloudFormation
Description: Description of the Amazon Bedrock Agent
AliasName:
Type: String
Default: prod
Description: Name of the agent alias
TargetVersion:
Type: String
Default: "3"
Description: The version to roll back to
Resources:
BedrockAgentRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: bedrock.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AmazonBedrockFullAccess
Path: /service-role/
BedrockAgent:
Type: AWS::Bedrock::Agent
Properties:
AgentName: !Ref AgentName
AgentResourceRoleArn: !GetAtt BedrockAgentRole.Arn
Description: !Ref AgentDescription
FoundationModel: !Ref ModelId
IdleSessionTTLInSeconds: 1800
Instruction: "You are an expert AWS solutions architect, DevOps specialist, and security consultant that provides comprehensive information about AWS services, best practices, and architecture patterns."
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName} (rolled back to version ${TargetVersion})"
RoutingConfiguration:
- AgentVersion: !Ref TargetVersion
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
Outputs:
AgentId:
Description: The ID of the created Bedrock Agent
Value: !Ref BedrockAgent
AliasId:
Description: The ID of the created Agent Alias
Value: !Ref BedrockAgentAlias
Description: 'CloudFormation template for an Amazon Bedrock Agent with an alias pointing to a specific version'
Parameters:
AgentName:
Type: String
Default: SimpleBedrockAgent
Description: Name of the Amazon Bedrock Agent
ModelId:
Type: String
Default: anthropic.claude-3-sonnet-20240229-v1:0
Description: The foundation model ID to use for the agent
AgentDescription:
Type: String
Default: A simple Amazon Bedrock Agent created via CloudFormation
Description: Description of the Amazon Bedrock Agent
AliasName:
Type: String
Default: prod
Description: Name of the agent alias
TargetVersion:
Type: String
Default: "3"
Description: The version to roll back to
Resources:
BedrockAgentRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Principal:
Service: bedrock.amazonaws.com
Action: sts:AssumeRole
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AmazonBedrockFullAccess
Path: /service-role/
BedrockAgent:
Type: AWS::Bedrock::Agent
Properties:
AgentName: !Ref AgentName
AgentResourceRoleArn: !GetAtt BedrockAgentRole.Arn
Description: !Ref AgentDescription
FoundationModel: !Ref ModelId
IdleSessionTTLInSeconds: 1800
Instruction: "You are an expert AWS solutions architect, DevOps specialist, and security consultant that provides comprehensive information about AWS services, best practices, and architecture patterns."
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName} (rolled back to version ${TargetVersion})"
RoutingConfiguration:
- AgentVersion: !Ref TargetVersion
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
Outputs:
AgentId:
Description: The ID of the created Bedrock Agent
Value: !Ref BedrockAgent
AliasId:
Description: The ID of the created Agent Alias
Value: !Ref BedrockAgentAlias
When updating an agent through CloudFormation:
- A new numbered version is automatically created (incrementing by 1)
- The DRAFT version is updated to match the latest configuration
- CloudFormation-managed aliases are automatically updated to point to the latest version
- Non-CloudFormation-managed aliases maintain their original routing configuration
- All previous versions are preserved as immutable snapshots
- Each version maintains its own configuration, including instruction, model, etc.
We confirmed this behavior across multiple updates (versions 1-7), with each update showing consistent behavior.
When rolling back to a previous version through CloudFormation:
1. No New Version Created: Unlike regular updates, rolling back to a previous version doesn't create a new version number.
2. Alias Routing Updated: The CloudFormation-managed alias is updated to point to the specified version.
3. DRAFT Version Unaffected: Rolling back doesn't change the DRAFT version, which still contains the latest changes.
4. All Versions Preserved: All previous versions remain available and unchanged.
2. Alias Routing Updated: The CloudFormation-managed alias is updated to point to the specified version.
3. DRAFT Version Unaffected: Rolling back doesn't change the DRAFT version, which still contains the latest changes.
4. All Versions Preserved: All previous versions remain available and unchanged.
We successfully rolled back from version 6 to version 3, and then updated to version 7, demonstrating the flexibility of the versioning system.
The key to rolling back is to explicitly specify the `RoutingConfiguration` in the `BedrockAgentAlias` resource:
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName} (rolled back to version ${TargetVersion})"
RoutingConfiguration:
- AgentVersion: !Ref TargetVersion
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
BedrockAgentAlias:
Type: AWS::Bedrock::AgentAlias
Properties:
AgentId: !Ref BedrockAgent
AgentAliasName: !Ref AliasName
Description: !Sub "Alias for ${AgentName} (rolled back to version ${TargetVersion})"
RoutingConfiguration:
- AgentVersion: !Ref TargetVersion
Tags:
CreatedBy: CloudFormation
Version: rollback-to-v3
- Use CloudFormation for Consistent Versioning: CloudFormation provides a reliable way to create and update agents with proper versioning.
- Maintain Version History Documentation: Keep track of what changes were made in each version.
- Use Aliases for Environment Management: Create separate aliases for development, testing, and production environments.
- Consider Version Rollback Strategy: In case of issues with a new version, have a process to update aliases to point to previous stable versions.
- Limit Version Proliferation: While versions are useful, consider cleaning up old versions that are no longer needed to avoid confusion.
- Test with DRAFT Before Creating Versions: Use the DRAFT version for testing before deploying changes to production aliases.
- Include Version Tags: Add version information in tags to help track resources across your AWS environment.
- Document Rollback Reasons: Keep track of why you rolled back to help prevent similar issues in the future.
- Test Rollback Version: Verify the rollback version works as expected before routing production traffic to it.
- Communicate Changes: Inform stakeholders when rolling back to a previous version.
- Monitor After Rollback: Closely monitor the agent after rollback to ensure it's functioning correctly.
- Plan for Forward Fix: Treat rollbacks as temporary measures while you address the issues in a new version.
- Parameterize Key Values: Make agent name, model ID, and other key properties configurable.
- Use Tags Correctly: In CloudFormation templates, the `Tags` property for Bedrock resources must be specified as an object, not an array.
- Consider Explicit Routing: For production deployments, consider explicitly specifying the routing configuration.
- Include Descriptive Outputs: Add outputs that make it easy to identify the created resources.
List Agent Versions
aws bedrock-agent list-agent-versions --agent-id YOUR_AGENT_ID --region YOUR_REGION
List Agent Aliases
aws bedrock-agent list-agent-aliases --agent-id YOUR_AGENT_ID --region YOUR_REGION
Get Details of a Specific Version
aws bedrock-agent get-agent-version --agent-id YOUR_AGENT_ID --agent-version VERSION_NUMBER --region YOUR_REGION
Create a New Version
aws bedrock-agent create-agent-version --agent-id YOUR_AGENT_ID --region YOUR_REGION
Update Alias Routing
aws bedrock-agent update-agent-alias --agent-id YOUR_AGENT_ID --agent-alias-id YOUR_ALIAS_ID —routing configuration agentVersion=NEW_VERSION --region YOUR_REGION
Amazon Bedrock Agent versioning through CloudFormation provides a robust way to manage the evolution of your agents over time. Our extensive testing has revealed several key insights:
- Predictable Versioning: CloudFormation provides a predictable and consistent versioning mechanism for Bedrock agents.
- Flexible Rollbacks: You can easily roll back to any previous version by explicitly specifying the routing configuration.
- Version Preservation: All versions are preserved, allowing you to track the evolution of your agent over time.
- Alias Management: Aliases provide a stable endpoint while allowing you to change which version they point to.
- DRAFT Version: The DRAFT version always contains the latest changes, regardless of which version aliases point to.
- CloudFormation Integration: CloudFormation fully supports both creating new versions and rolling back to previous versions.
This versioning behavior makes Amazon Bedrock Agents well-suited for production environments with proper change management processes. By understanding how versions and aliases work, you can implement effective strategies for deploying, updating, and rolling back your agents as part of your overall application lifecycle management.
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.