AWS Well-Architected Agent: Don't Leave the Context Empty

I created a Well-Architected Agent profile from the console. Three accounts, four pillars, one goal per pillar. The API said the profile was eligible for recommendations. Everything looked fine.

Then I looked at the application context. The console had created one for me, called "Default Application". It had the accounts and the Regions. Nothing else.

Nothing warns you about it. This post is what I learned filling it in.

1. What You Need

Before the context matters, the profile has to exist. These are the requirements from the documentation:

• A support plan at Business+ or higher. Business+, Enterprise On-Ramp, Enterprise Support or Unified Operations. Developer and Business do not get the agent.
• A profile in a supported Region. us-east-1, us-east-2 or us-west-2. From there it scans all commercial Regions. One profile covers up to 100 accounts.
• IAM permissions to set it up. wellarchitected:CreateAgentProfile, plus iam:CreateRole, iam:AttachRolePolicy and iam:PassRole for the execution role.
• An execution role in the profile account. The console can create it for you.
• An access role in every account you want analyzed, with the same name in all of them, the managed policy WellArchitectedAgentResourceScanning, and a trust policy for the execution role. The console does not create these.
• At least one pillar, one goal and one application context.
• Optional: Cost Explorer. Without it, the agent estimates costs from public pricing.

If you want to script it, you also need a recent SDK. boto3 1.43 had the agent operations. 1.40 and AWS CLI 2.36.6 did not.

2. What the Context Is For

From the documentation:

• At least one application context is required, or the profile is invalid and scheduled recommendations do not run.
• It holds what the agent "cannot discover automatically" about your workload.
• Criticality "directly affects recommendation prioritization".
• Tags are how the agent tells applications apart when they share accounts.

The default context covers the first point and none of the others.

3. The Fields

• Overview. What the app does.
• Type and criticality. Criticality has four levels: MISSION_CRITICAL, BUSINESS_CRITICAL, NON_CRITICAL and TEST_DEVELOPMENT.
• Architecture overview. The main pieces and how they connect.
• Additional context. Free text.
• Scope. Accounts, Regions, tags, services and resource types.

4. What Tripped Me

Service names. I sent "Amazon DynamoDB", then "dynamodb". Both failed with unsupported awsServices. The answer is in a note in the docs: use the CloudFormation service name. AWS::DynamoDB::Table becomes DynamoDB.

Services alone take the whole account. Selecting a service includes every resource of that service in the account. Mine has 19 Lambda functions and only a few belong to the app. A tag together with services or resource types gives you the intersection.

I had no tags. My stack had none of its own. CloudFormation adds aws:cloudformation:stack-name to every resource it creates, and the API accepted it as the scope tag. I have not confirmed that the agent filters by it.

5. Did It Change Anything?

I ran the same IaC review on the same SAM template, security pillar only, before and after.

With the default context: 12 recommendations. With mine: 7. I ran it twice and got 7 both times.

The ones that disappeared were account-level: log centralization, retention, a break-glass role, threat detection, incident response. My additional context says the account baselines are not part of this application. The agent seems to have taken that literally.

I cannot prove that sentence was the cause. I changed the whole context at once. And the two runs with my context shared only 5 of their 7 themes, so a single run has noise in it.

6. What I Would Do

• Replace the default. Write what the app is in plain words.
• Scope with a tag, not with services alone.
• Set criticality to what the app really is.
• Be careful with exclusions. If you say something is out of scope, say where it is covered. Otherwise you may just lose those recommendations.

Check your profile. If the only context is "Default Application", the agent knows which accounts to look at and nothing about what is in them.