AWS Well-Architected Agent: Your Architecture Review, Now Done by an Agent (Preview)

A proper Well-Architected review has always had the same cost: a day or two of the team answering a long questionnaire, someone pulling evidence from five consoles, and a report that's stale within weeks. Trusted Advisor helps with point checks, but it has no idea which application matters or what your business is optimizing for this quarter.

On October 1, 2026, AWS launched AWS Well-Architected Agent in public preview. It continuously analyzes your accounts and returns cost, security, resilience, and performance recommendations ranked against goals you write yourself, and it hands you the fix: console steps, CLI commands, or the change to your infrastructure code. AWS positions it as the next step after Trusted Advisor and the Well-Architected Tool, delivered through AWS Support.

Here's how it works, how to wire it up with read-only cross-account roles, how to point it at an EKS Terraform repo before you deploy, and what to check before granting it access to your whole organization.

Profile → read-only role chaining → analysis → recommendations with remediation. (Diagram labels in Spanish, from the original article.)

TL;DR

• Public preview since Oct 1, 2026. The service runs in us-east-1, us-east-2, and us-west-2, but can analyze resources in any commercial Region.
• You create a profile: up to 100 accounts, their Regions, the pillars you care about, and a goal per pillar. First recommendations land within 24 hours.
• It reads resource configuration across 65+ services, utilization metrics, and application topology via read-only roles.
• Recommendations come at three levels (resource, application, architecture) with priority, effort, impact, ROI, and explicit trade-offs.
• IaC review: upload a .zip of Terraform, CloudFormation, or CDK and get findings before anything is deployed.
• Remediation via console, updated IaC, CLI, SDK, SSM runbooks, and MCP. In what AWS showed, it doesn't change resources on its own.
• Requires an AWS Support plan. No published preview pricing.

What it is (and isn't)

It's an AWS Support service surfaced in the Well-Architected console. It doesn't replace the Well-Architected Tool (AWS says you can keep using it for manual reviews), it isn't a compliance auditor, and every recommendation carries a disclaimer that it's AI-generated and may be wrong or incomplete.

Preview scope: the console offers four pillars (cost, security, resilience, performance). The API already lists OPERATIONAL_EXCELLENCE as a value, but it isn't exposed in the preview console. IaC reviews currently use the Well-Architected Framework lens.

How it works

Profile. Created in a host account. You list target accounts (up to 100) and Regions, choose pillars, write a goal for each ("reduce unnecessary spend across my accounts", "workloads recover gracefully from disruptions"), and pick the execution role. Deletion protection is on by default in the console.

Profile setup: Regions, accounts, pillars with goals, roles. Image: AWS.

Application context (optional). Tell it which applications exist, where they live, and which tags identify them. That's what turns "15 queues without alarms" into "your event pipeline has no failure observability in any of its three Regions."

Access. Role chaining: an execution role in the profile account trusts wellarchitected.amazonaws.com and can assume an access role in each target account; access roles use the managed policy WellArchitectedAgentResourceScanning and trust the execution role, with the profile ARN as external ID to prevent confused-deputy issues. Onboarding is opt-in per account.

Recommendations and remediation

Each comes with priority, effort, impact, an ROI estimate, affected resources, cross-pillar benefits, and trade-offs. That last field is what a good architect always tells you, and here it's explicit.

Recommendations ranked against the profile's goals. Image: AWS.

Start remediation lets you pick console, updated IaC template, or AWS CLI. The API's remediation types also include SDK, MCP, and AUTO_REMEDIATION. In AWS's example, the IaC option returns a CDK helper ready to paste into your stack, split into phases.

IaC remediation returns the change for your repo. Image: AWS.

Architecture review. Upload a .zip of your IaC project to S3, choose lens and pillars, start the review. Binary and media files are excluded. Classmethod tried it on day one: the review took about 30 minutes and flagged, among other things, a Lambda function hard-coded to MemorySize: 256 with no alarms or tuning automation.

Hands-on

You need an active AWS Support plan, a recent AWS CLI, and one of the service Regions (us-east-1 here).

1. Execution role (profile account):

cat > exec-trust.json <<'EOF'
{"Version":"2012-10-17","Statement":[{"Effect":"Allow",
 "Principal":{"Service":"wellarchitected.amazonaws.com"},"Action":"sts:AssumeRole"}]}
EOF
aws iam create-role --path /service-role/ --role-name WAAgentExecutionRole \
  --assume-role-policy-document file://exec-trust.json

Give it sts:AssumeRole on arn:aws:iam::*:role/AccessRoleForWellArchitectedAgent.

2. Access role (each target account). Look up the managed policy ARN instead of hard-coding it:

POLICY_ARN=$(aws iam list-policies --scope AWS \
  --query "Policies[?PolicyName=='WellArchitectedAgentResourceScanning'].Arn" --output text)
aws iam create-role --role-name AccessRoleForWellArchitectedAgent \
  --assume-role-policy-document file://access-trust.json
aws iam attach-role-policy --role-name AccessRoleForWellArchitectedAgent \
  --policy-arn "$POLICY_ARN"

At scale, deploy this with CloudFormation StackSets, and add the external ID condition per the IAM docs once the profile exists.

3. Profile:

aws wellarchitected create-agent-profile \
  --name platform-eks \
  --business-overview "EKS container platform for payment APIs" \
  --pillars COST_OPTIMIZATION SECURITY RESILIENCE PERFORMANCE \
  --execution-role-arn arn:aws:iam::111122223333:role/service-role/WAAgentExecutionRole \
  --aggregation-configuration file://aggregation.json \
  --deletion-protection --region us-east-1

aggregation.json is a list of {"accountId", "regions", "accessRoleArn"} objects. get-agent-profile reports eligibleForScheduledGeneration, eligibleForArchitectureGeneration, and any fieldErrors.

4. Review an EKS Terraform repo — package it without state, provider cache, or secrets:

zip -r ../infra-eks.zip . -x ".terraform/*" "*.tfstate" "*.tfstate.backup" "*.tfvars" ".git/*"
aws s3 cp ../infra-eks.zip s3://my-review-bucket/infra-eks.zip

Then Conduct architecture review in the console.

5. Pull recommendations from the CLI:

aws wellarchitected list-agent-recommendations \
  --profile-arn arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-eks \
  --pillar COST_OPTIMIZATION --state OPEN --region us-east-1

aws wellarchitected get-agent-recommendation \
  --recommendation-arn <recommendation ARN> --remediation-type IAC --region us-east-1

Each recommendation includes awsServices, so you can filter EKS/ECS items into a weekly platform report or open an issue per HIGH finding.

Traps: applying CLI fixes in a GitOps setup (Terraform or Argo CD will revert the drift; route IaC fixes through PRs); zipping tfvars or .env files; assuming read-only means nothing sensitive is read; expecting results before 24 hours; treating dollar figures as exact; forgetting deletion protection when you try to remove a profile.

Pricing and availability

No published price during preview; it requires an active AWS Support plan. You pay normally for the S3 object holding your IaC zip and for whatever remediation deploys (alarms, SSM runbooks, capacity changes).

The service runs only in three US Regions but can onboard resources from any commercial Region. That's the part to check: if your workloads live in, say, São Paulo, their configuration, metrics, and uploaded IaC get processed in the US, and the announcement doesn't say where that data is stored or for how long. Regulated workloads should get a compliance sign-off first. And it's a preview, so APIs, pillars, lenses, and pricing can change.

My take

What matters here isn't that it uses AI. It's that the unit of work changes. Trusted Advisor gave you checks; the Well-Architected Tool gave you a questionnaire. This gives you a recommendation with context, impact, trade-offs, and the change for your repo, ranked by goals you wrote. If quality holds up in messy real environments (AWS's demo was very polished; Classmethod got reasonable but medium/low-priority findings), it'll replace most annual manual reviews. Two things are still unknown: price and data residency. I'd try it now on non-production accounts, route every fix through a pull request, and wait for GA pricing before rolling it out org-wide.

Resources

• AWS News Blog announcement
• What's New
• User guide · IAM for the agent
• CLI: create-agent-profile · list-agent-recommendations · get-agent-recommendation
• Classmethod hands-on (Japanese)

Originally published in Spanish on CloudAcademy.ar.