Reviewing AWS Architecture With the AWS Well-Architected Agent

An AWS application can work correctly and still have architectural problems. An EC2 instance may be larger than necessary, an RDS database may have no suitable recovery strategy, or an application may depend on a single Availability Zone. Teams often miss these issues when they focus mainly on whether the application is running.

Architecture reviews help identify these problems before they affect users or increase cloud costs. However, reviewing a large AWS environment manually takes time. Developers and cloud architects must examine resource configurations, application dependencies, security settings, performance metrics, and recovery procedures.

The AWS Well-Architected Agent is designed to simplify this review process. Announced in public preview in October 2026, it analyzes AWS resources and Infrastructure as Code templates to provide recommendations based on business goals.

This article explains how the agent works, how to configure it, and how developers can use its recommendations to improve an existing AWS application.

What Is AWS Well-Architected Agent?

AWS Well-Architected Agent is an AI-powered architecture analysis service that examines AWS infrastructure and provides recommendations for improving cost, security, resilience, and performance.

It considers more than individual resource settings. The service can correlate resource configurations, utilization metrics, and application relationships to understand how infrastructure components work together.

For example, consider an e-commerce application with the following architecture:

An Application Load Balancer receives incoming requests.
EC2 instances host the ASP.NET Core application.
Amazon RDS stores customer and order information.
Amazon S3 stores product images and documents.
Amazon SQS handles background order-processing tasks.

A traditional resource review might identify that the EC2 instances are underutilized. However, an architecture review should also consider whether reducing their capacity affects application performance, whether the database can recover from an Availability Zone failure, and whether the queue-processing system can handle a sudden increase in orders.

The Well-Architected Agent can generate recommendations at three levels:

Recommendation level	What it examines
Resource	Individual resources such as EC2 instances, Lambda functions, and RDS databases
Application	Multiple related resources belonging to an application
Architecture	Infrastructure patterns and Infrastructure as Code templates

The agent can also provide implementation guidance, including AWS CLI commands, Systems Manager runbooks, console walkthroughs, and updated Infrastructure as Code templates where applicable.

Understand the Four Optimization Areas

The agent currently focuses on four optimization areas. These are related to the broader AWS Well-Architected Framework, but they are not the same as its six standard pillars.

Cost optimization

Cost recommendations help identify resources that consume more money than necessary.

Examples include:

EC2 instances with consistently low utilization.
Storage configurations that could be more economical.
Unnecessary resources that are still running.
Opportunities to improve resource allocation.

A recommendation should be evaluated against actual application requirements. Reducing an instance size may lower the monthly bill, but it can also increase response times during peak traffic.

Security

Security recommendations focus on reducing unnecessary access and identifying risky configurations.

For example, an application might have an S3 bucket with broader access than required or an IAM role with excessive permissions.

The goal is to reduce the attack surface while keeping the application functional.

Resilience

Resilience recommendations examine how well an application handles failures.

For example, a production database running in a configuration without an appropriate recovery strategy could become a major availability risk.

Recommendations may include improving database failover, reviewing backup configurations, and removing single points of failure.

Performance

Performance recommendations focus on resource utilization, application requirements, and infrastructure configuration.

An EC2 instance might have insufficient compute capacity, or a database might need a different configuration to support its workload.

Performance improvements should be measured against application metrics rather than accepted only because an automated recommendation suggests them.

Prepare Your AWS Environment

Before creating an agent profile, check whether your AWS environment meets the current preview requirements.

The important prerequisites include:

An active AWS Support plan at Business+ or higher for the profile and monitored accounts.
Permission to create the required IAM roles and AWS Well-Architected Agent profile.
The AWS account IDs and Regions that should be monitored.
Business goals for the selected optimization areas.
Application information that helps the agent understand your infrastructure.

The agent is available through the AWS Well-Architected service in the US East (N. Virginia), US East (Ohio), and US West (Oregon) Regions. Workloads can be onboarded from other AWS commercial Regions.

Cost Explorer is optional. However, enabling it with resource-level cost data provides more accurate cost information. Without it, the agent estimates costs using public AWS pricing.

For organizations using AWS Organizations, review service control policies before onboarding. An organization-level policy can prevent the agent from accessing resources even when the IAM role appears to have the required permissions.

Create an AWS Well-Architected Agent Profile

An agent profile defines what the service should analyze. It includes the AWS accounts, Regions, optimization areas, and business goals.

Step 1: Open the AWS Well-Architected console

Navigate to the Well-Architected Agent experience and select the option to create an agent profile.

Provide a profile name and description.

For example:

Profile Name: ecommerce-production-review

Description:
Architecture analysis for the production
e-commerce application.

Choose the AWS accounts and Regions that belong to the application.

A profile can monitor up to 100 AWS accounts. Use a clearly defined scope rather than including every account without considering ownership and application boundaries.

Step 2: Select optimization areas and business goals

Select the areas that matter to the application.

For an e-commerce system, the initial priorities might be:

Cost optimization
Security
Resilience
Performance

Next, define goals for the selected areas.

A useful goal should describe the outcome the team wants to achieve.

For example:

Cost optimization:
Reduce infrastructure costs without affecting
checkout response times.

Security:
Limit access to production resources and
remove unnecessary public exposure.

Resilience:
Reduce the impact of Availability Zone failures
on order processing.

Performance:
Maintain stable application response times
during high traffic.

Avoid goals such as "make everything better." The agent needs useful application context to prioritize recommendations according to the business requirements.

Step 3: Configure IAM permissions

The agent uses IAM roles to discover resources across AWS accounts.

There are two important roles:

Execution role: Created in the account that owns the agent profile. It allows the agent to coordinate resource discovery.
Access role: Created in each workload account. It allows the execution role to access resource metadata and configuration.

The access role should use the AWS-managed WellArchitectedAgentResourceScanning policy or a carefully scoped custom policy that provides the required read permissions.

The trust relationship allows the execution role to assume the access role.

A simplified trust policy looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/service-role/ExecutionRoleForWellArchitectedAgent"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Replace the account ID and role name with the values from your environment. The ARN path must match how the execution role was created.

Repeat the access-role setup in every workload account included in the profile.

One important security detail is that the standard scanning role is designed for read-only resource discovery. It does not give the agent permission to modify your infrastructure. Remediation remains a separate action that your team must review and authorize.

Step 4: Add application context

Creating a profile is not enough. You must also provide application context so that the agent can understand which resources belong to which workload.

For the e-commerce application, useful context might include:

Application Name:
Ecommerce Platform

Overview:
An online shopping application built with
ASP.NET Core and hosted on AWS.

Criticality:
Business Critical

Architecture:
Application Load Balancer, EC2 instances,
Amazon RDS, Amazon S3, and Amazon SQS.

Additional Context:
The application processes customer orders
and requires reliable checkout operations.

You can also provide account and Region information, resource tags, application type, and other architectural details.

At least one application context is required for scheduled recommendations.

After the profile and access roles are configured, the agent begins generating scheduled recommendations. AWS documentation states that these are typically available within 24 hours after completing the required setup.

Review Infrastructure as Code Before Deployment

One useful capability is architecture review of Infrastructure as Code templates.

Instead of waiting until resources are deployed, developers can submit infrastructure definitions for analysis.

The agent supports architecture reviews of:

Terraform
AWS CloudFormation
AWS Cloud Development Kit (CDK)

Consider the following simplified Terraform configuration:

resource "aws_instance" "application_server" {
  ami           = var.ami_id
  instance_type = "t3.large"

  tags = {
    Name = "EcommerceApplication"
  }
}

This configuration creates an EC2 instance. However, the snippet alone does not describe the complete production architecture.

An architecture review should consider questions such as:

Is the instance type suitable for the workload?
Is the instance deployed in an appropriate network configuration?
Are security groups restricting unnecessary access?
Is the application designed to recover if the instance fails?
Does the infrastructure support the required availability?

The agent can review the uploaded IaC project and return architecture-level recommendations with suggested template changes where supported.

This is useful during pull request reviews because teams can identify infrastructure problems before deploying changes.

However, a recommendation is not automatically a production-ready change. Review the generated template, compare it with the existing infrastructure, and run the normal plan, test, and approval process before applying it.

Turn Recommendations Into Engineering Tasks

An architecture review is valuable only when the findings lead to improvements.

Suppose the agent identifies three recommendations for the e-commerce application:

Finding	Possible action	Validation
EC2 capacity is higher than required	Evaluate a smaller instance or scaling policy	Load test the application
Database recovery needs improvement	Review Multi-AZ configuration and recovery procedures	Perform a controlled failover test
IAM permissions are broader than necessary	Reduce the role's permissions	Test application operations

Do not treat these recommendations as isolated tasks. Consider their effect on other optimization areas.

For example, reducing EC2 capacity may improve cost but negatively affect performance. Enabling additional database redundancy may improve resilience while increasing cost.

This is why cross-pillar trade-off analysis matters. A good architectural decision should consider the overall application rather than optimizing one metric at the expense of another.

A practical workflow is:

Review the recommendation and its affected resources.
Understand the reason behind the finding.
Check the proposed implementation and its trade-offs.
Create an engineering task with a clear owner.
Implement the change in a non-production environment.
Run application and infrastructure tests.
Obtain the required approval.
Deploy and monitor the result.

Keep the original finding and the implementation decision together. This creates a useful record of why the architecture changed.

Common Mistakes to Avoid

Treating AI recommendations as automatic approval

The agent provides analysis and remediation guidance, but it does not replace architectural responsibility. Review every proposed change before applying it.

Giving the agent broader IAM access than necessary

Use the recommended read-only scanning permissions or a carefully scoped custom policy. Avoid granting write access simply to make resource discovery easier.

Creating a profile without application context

Without application context, the agent cannot generate scheduled recommendations for the profile. Describe the workload, its criticality, and its business goals.

Ignoring cross-pillar trade-offs

A cost-saving recommendation may affect performance or resilience. Evaluate the complete impact before implementation.

Reviewing templates without checking deployed resources

Infrastructure as Code reviews help identify problems before deployment, but they do not replace reviews of existing resources. Configuration drift can cause deployed infrastructure to differ from the templates stored in source control.

AWS Well-Architected Agent vs. AWS Well-Architected Tool

These two services have related purposes, but they support different review workflows.

Area	Well-Architected Agent	Well-Architected Tool
Review approach	AI-powered infrastructure analysis	Guided architecture review
Main input	AWS resources, application context, and IaC	Workloads, lenses, and review answers
Output	Prioritized recommendations and remediation guidance	Identified risks and improvement plans
Best suited for	Contextual optimization and ongoing analysis	Structured reviews and governance
Infrastructure changes	Provides suggested remediation	Helps document and track improvements

The services complement each other. The agent can help discover and prioritize issues, while the Well-Architected Tool can support a structured review process and track improvement milestones.

Summary

AWS Well-Architected Agent provides a way to review AWS infrastructure using resource configurations, utilization metrics, application context, and Infrastructure as Code templates.

Its recommendations cover cost optimization, security, resilience, and performance. Developers can use it to identify infrastructure risks, understand trade-offs, and prepare remediation changes before applying them.

The most important part of using the service is setting the correct scope. Define the accounts and Regions, configure read-only IAM access, provide meaningful business goals, and describe the application accurately.

Use the recommendations as input to your engineering review process, not as automatic instructions to change production infrastructure. This approach helps teams improve AWS architecture while keeping technical decisions, security, and operational responsibility under their control.