Well-Architected Agent CLI: Multi-Account Setup

The console wizard is fine for a demo, but nobody wants to click through role creation in twelve accounts. This walkthrough onboards the Well-Architected Agent CLI way: IAM roles, an agent profile spanning multiple accounts, goals, application context, an eligibility check, and your first look at recommendations. Every command here is copy-pasteable, and you can wrap the whole thing in a script once it works.

Prerequisites

• An AWS Support plan of Business+, Enterprise On-Ramp, Enterprise or Unified Operations on the profile account. Developer and plain Business do not qualify (support plans).
• A recent AWS CLI v2 that includes the agent commands under aws wellarchitected. Check with aws wellarchitected help | grep agent.
• Admin-level IAM access in one “profile account” and in each workload account you want analyzed (up to 100 per profile).
• A profile Region of us-east-1, us-east-2 or us-west-2. Workloads can live in any commercial Region.
• Optional: a CloudFormation, Terraform or CDK project to review in step 9.

Keep the API quickstart open in a tab; it is the reference this tutorial follows.

Onboard accounts with the Well-Architected Agent CLI

Set a few variables first. Replace the account IDs with your own.

export PROFILE_ACCT=111122223333
export WORKLOAD_ACCT=444455556666
export AWS_REGION=us-east-1

1. Create the execution role in the profile account. The agent service assumes this role. Use the service-role/ path so the ARN matches what the console would create.

   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 \
     --role-name ExecutionRoleForWellArchitectedAgent \
     --path /service-role/ \
     --assume-role-policy-document file://exec-trust.json
   
   cat > exec-assume.json <<'EOF'
   {"Version":"2012-10-17","Statement":[{"Effect":"Allow",
    "Action":"sts:AssumeRole",
    "Resource":"arn:aws:iam::*:role/AccessRoleForWellArchitectedAgent"}]}
   EOF
   
   aws iam put-role-policy \
     --role-name ExecutionRoleForWellArchitectedAgent \
     --policy-name AssumeAccessRoles \
     --policy-document file://exec-assume.json

   Compare against the getting started guide in case AWS adds permissions during preview.

2. Create the access role in each workload account. It trusts the execution role and gets the read-only managed policy WellArchitectedAgentResourceScanning. Run this with credentials for the workload account.

   cat > access-trust.json <<EOF
   {"Version":"2012-10-17","Statement":[{"Effect":"Allow",
    "Principal":{"AWS":"arn:aws:iam::${PROFILE_ACCT}:role/service-role/ExecutionRoleForWellArchitectedAgent"},
    "Action":"sts:AssumeRole"}]}
   EOF
   
   aws iam create-role \
     --role-name AccessRoleForWellArchitectedAgent \
     --assume-role-policy-document file://access-trust.json
   
   POLICY_ARN=$(aws iam list-policies --scope AWS \
     --query "Policies[?PolicyName=='WellArchitectedAgentResourceScanning'].Arn" \
     --output text)
   
   aws iam attach-role-policy \
     --role-name AccessRoleForWellArchitectedAgent \
     --policy-arn "$POLICY_ARN"

   For more than a couple of accounts, put this in a CloudFormation template and push it with StackSets.

3. Create the agent profile. Back in the profile account. The aggregation configuration lists each workload account, its access role and the Regions to scan.

   aws wellarchitected create-agent-profile \
     --name platform-prod \
     --execution-role-arn arn:aws:iam::${PROFILE_ACCT}:role/service-role/ExecutionRoleForWellArchitectedAgent \
     --pillars COST_OPTIMIZATION SECURITY RESILIENCE PERFORMANCE \
     --aggregation-configuration "[{\"accountId\":\"${WORKLOAD_ACCT}\",\"accessRoleArn\":\"arn:aws:iam::${WORKLOAD_ACCT}:role/AccessRoleForWellArchitectedAgent\",\"regions\":[\"us-east-1\",\"us-west-2\"]}]"

   Each entry in the aggregation array is one workload account, so adding accounts later is just a longer JSON list. Keep the list in a file under version control rather than in shell history; at 100 accounts per profile, it gets long fast. Copy the profile ARN from the output into a variable.

   export PROFILE_ARN="arn:aws:wellarchitected:...paste-from-output..."

4. Add goals. One pillar per goal, written in plain text. Be specific: numbers and dates rank better than vibes. A goal like “improve security” gives the agent nothing to sort by, while a concrete target lets it push the relevant findings to the top.

   aws wellarchitected create-agent-goal \
     --profile-arn "$PROFILE_ARN" \
     --title "Reduce EC2 spend by 20% by Q4 without raising p99 latency" \
     --pillars COST_OPTIMIZATION
   
   aws wellarchitected create-agent-goal \
     --profile-arn "$PROFILE_ARN" \
     --title "Payment services survive the loss of one Availability Zone" \
     --pillars RESILIENCE

5. Describe the application context. This is required. Criticality, accounts and Regions tell the agent what matters.

   aws wellarchitected create-agent-context \
     --profile-arn "$PROFILE_ARN" \
     --title "Payment processing service" \
     --context-type APPLICATION \
     --content "{\"applicationOverview\":\"Card authorization API on ECS behind an ALB, Aurora PostgreSQL backend\",\"criticality\":\"MISSION_CRITICAL\",\"accountIds\":[\"${WORKLOAD_ACCT}\"],\"regions\":[\"us-east-1\"]}"

6. Optional: enable resource-level cost data. In the Cost Explorer console preferences, turn on resource-level daily granularity so savings figures reflect your actual rates instead of list price. It has its own charges and is sticky once on, so read Cost Explorer pricing first. Verify it works:

   aws ce get-cost-and-usage-with-resources \
     --time-period Start=2026-10-01,End=2026-10-11 \
     --granularity DAILY --metrics UnblendedCost \
     --filter '{"Dimensions":{"Key":"SERVICE","Values":["Amazon Elastic Compute Cloud - Compute"]}}' \
     --group-by Type=DIMENSION,Key=RESOURCE_ID

7. Check eligibility. Do not wait a day to find a typo.

   aws wellarchitected get-agent-profile \
     --profile-arn "$PROFILE_ARN" \
     --query '{eligible: eligibleForScheduledGeneration, errors: fieldErrors}'

   If eligible is false, read errors. The usual suspects: a missing application context, an access role ARN without the right account ID, or a trust policy pointing at an execution role ARN missing service-role/.

8. Wait for the first generation. The user guide says within 24 hours; the API reference says up to 48. Meanwhile, confirm the access role can be assumed from the profile account side by checking CloudTrail in the workload account.

   aws cloudtrail lookup-events \
     --lookup-attributes AttributeKey=EventName,AttributeValue=AssumeRole \
     --max-results 20 \
     --query "Events[?contains(CloudTrailEvent, 'AccessRoleForWellArchitectedAgent')].EventTime"

9. Run an architecture review on IaC. Zip your CloudFormation, Terraform or CDK project and either upload it in the console or stage it in S3 and point the review at the S3 URI.

   cd infra && zip -r ../payments-iac.zip . -x '.terraform/*' 'cdk.out/*' && cd ..
   aws s3 cp payments-iac.zip s3://my-wa-reviews-${PROFILE_ACCT}/payments/payments-iac.zip

   Pick the pillars or lens to review against in the console. Architecture recommendations can come back with updated templates.

10. Read and act on recommendations. Resource, application and architecture recommendations appear in the Well-Architected console under your profile. For updated templates, download them and diff before anything ships.

    unzip updated-templates.zip -d review-out
    diff -ru infra/ review-out/ | less
    git checkout -b wa-agent-fixes && cp -r review-out/* infra/ && git diff --stat

    Open a pull request and review it like any other change. The agent is read-only and the output is generative, so a human signs off.

What you built

You now have a cross-account trust chain (execution role to read-only access roles), an agent profile scanning a workload account in two Regions, goals that drive prioritization, and an application context that tells the agent what is mission-critical. You also have a repeatable path to review IaC before deployment.

Next steps: template steps 1 and 2 with StackSets, add more accounts to the aggregation configuration, and write a goal per pillar you care about. The concepts page covers the object model in more depth.

Cleanup, if this was a sandbox: delete the agent profile in the console or CLI, then aws iam detach-role-policy and aws iam delete-role for the access role in each workload account, aws iam delete-role-policy and delete-role for the execution role, and empty the S3 bucket. Remember that Cost Explorer granular data stays on once enabled.

At Enkompass (enkompass.net), this is our home turf. We build cross-account IAM and StackSets rollouts for AWS Organizations and run Well-Architected programs that turn findings into shipped fixes. 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.