The AWS Well-Architected Agent landed in preview on October 1, and it is the first time the Well-Architected Framework has shown up as something that actually reads your accounts instead of a questionnaire you fill out from memory. Under the hood it is a fairly tidy machine: a profile, some goals, an application context, two IAM roles, and a scheduler. Know how those pieces fit and you will skip most of the “why is my profile not eligible” pain.
What the AWS Well-Architected Agent actually does
Per the launch post, the agent is delivered by AWS Support and analyzes resource configurations, utilization metrics and application topology, then checks them against Well-Architected best practices across 65+ services. The output is a ranked list of recommendations shaped by goals you write in plain English, not a 400-line dump of every unencrypted bucket you ever forgot about.
You get baseline Trusted Advisor recommendations without doing anything. The agent-driven, goal-aware stuff requires an agent profile, and that is where the moving parts start.
The object model: profile, goals, context
The concepts page lays out three objects you create, in this order:
- Agent profile. The container. It lives in one account (the “profile account”), names an execution role, selects pillars, and lists up to 100 workload accounts with their access roles and Regions. Profile names run 3 to 128 characters.
- Goals. Plain-text objectives, each tied to one pillar. “Cut EC2 spend 20% by Q4” under Cost Optimization. “Every customer-facing service survives a single-AZ loss” under Resilience. Goals drive prioritization, so vague goals get you vague rankings.
- Application context. Required, not optional. It describes what the workload is, how critical it is, and which accounts, Regions and tags belong to it. Without it, the agent has no idea that the box tagged
app=paymentsmatters more than the forgotten sandbox next door.
Once all three exist and validate, the profile becomes eligible for scheduled generation. The user guide says first results show up within 24 hours; the API reference hedges at 48. Plan for two days and be pleasantly surprised.
The two-role trust chain
This is the part people get wrong. There are two roles, in two places, and they chain.
The execution role sits in the profile account. Its trust policy allows the service principal wellarchitected.amazonaws.com to assume it. The default name is ExecutionRoleForWellArchitectedAgent, and if the console creates it for you, it lands under the service-role/ path. That path matters, because the ARN you reference later has to include it.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "wellarchitected.amazonaws.com" },
"Action": "sts:AssumeRole"
}]
}The access role lives in every workload account the profile covers. Default name AccessRoleForWellArchitectedAgent, trusted by the execution role’s ARN, with the AWS managed policy WellArchitectedAgentResourceScanning attached. That policy is read-only. The agent can look, it cannot touch.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/service-role/ExecutionRoleForWellArchitectedAgent"
},
"Action": "sts:AssumeRole"
}]
}So the flow is: service assumes execution role in the profile account, execution role assumes access role in each workload account, access role reads. Classic hub-and-spoke, same shape as every cross-account auditing tool you have ever deployed, minus the Lambda you would have had to babysit.
The most common breakage is predictable: someone creates the execution role by hand without the service-role/ path, then copies the console-style ARN into the access role trust policy. The assume fails, and the profile reports errors instead of findings.
Checking eligibility before you wait two days
Do not sit around for 48 hours to discover a typo. The API quickstart exposes the eligibility flag and per-field validation errors on the profile itself:
aws wellarchitected get-agent-profile \
--profile-arn arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/EXAMPLE \
--region us-east-1 \
--query '{eligible: eligibleForScheduledGeneration, errors: fieldErrors}'If eligible is false, errors tells you which field is unhappy: a missing context, an access role that cannot be assumed, an account ID that does not match. Fix, re-run, move on. Put this in whatever script creates the profile so it fails loudly instead of quietly.
One Region note: the agent itself runs in us-east-1, us-east-2 and us-west-2, but it onboards workloads from any commercial Region. Your profile lives in one of those three; your workloads can live wherever.
Three kinds of recommendations
The agent returns three recommendation types, and they deserve different handling:
- Resource recommendations. Scoped to a single resource: an oversized instance, a volume without snapshots, a security group open wider than it should be. These are the ones you can usually act on in an afternoon.
- Application recommendations. Scoped to the workload described in your application context. Think “this service has a single-AZ dependency on its cache tier” rather than “this cache node is small.” This is where the goal-awareness pays off.
- Architecture recommendations. Produced by analyzing infrastructure as code. Hand it CloudFormation, Terraform or CDK and it can return updated templates, not just prose. That is a big deal, and it is where the agent stops being a smarter Trusted Advisor and starts being a reviewer.
Cross-pillar trade-offs show up too. A Resilience recommendation that adds a standby will note its cost impact rather than pretending reliability is free.
Real dollars versus list-price guesses
Cost impact numbers come from one of two sources. If you enable resource-level daily granularity in Cost Explorer, the agent uses your actual spend per resource. If you do not, it falls back to estimates from public pricing, which ignore your Savings Plans, Reserved Instances, EDP discounts and everything else your finance team negotiated.
The catch: granular data is not free, and once you turn it on, the docs warn it cannot simply be disabled. Check the Cost Explorer pricing page before flipping it in a large organization. For most teams with real discount coverage, the accuracy is worth it, because a recommendation that says “save $4,000” when the real number is $900 trains people to ignore the tool.
Prerequisites people trip over
- Support plan. The profile requires Business+, Enterprise On-Ramp, Enterprise or Unified Operations. Developer and plain Business are excluded. See the support plans page.
- Account cap. 100 accounts per profile. Bigger estates need multiple profiles, which is a decent forcing function to scope by business unit anyway.
- Preview semantics. APIs and output formats can shift. Pin your CLI version in automation and read the user guide changelog before upgrading.
- Generative output. AWS says plainly that recommendations may contain errors. Treat them like a sharp junior engineer’s PR comments: usually right, always reviewed.
Where to start
Pick one production workload with a clear owner. Create the execution role, deploy the access role with StackSets to that workload’s accounts, write two or three specific goals, fill in a real application context with tags, and run the eligibility check. Read the first batch of recommendations with the owning team, not alone. The getting started guide covers the console path if you want to click through once before scripting it.
The design is sensible: read-only by default, goal-driven prioritization, IaC-aware reviews. The quality will depend on how accurately you describe your workloads, which, to be fair, was always true of Well-Architected reviews. The difference is that this one does the reading for you.
At Enkompass (enkompass.net), this is our home turf. We have run Well-Architected reviews across multi-account AWS Organizations and wired the cross-account IAM plumbing that tools like this depend on. If you’d rather have seasoned cloud people handle it instead of learning the hard way at 2 AM, let’s talk. Reach out through our contact page or call us directly at +1-828-436-5667 — we’ll help you turn this from a someday-project into a done-deal.