Overview Prerequisites IAM roles setup Onboarding steps Verification Next steps Notes

AWS DevOps Agent CLI onboarding guide

Overview

With AWS DevOps Agent, you can monitor and manage your AWS infrastructure. This guide walks you through setting up AWS DevOps Agent by using the AWS Command Line Interface (AWS CLI). You create IAM roles, set up an agent space, and associate your AWS account. You also enable the operator app and optionally connect third-party integrations. This guide takes approximately 20 minutes to complete.

AWS DevOps Agent is available in six AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (Ireland). For more information about supported Regions, see Supported Regions.

Prerequisites

Before you begin, make sure that you have the following:

AWS CLI version 2 installed and configured
Authentication to your AWS monitoring account
Permissions to create AWS Identity and Access Management (IAM) roles and attach policies
An AWS account to use as the monitoring account
Familiarity with the AWS CLI and JSON syntax

Throughout this guide, replace the following placeholder values with your own:

<MONITORING_ACCOUNT_ID> — Your 12-digit AWS account ID for the monitoring (primary) account
<EXTERNAL_ACCOUNT_ID> — The 12-digit AWS account ID of the secondary account to monitor (used in step 4)
<REGION> — The AWS Region code for your agent space (for example, us-east-1 or eu-central-1)
<AGENT_SPACE_ID> — The agent space identifier that is returned by the create-agent-space command

IAM roles setup

1. Create the DevOps Agent space role

Create the IAM trust policy by running the following command:


cat > devops-agentspace-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

Create the IAM role:


aws iam create-role \
  --region <REGION> \
  --role-name DevOpsAgentRole-AgentSpace \
  --assume-role-policy-document file://devops-agentspace-trust-policy.json

Save the role ARN by running the following command:


aws iam get-role --role-name DevOpsAgentRole-AgentSpace --query 'Role.Arn' --output text

Attach the AWS managed policy:


aws iam attach-role-policy \
  --role-name DevOpsAgentRole-AgentSpace \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

Create and attach an inline policy to allow creation of the Resource Explorer service-linked role:


cat > devops-agentspace-additional-policy.json << 'EOF'
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Sid": "AllowCreateServiceLinkedRoles",
      "Effect": "Allow",
      "Action": [
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": [
        "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer"
      ]
    }
  ]
}
EOF

aws iam put-role-policy \
  --role-name DevOpsAgentRole-AgentSpace \
  --policy-name AllowCreateServiceLinkedRoles \
  --policy-document file://devops-agentspace-additional-policy.json

2. Create the operator app IAM role

Create the IAM trust policy by running the following command:


cat > devops-operator-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

Create the IAM role:


aws iam create-role \
  --role-name DevOpsAgentRole-WebappAdmin \
  --assume-role-policy-document file://devops-operator-trust-policy.json \
  --region <REGION>

Save the role ARN by running the following command:


aws iam get-role --role-name DevOpsAgentRole-WebappAdmin --query 'Role.Arn' --output text

Attach the AWS managed operator app policy:


aws iam attach-role-policy \
  --role-name DevOpsAgentRole-WebappAdmin \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy

This managed policy grants the operator app permissions to access agent space features. These features include investigations, recommendations, knowledge management, chat, and AWS Support integration. The policy scopes access to the specific agent space by using the aws:PrincipalTag/AgentSpaceId condition. For more information about the full list of actions, see DevOps Agent IAM permissions.

Onboarding steps

1. Create an agent space

Run the following command to create an agent space:


aws devops-agent create-agent-space \
  --name "MyAgentSpace" \
  --description "AgentSpace for monitoring my application" \
  --region <REGION>

Optionally, specify --kms-key-arn to use a customer managed AWS KMS key for encryption. You can also use --tags to add resource tags and --locale to set the language for agent responses.

Save the agentSpaceId from the response (located at agentSpace.agentSpaceId).

To list your agent spaces later, run the following command:


aws devops-agent list-agent-spaces \
  --region <REGION>

2. Associate your AWS account

Associate your AWS account to turn on topology discovery. Set the accountType to one of the following values:

monitor — The primary account where the agent space exists. This account hosts the agent and is used for topology discovery.
source — An additional account that the agent monitors. Use this type when you associate external accounts in step 4.


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "aws": {
      "assumableRoleArn": "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace",
      "accountId": "<MONITORING_ACCOUNT_ID>",
      "accountType": "monitor"
    }
  }' \
  --region <REGION>

3. Enable the operator app

Authentication flows can use IAM, IAM Identity Center (IDC), or an external identity provider (IdP). Run the following command to enable the operator app for your agent space:


aws devops-agent enable-operator-app \
  --agent-space-id <AGENT_SPACE_ID> \
  --auth-flow iam \
  --operator-app-role-arn "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin" \
  --region <REGION>

For IAM Identity Center authentication, use --auth-flow idc and provide --idc-instance-arn. For an external identity provider, use --auth-flow idp and provide --issuer-url, --idp-client-id, and --idp-client-secret. For more information, see Setting Up IAM Identity Center Authentication and Setting Up External Identity Provider (IdP) Authentication.

4. (Optional) Associate additional source accounts

To monitor additional accounts with AWS DevOps Agent, create an IAM cross-account role.

Create the cross-account role in the external account

Switch to the external account and create the trust policy. The MONITORING_ACCOUNT_ID is the main account that hosts the agent space that you set up in step 2. This configuration allows the AWS DevOps Agent service to assume a role in the secondary source accounts on behalf of the monitoring account.

Run the following command to create the trust policy:


cat > devops-cross-account-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>",
          "sts:ExternalId": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<AGENT_SPACE_ID>"
        }
      }
    }
  ]
}
EOF

Create the cross-account IAM role:


aws iam create-role \
  --role-name DevOpsAgentCrossAccountRole \
  --assume-role-policy-document file://devops-cross-account-trust-policy.json

Save the role ARN by running the following command:


aws iam get-role --role-name DevOpsAgentCrossAccountRole --query 'Role.Arn' --output text

Attach the AWS managed policy:


aws iam attach-role-policy \
  --role-name DevOpsAgentCrossAccountRole \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

Attach the inline policy to allow creation of the Resource Explorer service-linked role in the external account:


cat > devops-cross-account-additional-policy.json << 'EOF'
{
  "Version": "2012-10-17",		 	 	 		 	 	 
  "Statement": [
    {
      "Sid": "AllowCreateServiceLinkedRoles",
      "Effect": "Allow",
      "Action": [
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": [
        "arn:aws:iam::<EXTERNAL_ACCOUNT_ID>:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer"
      ]
    }
  ]
}
EOF

aws iam put-role-policy \
  --role-name DevOpsAgentCrossAccountRole \
  --policy-name AllowCreateServiceLinkedRoles \
  --policy-document file://devops-cross-account-additional-policy.json

Associate the external account

Switch back to your monitoring account, and then run the following command to associate the external account:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "sourceAws": {
      "accountId": "<EXTERNAL_ACCOUNT_ID>",
      "accountType": "source",
      "assumableRoleArn": "arn:aws:iam::<EXTERNAL_ACCOUNT_ID>:role/DevOpsAgentCrossAccountRole"
    }
  }' \
  --region <REGION>

5. (Optional) Associate GitHub

For instructions on registering GitHub through the console, see Connecting to CI/CD pipelines.

List the registered services:


aws devops-agent list-services \
  --region <REGION>

Save the <SERVICE_ID> for serviceType: github.

After you register GitHub in the console, associate GitHub repositories by running the following command:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "github": {
      "repoName": "<GITHUB_REPO_NAME>",
      "repoId": "<GITHUB_REPO_ID>",
      "owner": "<GITHUB_OWNER>",
      "ownerType": "organization"
    }
  }' \
  --region <REGION>

6. (Optional) Register and associate ServiceNow

First, register the ServiceNow service with OAuth credentials:


aws devops-agent register-service \
  --service servicenow \
  --service-details  '{
    "servicenow": {
      "instanceUrl": "<SERVICENOW_INSTANCE_URL>",
      "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<SERVICENOW_CLIENT_NAME>",
            "clientId": "<SERVICENOW_CLIENT_ID>",
            "clientSecret": "<SERVICENOW_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

Save the returned <SERVICE_ID>, then associate ServiceNow:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "servicenow": {
      "instanceUrl": "<SERVICENOW_INSTANCE_URL>"
    }
  }' \
  --region <REGION>

7. (Optional) Register and associate Dynatrace

First, register the Dynatrace service with OAuth credentials:


aws devops-agent register-service \
  --service dynatrace \
  --service-details '{
  "dynatrace": {
    "accountUrn": "<DYNATRACE_ACCOUNT_URN>",
    "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<DYNATRACE_CLIENT_NAME>",
            "clientId": "<DYNATRACE_CLIENT_ID>",
            "clientSecret": "<DYNATRACE_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

Save the returned <SERVICE_ID>, then associate Dynatrace. Resources are optional. The environment specifies which Dynatrace environment to associate with.


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "dynatrace": {
      "envId": "<DYNATRACE_ENVIRONMENT_ID>",
      "resources": [
        "<DYNATRACE_RESOURCE_1>",
        "<DYNATRACE_RESOURCE_2>"
      ]
    }
  }' \
  --region <REGION>

The response includes webhook information for integration. You can use this webhook to trigger an investigation from Dynatrace. For more information, see Connecting Dynatrace.

8. (Optional) Register and associate Splunk

First, register the Splunk service with BearerToken credentials.

The endpoint uses the following format: https://<XXX>.api.scs.splunk.com/<XXX>/mcp/v1/


aws devops-agent register-service \
  --service mcpserversplunk \
  --service-details '{
  "mcpserversplunk": {
    "name": "<SPLUNK_NAME>",
    "endpoint": "<SPLUNK_ENDPOINT>",
    "authorizationConfig": {
        "bearerToken": {
            "tokenName": "<SPLUNK_TOKEN_NAME>",
            "tokenValue": "<SPLUNK_TOKEN_VALUE>"
        }
      }
    }
  }' \
  --region <REGION>

Save the returned <SERVICE_ID>, then associate Splunk:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpserversplunk":  {
      "name": "<SPLUNK_NAME>",
      "endpoint": "<SPLUNK_ENDPOINT>"
    }
  }' \
  --region <REGION>

The response includes webhook information for integration. You can use this webhook to trigger an investigation from Splunk. For more information, see Connecting Splunk.

9. (Optional) Register and associate New Relic

First, register the New Relic service with API key credentials.

Region: Either US or EU.

Optional fields: applicationIds, entityGuids, alertPolicyIds


aws devops-agent register-service \
  --service mcpservernewrelic \
  --service-details '{
    "mcpservernewrelic": {
      "authorizationConfig": {
        "apiKey": {
          "apiKey": "<YOUR_NEW_RELIC_API_KEY>",
          "accountId": "<YOUR_ACCOUNT_ID>",
          "region": "US",
          "applicationIds": ["<APP_ID_1>", "<APP_ID_2>"],
          "entityGuids": ["<ENTITY_GUID_1>"],
          "alertPolicyIds": ["<POLICY_ID_1>"]
        }
      }
    }
  }' \
  --region <REGION>

Save the returned <SERVICE_ID>, then associate New Relic:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpservernewrelic":  {
      "accountId": "<YOUR_ACCOUNT_ID>",
      "endpoint": "https://mcp.newrelic.com/mcp/"
    }
  }' \
  --region <REGION>

The response includes webhook information for integration. You can use this webhook to trigger an investigation from New Relic. For more information, see Connecting New Relic.

10. (Optional) Register and associate Datadog

You must first register Datadog through the AWS DevOps Agent console by using the OAuth flow before you can associate it through the CLI. For more information, see Connecting DataDog.

List the registered services:


aws devops-agent list-services \
  --region <REGION>

Save the <SERVICE_ID> for serviceType: mcpserverdatadog.

Then associate Datadog:


aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "mcpserverdatadog": {
      "name": "Datadog-MCP-Server",
      "endpoint": "<DATADOG_MCP_ENDPOINT>"
    }
  }' \
  --region <REGION>

The response includes webhook information for integration. You can use this webhook to trigger an investigation from Datadog. For more information, see Connecting DataDog.

11. (Optional) Delete an agent space

Deleting an agent space removes all associations, configurations, and investigation data for that agent space. This action can't be undone.

To delete an agent space, run the following command:


aws devops-agent delete-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

Verification

To verify your setup, run the following commands:


# List your agent spaces
aws devops-agent list-agent-spaces \
  --region <REGION>

# Get details of a specific agent space
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

# List associations for an agent space
aws devops-agent list-associations \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

Next steps

To connect additional integrations, see Configuring capabilities for AWS DevOps Agent.
To learn about agent skills and capabilities, see DevOps Agent Skills.
To understand the operator web app, see What is a DevOps Agent Web App?.

Notes

Replace <AGENT_SPACE_ID>, <MONITORING_ACCOUNT_ID>, <EXTERNAL_ACCOUNT_ID>, <REGION>, and so on with your actual values.
For a list of supported Regions, see Supported Regions.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Creating an Agent Space

Creating a test environment