View a markdown version of this page

Implement recommendations in AWS Well-Architected Agent - AWS Well-Architected
Remediation modelsRun SSM Runbook for remediationStarting guided remediationFollowing the guided SOPDownloading the complete SOPCompleting remediation

AWS Well-Architected Agent is in preview release and is subject to change.

Implement recommendations in AWS Well-Architected Agent

AWS WA Agent provides multiple implementation options including automated remediation through AWS Systems Manager, self-service guided actions, and human-in-the-loop support available with Premier Support plans.

Remediation models

AWS WA Agent uses two remediation models depending on how the recommendation was generated:

  • SSM Runbook automation: Recommendations derived from AWS Trusted Advisor checks have pre-built SSM Runbooks. These are deterministic, tested automation that can be run directly or scheduled for recurring execution. AWS WA Agent can trigger one-click remediation on your behalf with your consent.

  • Guided actions (AI-generated): Recommendations generated by the AWS WA Agent AI engine (resource, application, and architecture types) include step-by-step guided actions. These may include AWS CLI commands, SDK code, console walkthroughs, or updated IaC templates. Guided actions are advisory and should be reviewed before execution.

Important

AWS WA Agent does not execute AI-generated remediation steps on your behalf. AI-generated guided actions are provided for your review and validation. You are responsible for reviewing, testing, and executing these steps in your environment. This follows the AWS shared responsibility model for AI-generated content.

Run SSM Runbook for remediation

When a prescheduled auto remediation is not configured for a recommendation, you can view the SSM Runbook details and run the SSM Runbook for remediation.

To use automated remediation

  1. Navigate to the specific recommendation details page.

  2. Go to the "prescheduled auto-remediation" section, if available.

  3. Review the SSM Runbook details including schedule and next run time.

  4. Choose the SSM Runbook.

  5. Choose Execute SSM runbook to run the automation immediately.

  6. Monitor the execution status and results.

Starting guided remediation

After reviewing a recommendation, choose Start remediation to begin a guided remediation workflow. AWS WA Agent generates a step-by-step standard operating procedure (SOP) tailored to the specific resources in your environment. The SOP is resource-aware: each step references actual resource names and ARNs from your account rather than generic placeholders.

To start remediation

  1. On the recommendation detail page, choose Start remediation.

  2. Select a remediation method:

    • Using AWS Management Console: Step-by-step console navigation instructions.

    • Using AWS CLI: AWS CLI commands you can copy and run.

    • Using SDK: SDK code (Python/boto3) you can adapt and execute.

AWS WA Agent generates a phased SOP for the selected method. Each method produces a different SOP with instructions appropriate to that tool. For example, the console SOP walks you through UI navigation, while the CLI SOP provides ready-to-run commands.

Following the guided SOP

The remediation view is organized into three panels:

  • Left panel (phases): Lists all phases in the SOP (for example, Phase 1 of 10, Phase 2 of 10). The current phase is highlighted. Phase titles describe the action (for example, "Enable S3 Bucket Keys for the CloudTrail logs bucket").

  • Center panel (instructions): Detailed instructions for the current phase. Depending on the remediation method, this may include console navigation steps, CLI commands with copy buttons, or SDK code snippets.

  • Right panel (resources): Links to relevant AWS documentation for the current phase.

To progress through the SOP:

  • Choose Mark as complete to record that you have finished the current phase, then choose Next to advance.

  • You can navigate to any phase by selecting it in the left panel.

  • Phases are specific to your resources. For example, if a recommendation affects four S3 buckets, the SOP includes a separate phase for each bucket, referencing it by name.

Typical SOP phases include:

  1. Prerequisites (verify tool installation, credentials)

  2. Per-resource remediation steps (one or more phases per affected resource)

  3. Verification (confirm the change took effect)

  4. Documentation (record changes for compliance and audit)

Important

Remediation SOPs are generated using AWS generative AI capabilities and may contain errors or incomplete information. Recommendations might contain information related to security, a nuanced topic. You are responsible for evaluating the recommendation in your specific context and implementing appropriate oversight and safeguards. Review all steps before executing in production. For more information about AWS Responsible AI practices, see https://aws.amazon.com/ai/responsible-ai/policy/.

Downloading the complete SOP

Choose Download complete SOP to export the full procedure for the currently selected remediation method. The download contains all phases, commands, and resource references in a single document.

Each remediation method (Console, CLI, SDK) has its own downloadable SOP. Switch methods using the radio buttons at the top of the remediation page to download the version you need.

Downloaded SOPs are useful for:

  • Offline execution in environments without console access

  • Attaching to change management tickets for approval

  • Handing off implementation to another team member

  • Archiving as a record of the remediation procedure

Completing remediation

Console

After completing all phases, choose Mark recommendation as complete at the top of the remediation page. The recommendation moves to your archived recommendations. If the underlying condition recurs in a future refresh cycle, AWS WA Agent generates a new recommendation.

CLI

To mark a recommendation as complete:

aws wellarchitected update-agent-recommendation-status \
    --recommendation-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/my-profile/recommendation/rec-id" \
    --status COMPLETED

To suppress a recommendation:

aws wellarchitected update-agent-recommendation-status \
    --recommendation-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/my-profile/recommendation/rec-id" \
    --status SUPPRESSED \
    --update-reason "Not applicable to our environment"

To reopen a previously closed recommendation:

aws wellarchitected update-agent-recommendation-status \
    --recommendation-arn "arn:aws:wellarchitected:us-east-1:111122223333:agent-profile/my-profile/recommendation/rec-id" \
    --status ACTIVE