I have run Well-Architected reviews the old way more times than I can count: a spreadsheet, a room full of engineers, two days of questions, and a remediation backlog that nobody owns by the following sprint. Trusted Advisor helped with the detection side, but it hands you a flat list. An idle EBS volume in a sandbox account and a single-AZ RDS instance behind your payment API arrive with the same visual weight.
On October 1, 2026, AWS launched the preview of AWS Well-Architected Agent , positioned as the next generation of both Trusted Advisor and the Well-Architected Tool. The pitch is that it ranks findings against business goals you declare and ships each finding with a fix in console, CLI, or IaC form.
The announcement is three paragraphs. The user guide is much longer, and it is where the useful detail lives: the IAM role chain, the support-tier gate, the quotas, and the resource types it does not analyze. This post walks through those mechanics, the CLI onboarding path, and the gaps I would want to know about before pointing it at production accounts.
What actually shipped
It is a preview, delivered by AWS Support, that continuously scans your accounts and produces ranked recommendations across four pillars: cost optimization, security, resilience, and performance. Operational excellence and sustainability, the other two Well-Architected pillars, are not in scope for the agent.
| Attribute | Detail |
|---|---|
| Status | Public preview, subject to change |
| Pillars analyzed | Cost optimization, security, resilience, performance |
| Service coverage | 65+ AWS services (AWS News Blog) |
| Recommendation levels | Resource, application (beta), architecture |
| Remediation formats | Console walkthrough, AWS CLI commands, updated IaC code |
| Refresh cadence | Weekly scheduled refresh; architecture reviews on demand |
| Profile hosting Regions | us-east-1, us-east-2, us-west-2 |
| Regions scanned | All commercial Regions |
| Support plan | Business+, Enterprise On-Ramp, Enterprise Support, or Unified Operations |
| Programmatic access | wellarchitected API namespace, AWS CLI, AWS MCP Server |
Two framing points from the docs matter. First, it ingests findings from Trusted Advisor rather than replacing that detection layer, then adds goal-based ranking and remediation on top. Second, the existing Well-Architected Tool is not going away; you can still run manual reviews with custom lenses.
The mechanics: profile, goals, context, roles
Everything hangs off an agent profile. A profile defines which accounts and Regions to scan, which pillars to analyze, and which goals to rank against. Nothing works without one, not even architecture reviews.
Goals are plain-text statements tied to one or more pillars. The docs' own example is specific and measurable: reduce EC2 spend by 20% by Q4 through rightsizing and Reserved Instance coverage. A profile needs at least one goal and allows up to 10 active goals. Goals are also exposed as a CloudFormation resource,
AWS::WellArchitected::AgentGoal, which means you can version them alongside your infrastructure.Application context is the part most people will skip, and it is mandatory. Without at least one application context, the profile is flagged invalid and scheduled generation never runs. Context tells the agent what the agent cannot discover on its own: application name, overview, criticality, accounts, Regions, and tags to narrow scope.
The role chain is a two-hop design:
- An execution role in the profile account (default name
ExecutionRoleForWellArchitectedAgent) is assumed by the service to orchestrate discovery. - The execution role calls
sts:AssumeRoleon an access role in each workload account (default nameAccessRoleForWellArchitectedAgent). - Each access role carries the AWS managed policy
WellArchitectedAgentResourceScanning, which grants read-only access to resource metadata and configuration.
The access role trust policy is a single statement that trusts the execution role ARN:
1
2
3
4
5
6
7
8
9
10
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::111122223333:role/service-role/ExecutionRoleForWellArchitectedAgent" },
"Action": "sts:AssumeRole"
}
]
}One trap worth calling out: the execution role ARN path differs depending on how you created it. Roles created by the console's Create new role button live under
service-role/. Roles you pre-create in IAM do not. Copy the ARN from the profile details page rather than typing it.The console does not create the access roles for you. After profile creation it shows an Action required prompt, and the agent ignores any account whose access role does not exist yet. At 100 accounts per profile, that is a StackSet or Terraform job, not a click-ops task.
Three recommendation levels, two generation paths
The agent produces three types of recommendation, and they are not generated the same way. Resource and application recommendations come only from the scheduled cycle. Architecture recommendations come only from on-demand IaC reviews.
| Level | Scope | How it is generated | What you get |
|---|---|---|---|
| Resource | A single resource | Weekly scheduled refresh | Finding, dollar impact where applicable, step-by-step fix |
| Application (beta) | Findings consolidated across resources in one application context | Weekly scheduled refresh | Grouped finding scoped to the application |
| Architecture | Patterns across an IaC project | On demand, max 5 reviews per profile per day | Updated IaC code in the same language as the input |
Every recommendation carries two pieces of analysis that Trusted Advisor never gave you. Cross-pillar impact shows how the change helps other pillars. Trade-off analysis names the pillar that pays, the risk level, and a mitigation. The announcement's example is adding Multi-AZ failover to a critical database, with the cost and performance effect shown before you commit.
A few mechanics that shape how you will use it:
- Each generation run caps at 30 recommendations. Stored recommendations accumulate across runs, but a single run will not dump 400 findings on you. That is a deliberate prioritization constraint.
- Scheduled runs have a 24-hour cooldown per profile, and you cannot trigger resource or application recommendations on demand. The
StartAgentRecommendationGenerationAPI only accepts theARCHITECTUREtype. - Cost accuracy depends on AWS Cost Explorer. Without it, the agent estimates from public pricing, which ignores your Savings Plans, RIs, and EDP discount. For resource-level dollar figures you also need resource-level data at daily granularity enabled in Cost Management Preferences, which carries its own charge.
Onboarding from the CLI
The whole setup can be done with four
aws wellarchitected calls, which is the path I would take for anything beyond a proof of concept. The API does not create IAM roles, so the execution role and every access role must exist first.1. Create the profile. The API lets you set a different access role ARN per account, which the console does not allow.
1
2
3
4
5
aws wellarchitected create-agent-profile \
--name "platform-prod" \
--execution-role-arn "arn:aws:iam::111122223333:role/service-role/ExecutionRoleForWellArchitectedAgent" \
--pillars COST_OPTIMIZATION SECURITY RESILIENCE PERFORMANCE \
--aggregation-configuration '[{"accountId":"444455556666","accessRoleArn":"arn:aws:iam::444455556666:role/AccessRoleForWellArchitectedAgent","regions":["eu-central-1","eu-west-1"]}]'2. Add a goal. Write it like an OKR, not a slogan. A measurable target with a date gives the ranking something to work against.
1
2
3
4
aws wellarchitected create-agent-goal \
--profile-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-prod" \
--title "Eliminate single-AZ data stores for tier-1 services by end of Q1" \
--pillars RESILIENCE3. Add application context. This is the step that makes the profile valid.
1
2
3
4
5
aws wellarchitected create-agent-context \
--profile-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-prod" \
--title "Payment processing service" \
--context-type APPLICATION \
--content '{"applicationOverview":"Real-time payment processing","criticality":"MISSION_CRITICAL","accountIds":["444455556666"],"regions":["eu-central-1"]}'4. Verify eligibility.
1
2
3
aws wellarchitected get-agent-profile \
--profile-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-prod" \
--query '{eligible: eligibleForScheduledGeneration, errors: fieldErrors}'If
eligibleForScheduledGeneration comes back false, the fieldErrors map tells you which field is wrong. Given the service-role path difference above, the trust policy ARN is the first thing I would check.Note that the profile itself lives in one of the three US hosting Regions, while the
regions in the aggregation configuration can be any commercial Region. Example account IDs and ARNs above follow the docs' placeholder format.Architecture reviews: the shift-left piece
This is the feature I care most about as a DevSecOps person. Architecture reviews analyze IaC before deployment and return deployment-ready updated templates, in the same language you submitted. Submit Terraform, get Terraform back.
The input is an S3 URI pointing to either a .zip of the IaC project or an S3 folder. The bucket must be in the same Region as the agent profile, and you must tick a consent checkbox (or the API equivalent) allowing the agent to read the contents.
| Limit | Value |
|---|---|
| .zip upload size | 25 MB |
| S3 folder total size | 100 MB |
| Individual file in S3 folder | 1 MB |
| Reviews per profile per day | 5 |
| Lens available | Well-Architected Framework only |
Binary and media files are excluded, and the service rejects submissions it judges to contain malicious content. Custom lenses, which many enterprises have invested in through the Well-Architected Tool, are not supported for agent reviews yet.
From the CLI, a review scoped to security and cost looks like this:
1
2
3
4
5
6
7
8
9
10
11
12
aws wellarchitected start-agent-recommendation-generation \
--profile-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-prod" \
--types ARCHITECTURE \
--name "payments-tf-pr-1842" \
--scope '{"pillars": ["SECURITY", "COST_OPTIMIZATION"]}' \
--additional-context '{
"s3Uri": "s3://iac-review-us-east-1/payments/pr-1842.zip",
"lensArns": ["arn:aws:wellarchitected::aws:lens/wellarchitected"]
}'
aws wellarchitected list-agent-recommendation-generations \
--profile-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/platform-prod"The
scope object also accepts goalIds (up to 10) and an items filter that narrows the review to specific best practice IDs such as SEC02-BP02, service names, or resource ARNs. That filter is useful when you want a fast, targeted check on one concern instead of a full sweep.The DevSecOps lens: access and blind spots
The access model is reasonable. Workload accounts grant read-only metadata access through a managed policy, the trust is pinned to one execution role ARN, and nothing in the documented setup gives the agent write access. Remediation is something you run, not something the agent runs. If you already have broad trust policies from early testing, the docs tell you to tighten them back to the single-principal template.
The part that deserves more attention is coverage. The quotas page lists CloudFormation resource types the agent does not analyze. Several of them are exactly where security posture lives:
| Area | Unsupported resource types (selection) |
|---|---|
| Edge protection | AWS::WAFv2::WebACL, AWS::WAFv2::RuleGroup, AWS::WAFv2::IPSet, AWS::Shield::Protection |
| Inline IAM | AWS::IAM::RolePolicy, AWS::IAM::UserPolicy, AWS::IAM::GroupPolicy |
| Org guardrails | AWS::Organizations::Policy, AWS::ControlTower::EnabledControl |
| Detection config | AWS::SecurityHub::* (13 types), AWS::SecurityLake::*, AWS::Macie::FindingsFilter |
| Identity Center | AWS::SSO::PermissionSet, AWS::SSO::Assignment |
| Search | AWS::OpenSearchService::Domain |
Read that list carefully before you present the agent's security score to anyone. No WAF configuration, no inline IAM policies, no SCPs, and no Identity Center permission sets means a clean security result says nothing about some of your highest-risk controls. Keep Security Hub, IAM Access Analyzer, and your policy-as-code checks in place. The agent complements them; it does not replace them.
The second point is accountability. AWS states plainly that recommendations are generated by AI and may contain errors or incomplete information, and that evaluating them is your responsibility. According to AWS Support leadership quoted in The AI Economy , findings are grounded in deterministic signals such as Trusted Advisor, pass a claim-validation step, and are traceable to their source signal. That traceability is good for auditors. It does not change the rule: every generated IaC change goes through a pull request and a human review.
What the announcement does not tell you
The What's New post says the agent is available to customers "with an AWS Support plan". The user guide is narrower, and several other details differ between the launch material and the docs.
| Topic | Launch material says | User guide says |
|---|---|---|
| Eligibility | Any AWS Support plan | Business+ or higher only; Developer and Business tiers have no access |
| Time to first recommendations | Within 24 hours of profile creation (News Blog) | Scheduled recommendations within 48 hours |
| IaC formats for reviews | Terraform, CloudFormation, CDK | Architecture review page lists CDK and Terraform projects |
| Remediation formats | What's New mentions SSM runbooks | News Blog and docs describe console, CLI, and IaC paths |
| Lenses | Well-Architected lens selection | Only the Well-Architected Framework lens is supported for reviews |
The tier gate also caps scale. Business+ gets 2 profiles with 7 applications each. Enterprise On-Ramp, Enterprise Support, and Unified Operations get 10 profiles with 30 applications each. Each profile still tops out at 100 accounts, so a large AWS Organization will need a deliberate profile strategy, probably one per business unit or platform boundary.
Other practical constraints:
- Data residency. Profiles are hosted only in three US Regions. If your organization has EU data-handling rules, review what metadata leaves the workload Region before onboarding. I could not find a statement in the docs about where scanned configuration data is processed beyond the hosting Region.
- Pillar coverage. Operational excellence and sustainability are not analyzed.
- Application recommendations are beta. The docs explicitly ask for feedback on their quality and tell you to review each one before acting.
- Preview pricing. I found no separate price for the agent in the launch material; it is delivered through AWS Support. Cost Explorer API calls and resource-level granular data do carry charges.
Some third-party write-ups already in circulation describe preview feature flags, single-Region availability, and JSON workload-definition payloads. None of that matches the official docs. Go to the user guide, not the summaries.
Where it fits in a delivery pipeline
The architecture review API is the piece that belongs in CI, and the pattern below is how I would wire it. This is my design, not an AWS reference architecture.
The agent review runs alongside your existing policy-as-code and SAST checks, and both feed a required human approval. Nothing generated by the agent is applied automatically.
Three constraints shape the design:
- The quota is 5 reviews per profile per day. You cannot run it on every push. Trigger it on a PR label, on changes to tier-1 modules, or once per release branch.
- The S3 bucket must sit in the profile's hosting Region. For an EU-based team, that means a dedicated us-east-1 (or us-east-2, us-west-2) bucket for review uploads, with a lifecycle rule to expire them.
- Use the
itemsfilter for targeted checks. A narrow review against specific best practice IDs is faster to read in a PR comment than a full four-pillar sweep.
For engineers working in an AI coding tool, AWS points to the AWS MCP Server and its plugins as the programmatic route into the agent's APIs. That pairs naturally with a Claude Code or Copilot workflow where the IaC change and the review live in the same session.
Verdict
Well-Architected Agent fixes the right problem. Ranking findings against declared goals, showing trade-offs before the change, and returning fixes in the IaC language you already use is a real step up from Trusted Advisor's flat list.
It is also clearly a preview. The Business+ gate, US-only hosting, a single lens, 30 recommendations per run, and blind spots across WAF, inline IAM, and SCPs mean it is a prioritization layer, not a posture tool of record. My recommendation: onboard one non-production profile, write two or three measurable goals, wire the architecture review into a pull-request workflow on a single repo, and compare its output with what your existing scanners already catch. That comparison will tell you more than any launch post.
If you try it, I would like to hear what it found that your current tooling missed, and what it got wrong.
Sources
- AWS Well-Architected Agent is now available in preview (What's New, Oct 1, 2026)
- Announcing AWS Well-Architected Agent (preview) (AWS News Blog, Channy Yun)
- What is AWS Well-Architected Agent?
- Getting started with AWS Well-Architected Agent
- API quickstart
- Conducting architecture reviews
- Quotas and limits
- AWS::WellArchitected::AgentGoal resource schema (Pulumi AWS Native registry)
- AWS Built an AI Agent That Audits Your Cloud Setup (The AI Economy)
About the author
Ashish Kasaudhan is a DevSecOps Architect at Giesecke+Devrient and a member of the AWS Community Builders program. He has spent 17 years in DevOps and platform engineering, working across cloud infrastructure, containerization, CI/CD, and enterprise automation, with earlier roles at PwC Acceleration Centers, Thales, and NTT DATA. He is the creator of SkyArch AI, an open-source multi-cloud architecture diagramming tool, and writes practitioner-focused pieces on cloud, DevOps, AIOps, and MLOps.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article