Build an AI DevOps Health Agent on AWS

Deploy an AI agent on AgentCore that audits your AWS infrastructure health.

Introduction

30 Second Summary

Imagine having a personal inspector who checks your cloud infrastructure for security gaps, wasted resources, and misconfigurations. Instead of manually clicking through dozens of AWS console pages, you could just ask an AI agent to do it for you.

In this project, you will build an AI DevOps Health Agent on Amazon Bedrock AgentCore that autonomously writes Python code to inspect your AWS resources, identifies issues, and delivers a structured health report with recommendations.

What You'll Build

An AI agent deployed on AgentCore that uses a code interpreter to execute boto3 calls against your live AWS account, then synthesizes findings into a severity-rated health report.

By the end of this project, you'll have:

  • A deployed AgentCore harness configured as a DevOps health specialist with a custom system prompt and code interpreter.
  • Read-only IAM permissions attached to the agent's execution role, following the principle of least privilege.
  • Full reasoning traces in CloudWatch showing every decision the agent made, every line of code it wrote, and every API result it processed.
  • Secret Mission: Have the agent generate a risk-scored JSON report and save it directly to S3.

Are there any prerequisites?

This project assumes basic Python familiarity and introductory AWS knowledge (navigating the console and understanding what IAM roles are). No prior experience with AI agents or AgentCore is needed.

Set Up Your AWS Account and AgentCore CLI

Before your AI agent can inspect cloud infrastructure, you need the foundation in place. That means an AWS account, proper credentials, and the CLI tools that let you deploy and manage agents from your terminal.

In this step, you will create an AWS account, install the AWS CLI and the AgentCore CLI, and enable access to Amazon Bedrock models.

In this step, get ready to:
  • Create an AWS account and configure IAM credentials.
  • Install Node.js and the AgentCore CLI.
  • Enable Bedrock model access for your agent.
Create an AWS account and configure IAM credentials

Your agent runs on AWS, so it needs an account with proper permissions to deploy resources.

  • Open your browser and navigate to https://aws.amazon.com.
  • Click Create an AWS Account and follow the sign-up process.
  • Sign in to the AWS Management Console once your account is ready.

Already have an AWS account?

Skip straight to creating an IAM user below. You do not need a new account.

Next, create an IAM user with the permissions needed to deploy AgentCore resources.

  • In the console search bar at the top, type IAM and select IAM from the results.
  • Click Users in the left sidebar.
  • Click Create user.
  • Enter a username (e.g. agentcore-admin) and click Next.
  • Select Attach policies directly.
  • Search for AdministratorAccess and check the box next to it.
  • Click Next, then Create user.

Why AdministratorAccess?

For a learning project, AdministratorAccess simplifies setup. AgentCore needs to create IAM roles, CloudFormation stacks, and CloudWatch resources during deployment.

In a production environment, you would use a more restrictive policy. For this project, broad access keeps you focused on the agent itself.

Now create access keys for this user so your terminal can authenticate.

  • Click on your new user's name to open their details.
  • Select the Security credentials tab.
  • Scroll down to Access keys and click Create access key.
  • Select Command Line Interface (CLI) as the use case.
  • Acknowledge the recommendation and click Next.
  • Click Create access key.
  • Copy both your Access key ID and Secret access key somewhere safe. You will not be able to see the secret key again.

Keep your keys safe

Never share your access keys or commit them to a code repository. Store them securely and only use them in the AWS CLI configuration.

Now install the AWS CLI so your terminal can talk to AWS.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal and press Enter to open it.
  • Check if the AWS CLI is already installed by running:
aws --version

✔️ I see a version number

The AWS CLI is ready. Move on to configuring your credentials below.

ⓧ Command not found

You need to install the AWS CLI. Follow the official instructions for your operating system.

macOS

  • Download the macOS installer from https://awscli.amazonaws.com/AWSCLIV2.pkg.
  • Open the downloaded .pkg file and follow the on-screen instructions.
  • Close and reopen your terminal, then run aws --version again to confirm installation.

Windows

  • Download the Windows installer from https://awscli.amazonaws.com/AWSCLIV2.msi.
  • Run the downloaded .msi file and follow the installer prompts.
  • Close and reopen your terminal, then run aws --version again to confirm installation.

Configure the AWS CLI with your IAM user's credentials by running:

aws configure

What does aws configure ask for?

The command prompts you for four values. Enter them as follows:

  • AWS Access Key ID: paste the access key ID you copied earlier.
  • AWS Secret Access Key: paste the secret access key you copied earlier.
  • Default region name: enter us-east-1.
  • Default output format: press Enter to accept the default (json).
  • Verify your configuration works by running:
aws sts get-caller-identity

You should see a JSON response containing your account ID, user ARN, and user ID.

Seeing an error about invalid credentials?

Double-check that you pasted the access key and secret key correctly with no extra spaces. Run aws configure again to re-enter them.

Also confirm you set the region to us-east-1 since AgentCore harness preview runs in US East (N. Virginia).

Help me troubleshoot my AWS CLI credentials

Install Node.js and the AgentCore CLI

The AgentCore CLI requires Node.js 20+ as a prerequisite. Let's check if you already have it.

  • Check your Node.js version by running:
node --version

✔️ I see version 20 or higher

Your Node.js version is compatible. Move on to installing the AgentCore CLI below.

ⓧ I see an older version

You need Node.js 20+ for the AgentCore CLI. Your current version is too old.

  • Visit https://nodejs.org/en/download and download the latest LTS installer for your operating system.
  • Run the installer and follow the prompts. It will replace your current version.
  • Close and reopen your terminal.
  • Run node --version again to confirm the version is 20 or higher.

ⓧ Command not found

Node.js is not installed on your system.

  • Visit https://nodejs.org/en/download and download the LTS installer for your operating system.
  • Run the installer and follow the prompts.
  • Close and reopen your terminal.
  • Run node --version to confirm it shows version 20 or higher.

With Node.js ready, install the AgentCore CLI from the preview channel.

  • Install the AgentCore CLI globally by running:
npm install -g @aws/agentcore@preview

What is the AgentCore CLI?

This is the command-line tool for creating, deploying, and managing AI agents on Amazon Bedrock AgentCore. The @preview tag installs the version that includes the managed harness feature (launched April 2026).

  • Verify the installation succeeded by running:
agentcore --version

You should see a version number printed in your terminal.

Command not found after installing?

If agentcore --version fails, your system may not have the global npm bin directory in its PATH.

  • Try closing and reopening your terminal.
  • If it still fails, run npm bin -g to find the global bin path, then add it to your PATH environment variable.

Help me fix my AgentCore CLI installation

Enable Bedrock model access

Your agent uses a foundation model hosted on Amazon Bedrock. You need to confirm your IAM user can invoke Bedrock models.

Now attach the Bedrock policy to your IAM user.

  • Return to the IAM console (search IAM in the top search bar).
  • Click Users, then click on your IAM user.
  • Select the Permissions tab.
  • Click Add permissions, then Attach policies directly.
  • Search for AmazonBedrockFullAccess and check the box next to it.
  • Click Add permissions.

Why don't I need to enable specific models?

The AgentCore harness defaults to Claude Sonnet 4.6 on Amazon Bedrock. With the AmazonBedrockFullAccess policy attached and correct AWS Marketplace permissions, the model auto-enables on first invocation.

You do not need to manually request access for individual models.

Your IAM user should now have both AdministratorAccess and AmazonBedrockFullAccess policies attached.

Your tools are installed and your credentials are configured. Next up, you will create and deploy your DevOps Health Agent on AgentCore.

Create and Deploy the DevOps Health Agent

Your AWS environment is configured and the AgentCore CLI is ready. Now it's time to create the actual agent that will inspect your infrastructure.

In this step, you'll scaffold an Amazon Bedrock AgentCore project, configure it as a DevOps health specialist with a custom system prompt, deploy it to AWS, and grant it read-only permissions to inspect your cloud resources.

In this step, get ready to:
  • Scaffold the HealthAgent project with the AgentCore CLI.
  • Configure the agent with a DevOps health system prompt and code interpreter tool.
  • Deploy the agent and attach read-only IAM permissions.
Scaffold the agent with a DevOps-focused configuration

The AgentCore CLI provides a scaffolding command that creates a project structure with all the configuration files your agent needs.

  • Create the HealthAgent project by running this command:
agentcore create --name HealthAgent --model-provider bedrock

What does this command do?

This scaffolds a new AgentCore project in your current directory. The --name flag sets your agent's identity to HealthAgent. The --model-provider bedrock flag tells AgentCore to use Amazon Bedrock for model inference, which defaults to Claude Sonnet 4.6.

  • Confirm the project files were created by running:
ls

You should see an agentcore/ folder and an app/ directory in the output.

What's inside the project?

The CLI creates three key items: agentcore/agentcore.json (your main agent configuration), agentcore/aws-targets.json (your AWS account and region settings), and the app/ directory for any custom application code.

Don't see the project files?

Make sure you ran the command from a directory where you have write permissions. Check that your AWS credentials are still valid by running aws sts get-caller-identity. If you see a credentials error, re-run aws configure to fix your access keys.

Help me troubleshoot why agentcore create is failing.

Configure the agent as a DevOps health specialist with code interpreter

Your project structure exists, but the agent doesn't have a personality or tools yet. You need to tell it what kind of agent it is and give it the ability to execute code.

The code interpreter tool lets the agent write and run Python code inside a secure microVM. This is how it will call AWS APIs using boto3 to inspect your infrastructure.

  • Add the harness configuration with a system prompt and code interpreter by running this command:
agentcore add harness --name HealthAgent --system-prompt "You are an AWS DevOps Health Agent. Your mission is to inspect AWS infrastructure and identify security issues, misconfigurations, cost waste, and operational risks. When asked to check infrastructure health, use the code interpreter to write and execute boto3 Python code that calls AWS APIs. Always use read-only API calls (Describe, List, Get). Never modify resources. Present findings as a structured health report with severity levels: CRITICAL, WARNING, INFO." --tools code-interpreter

What does this command do?

The --system-prompt flag gives your agent its identity and operating rules. It tells the agent to act as a DevOps health inspector, use only read-only API calls, and format findings with severity levels.

The --tools code-interpreter flag gives the agent access to a sandboxed execution environment. Each session runs in an isolated microVM with its own filesystem and shell, so the agent can safely write and execute boto3 code.

  • Deploy the agent to AWS by running:
agentcore deploy

What happens during deployment?

The CLI uses AWS CDK to synthesize and deploy CloudFormation resources. It creates an IAM execution role, provisions a microVM runtime endpoint, and configures CloudWatch logging. This takes 2-3 minutes.

Wait for the deployment to complete. You'll see progress output in your terminal as each resource is created.

  • Verify the deployment succeeded by running:
agentcore status

You should see your HealthAgent listed as deployed with its ARN displayed.

Deployment failed or timed out?

Check that your us-east-1 region is set correctly. Run aws configure get region to confirm. If you see a permissions error, verify your IAM user has AdministratorAccess attached. The deploy command needs permissions to create IAM roles, CloudFormation stacks, and CloudWatch log groups.

Help me fix my AgentCore deployment failure.

Add read-only AWS permissions to the agent's execution role

Your agent is deployed, but its execution role doesn't yet have permission to read your AWS resources. You'll attach the ReadOnlyAccess AWS managed policy, which grants read access to all services without the ability to modify or delete anything.

Why ReadOnlyAccess?

This follows the principle of least privilege. The agent needs to inspect your infrastructure using Describe, List, and Get API calls. ReadOnlyAccess grants exactly that, covering all AWS services, without any write or delete permissions. The agent can look at everything but change nothing.

  • Find your agent's execution role name by checking the output of agentcore status from the previous step. Look for the execution role ARN. The role name looks like AgentCore-HealthAgent-* (with a unique suffix).
  • Open the IAM console at https://console.aws.amazon.com/iam/.
  • In the left navigation pane, click **Roles**.Roles.
  • Search for your execution role name (starts with AgentCore-HealthAgent) and click on it.
  • Select the Permissions tab.
  • Click Add permissions, then choose Attach policies.
  • Search for ReadOnlyAccess in the search box.
  • Select the checkbox next to ReadOnlyAccess (the AWS managed policy).
  • Click Add permissions to attach the policy.

You should now see ReadOnlyAccess listed under the role's permissions alongside the AgentCore base policy.

Can't find the execution role?

Run agentcore status again and copy the full role ARN. The role name is the last segment after the final slash. Make sure you're looking at the IAM console in the us-east-1 region. IAM is global, but the role was created during deployment and should appear immediately.

Help me find my AgentCore execution role in IAM.

Your DevOps Health Agent is deployed and has the permissions it needs to inspect your infrastructure. Next up, you'll put it to work running real health checks against your AWS account.

Run Infrastructure Health Checks

Your agent is deployed, configured, and equipped with read-only access to your entire AWS account.

Now it is time to put the agent to work. You will give it natural language missions and watch it autonomously write boto3 Python code, execute it against your live infrastructure, and report back with structured findings.

In this step, get ready to:
  • Run a basic health check inspecting IAM users and S3 buckets.
  • Check Lambda function utilization for cost optimization.
  • Conduct a multi-turn deep dive session for security risk analysis.
Run a basic infrastructure health check

The first health check asks the agent to inspect two common security concerns: IAM users without MFA and S3 buckets with public access.

  • Invoke the agent with a security-focused prompt by running this command:
agentcore invoke --harness HealthAgent --session-id "$(uuidgen)" "Check my AWS infrastructure health. Start by listing all IAM users and checking if any have console access without MFA enabled. Then check if there are any S3 buckets with public access. Report your findings with severity levels."

What does this command do?

The agentcore invoke command sends your prompt to the deployed HealthAgent harness.

  • The --harness HealthAgent flag targets your specific agent.
  • The --session-id "$(uuidgen)" generates a unique session ID (at least 33 characters) so the agent gets its own isolated microVM environment.
  • The quoted text at the end is your natural language prompt telling the agent what to inspect.

Watch your terminal as the response streams in. The agent reasons through the task, writes boto3 code, executes it, and reports findings with CRITICAL, WARNING, and INFO severity levels.

Not seeing any output?

  • Confirm your agent is still deployed by running agentcore status. If it does not show as deployed, run agentcore deploy again.
  • Make sure your AWS credentials are still valid. Run aws sts get-caller-identity to check.
  • If the agent returns an error about permissions, verify that the ReadOnlyAccess policy is still attached to the execution role in IAM.

Still stuck? Help me troubleshoot why my AgentCore invoke command is not returning results.

Check resource utilization

Beyond security, the agent can also identify cost waste. This next check asks it to analyze Lambda functions for signs of being unused or over-provisioned.

  • Run a cost optimization check on your Lambda functions by running this command:
agentcore invoke --harness HealthAgent --session-id "$(uuidgen)" "Check for any Lambda functions in this account. For each one, check when it was last modified and its memory configuration. Identify any that look unused (not modified in over 90 days) or over-provisioned. Give me a cost optimization summary."

What will the agent do?

The agent writes code that calls the Lambda ListFunctions and GetFunction APIs. It checks the last-modified timestamp and memory allocation for each function, then applies logic to flag anything unused or wasteful.

If your account has no Lambda functions, the agent will report that it found zero functions. That is a valid result.

You should see the agent list each Lambda function (if any exist), analyze its configuration, and provide a cost optimization summary with actionable recommendations.

Seeing a permissions error?

  • The ReadOnlyAccess policy covers Lambda read APIs. If you see an access denied error, the policy may have been detached from the execution role.
  • Return to the IAM console and confirm the execution role (named like AgentCore-HealthAgent-*) still has ReadOnlyAccess attached.

Need more help? Help me fix a permissions error when my agent tries to call Lambda APIs.

Run a multi-turn deep dive session

So far, each invocation has been a standalone request. AgentCore also supports multi-turn sessions where the agent maintains context between messages.

By reusing the same session ID across two invocations, you can ask follow-up questions that build on the agent's previous findings.

  • Start a multi-turn session by asking the agent for a broad overview. Run this command:
agentcore invoke --harness HealthAgent --session-id "health-audit-session-001-abcdef12" "Give me an overview of all AWS services currently in use in this account. List each service and how many resources exist."

Why a fixed session ID?

Instead of $(uuidgen) which generates a new ID each time, you are using a fixed string here so you can reference the same session in the next command. The session ID must be at least 33 characters long.

AgentCore provisions a dedicated microVM for this session. Everything the agent discovers in this first call remains available for follow-up questions.

Wait for the agent to finish streaming its response. It will list all AWS services with active resources in your account.

  • Now ask a follow-up question using the same session ID. Run this command:
agentcore invoke --harness HealthAgent --session-id "health-audit-session-001-abcdef12" "Based on what you found, what are the top 3 security risks I should address first? Explain why each is a risk."

What is happening here?

Because you used the same --session-id value, the agent remembers what it found in the first invocation. It uses that context to prioritize security risks without needing to re-scan your account.

This multi-turn pattern is how production agents handle complex investigations. One broad scan followed by targeted drill-downs.

The agent should reference specific resources it found in the first invocation and explain why each one poses a security risk.

See the raw streaming events

Add --verbose to any invoke command to see the raw JSON events as they stream. This shows you exactly what the agent is thinking, what code it wrote, and what results it received.

Agent not referencing the first invocation?

  • Make sure both commands use the exact same session ID string. Even a single character difference creates a new session.
  • If you waited more than 15 minutes between invocations, the session's microVM may have timed out. The session will resume on the next call, but the agent might need to re-scan.
  • Verify you ran the first command successfully before running the follow-up.

Need help? Why is my AgentCore agent not maintaining context between invocations in the same session?

Your agent just autonomously wrote and executed real code against your live AWS infrastructure. Next up, you will peek behind the curtain and watch the agent's full reasoning chain in CloudWatch.

Monitor Agent Reasoning in CloudWatch

Your agent just audited real AWS infrastructure and delivered actionable recommendations. That is powerful on its own, but in production you also need to understand how the agent thinks.

Amazon Bedrock AgentCore automatically sends traces to CloudWatch every time your agent runs. These traces reveal what code the agent wrote, what API results it received, and how it synthesized its final report. In this step, you will explore those traces and then clean up all resources.

In this step, get ready to:
  • View reasoning traces in CloudWatch showing model decisions and code execution.
  • Examine token usage and latency metrics for your agent sessions.
  • Clean up all AgentCore resources to stop charges.
View the agent's reasoning traces

Every time your HealthAgent runs, AgentCore emits traces that record each reasoning step. These traces let you see exactly what boto3 code the agent generated and what results came back from your AWS account.

  • Return to the AWS Management Console and open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
  • Make sure your region is set to us-east-1 (N. Virginia) in the top-right corner.
  • In the left navigation pane, expand Application Signals.
  • Select Transaction Search.
  • Look for traces from your HealthAgent invocations. You should see entries corresponding to your health check, Lambda utilization check, and multi-turn session.
  • Click on a trace ID to open the full trace view.

Inside each trace you will see the complete decision chain: the model's reasoning, the code interpreter invocations, and the final synthesis step where the agent compiled its report.

What am I looking at in these traces?

Each trace shows a sequence of spans. A span represents one unit of work the agent performed.

  • Model reasoning spans show the prompt sent to Claude Sonnet 4.6 and the response it generated.
  • Code interpreter spans show the boto3 code the agent wrote and the output it received from your AWS account.
  • Synthesis spans show how the agent combined API results into a structured health report.

No traces showing up?

AgentCore traces are powered by OpenTelemetry and may take a few minutes to appear after invocation. If you do not see traces immediately, wait 2-3 minutes and refresh the page.

Examine token usage and performance

Understanding how many tokens your agent consumes per session helps you estimate costs and optimize prompts. AgentCore publishes metrics to a dedicated CloudWatch namespace.

  • In the CloudWatch console, select Metrics in the left navigation pane, then choose All metrics.
  • Search for the AgentCore metrics namespace. You will find metrics for session count, latency, duration, token usage, and error rates.
  • Compare the latency of your simple health check (Step 3, substep 1) against the multi-step Lambda utilization check (Step 3, substep 2).
  • Note the token usage difference. Complex multi-step queries use significantly more tokens because the agent reasons through multiple API calls.

Why do token counts matter?

Token usage directly drives your Bedrock inference cost. A simple query that checks one service might use a few hundred tokens, while a multi-turn deep dive could use thousands.

By reviewing these metrics you can identify prompts that are too expensive and refine them to be more targeted.

Clean up all resources

AgentCore bills per vCPU-second while the runtime is active. Now that you have explored your agent's traces, it is time to tear everything down.

  • Return to your terminal. Make sure you are inside your AgentCore project directory (the folder containing agentcore/agentcore.json).
  • Destroy all AgentCore resources by running this command:
agentcore destroy
  • When prompted, confirm the deletion.

What does this command do?

The agentcore destroy command removes all CloudFormation resources that the CLI created during deployment. This includes the AgentCore Runtime endpoint, the IAM execution role, and the CloudWatch log groups.

  • Verify that no deployments remain by running:
agentcore status

You should see that no active deployments exist. All AgentCore resources have been removed and no further charges will apply.

Destroy command failed?

If the command fails with a permissions error, make sure you are using the same AWS credentials (same IAM user) that deployed the agent originally. The CloudFormation stack can only be deleted by the account that created it.

If you see a stack stuck in DELETE_FAILED state, open the CloudFormation console, find the stack, and delete it manually with the option to skip failed resources.

Help me troubleshoot my agentcore destroy failure.

Secret mission

Generate a Risk-Scored Report and Save to S3

Your agent can read your infrastructure, but what if it could also write reports? In this bonus challenge, you will create an S3 bucket, grant the agent scoped write permissions, and prompt it to generate a risk-scored JSON health report saved directly to S3.

Clean Up Your Resources

Clean Up Your Resources

If you followed Step 3 or the Secret Mission through to the end, your cloud resources are already cleaned up. All that remains is deciding what to do with your local project files and the AgentCore CLI.

Cost warning

If you skipped the cleanup substep in Step 3 or the Secret Mission, your AgentCore Runtime endpoint may still be running. AgentCore bills per vCPU-second while the agent is active. Run agentcore destroy immediately from your project directory to stop all charges.

Resources you used:

  • AgentCore deployment (Runtime endpoint, IAM execution role, CloudFormation stack, CloudWatch log groups).
  • Local AgentCore project directory containing agentcore/agentcore.json, agentcore/aws-targets.json, and the app/ folder.
  • AgentCore CLI (@aws/agentcore npm global package).

Keep everything running

No action needed. Choose this if you want to reference your project files later or continue experimenting with the AgentCore CLI.

  • Your local project files remain on disk for reference.
  • The AgentCore CLI stays installed globally so you can scaffold new agents in the future.
  • Since agentcore destroy was already run, there are no ongoing cloud costs.

Pause - I'll come back to this later

AgentCore scales to zero when idle and the deployment was already destroyed during the project. There is no separate pause action for this service.

  • Your local project files are still on disk. You can redeploy at any time by running agentcore deploy from your project directory.
  • No ongoing costs accrue while the agent is not deployed.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow every step below.

  • If you have not already run agentcore destroy, do so now from your project directory to remove all cloud resources.
  • Delete your local project files. On macOS or Linux, run:
rm -rf ~/Desktop/HealthAgent
  • On Windows, run:
Remove-Item -Recurse -Force ~\Desktop\HealthAgent
  • Uninstall the AgentCore CLI by running:
npm uninstall -g @aws/agentcore
  • Verify no AgentCore resources remain by running:
agentcore status

You should see a "command not found" error (confirming the CLI is uninstalled) or a message confirming no active deployments.

That's a Wrap!

That's a Wrap!

Nice work! You just built and deployed a purpose-driven AI DevOps Health Agent on Amazon Bedrock AgentCore, one of the newest services on AWS.

Your agent autonomously wrote and executed real code to inspect your cloud infrastructure, delivered structured health reports, and gave you full observability into its reasoning chain.

You've learned how to:

  • Deploy an AI agent on Amazon Bedrock AgentCore that autonomously writes and executes boto3 code to inspect real AWS infrastructure.
  • Configure least-privilege IAM permissions so the agent can read but never modify your cloud resources.
  • Monitor the agent's full reasoning chain in CloudWatch, including traces, token usage, and code execution details.
  • Secret Mission: Generated a risk-scored JSON health report and saved it directly to S3 using scoped write permissions.

Ready to quiz yourself?