AWS Builder Center

Setting Up AWS DevOps Agent for Multi-Account Monitoring with AWS CLI

Learn how to deploy AWS DevOps Agent across multiple AWS accounts using a programmatic CLI approach. This comprehensive guide demonstrates creating cross-account monitoring with the "Optimus Prime" agent space, covering IAM role setup, cross-account permissions, and MCP server integration. Perfect for enterprise environments requiring automated incident response across account boundaries.

Senior Technical Account Manager (Sr. TAM) @ Amazon Web Services (AWS)
Today, I'll walk you through setting up AWS DevOps Agent across multiple AWS accounts using the AWS CLI. This approach gives you programmatic control and enables automation of your DevOps Agent deployment, perfect for organizations managing complex multi-account architectures.
AWS DevOps Agent is a frontier agent that acts as your always-on, autonomous on-call engineer. When production incidents occur, it automatically correlates data across your operational toolchain, identifies probable root causes, and recommends targeted mitigations. What makes this setup particularly powerful is the ability to monitor resources across multiple AWS accounts from a single Agent Space.

Why Multi-Account DevOps Agent Setup?

In enterprise environments, applications often span multiple AWS accounts for security, compliance, and organizational boundaries. A single DevOps Agent Space can monitor:
  • Production account - Your live workloads
  • Development/staging accounts - Pre-production environments
  • Shared services accounts - Common infrastructure components
  • Security/logging accounts - Centralized monitoring and compliance

Prerequisites

Before we begin, ensure you have:
  • AWS CLI installed and configured
  • Administrative access to all target AWS accounts
  • DevOps Agent CLI model installed
  • Appropriate IAM permissions in each account

Step 1: Install and Configure DevOps Agent CLI

First, let's set up the DevOps Agent CLI extension:
# Download the DevOps Agent service model
curl -o devopsagent.json https://d1co8nkiwcta1g.cloudfront.net/devopsagent.json

# Add the service model to AWS CLI
aws configure add-model --service-model "file://${PWD}/devopsagent.json" --service-name devopsagent

# Verify installation
aws devopsagent help


Step 2: Create IAM Roles for Multi-Account Access

Primary Account (Monitoring Account) Setup

In your primary monitoring account (e.g., 123456789012), create the main DevOps Agent role:
# Create trust policy for the Agent Space role
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": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:aidevops:us-east-1:123456789012:agentspace/*"
}
}
}
]
}
EOF

# Create the Agent Space role
aws iam create-role \
--region us-east-1 \
--role-name DevOpsAgentRole-AgentSpace \
--assume-role-policy-document file://devops-agentspace-trust-policy.json

# Attach AWS managed policy
aws iam attach-role-policy \
--role-name DevOpsAgentRole-AgentSpace \
--policy-arn arn:aws:iam::aws:policy/AIOpsAssistantPolicy


Create Operator App Role

# Create operator app role for web interface access
aws iam create-role \
--role-name DevOpsAgentRole-WebappAdmin \
--assume-role-policy-document file://devops-agentspace-trust-policy.json \
--region us-east-1

# Attach operator permissions
cat > devops-operator-inline-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowBasicOperatorActions",
"Effect": "Allow",
"Action": [
"aidevops:GetAgentSpace",
"aidevops:GetAssociation",
"aidevops:ListAssociations",
"aidevops:InvokeAgent",
"aidevops:ListRecommendations",
"aidevops:GetRecommendation"
],
"Resource": "arn:aws:aidevops:us-east-1:123456789012:agentspace/*"
}
]
}
EOF

aws iam put-role-policy \
--role-name DevOpsAgentRole-WebappAdmin \
--policy-name AIDevOpsBasicOperatorActionsPolicy \
--policy-document file://devops-operator-inline-policy.json


Step 3: Create Agent Space

Let's create our multi-account Agent Space for comprehensive monitoring:

Multi-Account Agent Space

# Create Optimus Prime for comprehensive multi-account monitoring
aws devopsagent create-agent-space \
--name "Optimus Prime" \
--description "Multi-account monitoring with MCP integration" \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1

Save the  agentSpaceId  from the response - you'll need it for subsequent steps.

Step 4: Configure Multi-Account Access

Set Up Cross-Account Roles

For each secondary account (e.g., 987654321098), create a cross-account role:
# Switch to secondary account context
aws configure --profile AWSAdministratorAccess-987654321098

# Create cross-account trust policy
cat > devops-cross-account-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "arn:aws:aidevops:us-east-1:123456789012:agentspace/YOUR_AGENT_SPACE_ID"
}
}
}
]
}
EOF

*Note: Replace YOUR_AGENT_SPACE_ID with the actual agent space ID from Step 3*

# Create cross-account role in secondary account
aws iam create-role \
--role-name DevOpsAgentCrossAccountRole-OptimusPrime \
--assume-role-policy-document file://devops-cross-account-trust-policy.json \
--profile AWSAdministratorAccess-987654321098

# Attach required policies
aws iam attach-role-policy \
--role-name DevOpsAgentCrossAccountRole-OptimusPrime \
--policy-arn arn:aws:iam::aws:policy/AIOpsAssistantPolicy \
--profile AWSAdministratorAccess-987654321098


Update Primary Account Permissions

# Add cross-account assume role permissions to primary account
cat > devops-cross-account-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::987654321098:role/DevOpsAgentCrossAccountRole-OptimusPrime"
}
]
}
EOF

aws iam put-role-policy \
--role-name DevOpsAgentRole-AgentSpace \
--policy-name DevOpsAgentCrossAccountAccess-OptimusPrime \
--policy-document file://devops-cross-account-policy.json


Step 5: Associate Accounts with Agent Spaces

Associate Primary Account

# Associate monitoring account
aws devopsagent associate-service \
--agent-space-id YOUR_AGENT_SPACE_ID \
--service-id aws \
--configuration '{
"aws": {
"assumableRoleArn": "arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace",
"accountId": "123456789012",
"accountType": "monitor",
"resources": []
}
}' \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1


Associate Secondary Account

# Associate source account for cross-account monitoring
aws devopsagent associate-service \
--agent-space-id YOUR_AGENT_SPACE_ID \
--service-id aws \
--configuration '{
"sourceAws": {
"accountId": "987654321098",
"accountType": "source",
"assumableRoleArn": "arn:aws:iam::987654321098:role/DevOpsAgentCrossAccountRole-OptimusPrime",
"resources": []
}
}' \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1


Step 6: Enable Operator App and MCP Integration

Enable Web Interface

# Enable operator app for team access
aws devopsagent enable-operator-app \
--agent-space-id YOUR_AGENT_SPACE_ID \
--auth-flow iam \
--operator-app-role-arn "arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin" \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1


Integrate MCP Server

# Associate event channel for webhook integration
aws devopsagent associate-service \
--agent-space-id YOUR_AGENT_SPACE_ID \
--service-id SERVICE_ID \
--configuration '{"eventChannel": {"shouldUpdateWebhook": true}}' \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1

Note: Replace SERVICE_ID with the actual service ID from  aws devopsagent list-services 

Step 7: Verification and Management

Verify Setup

# List all agent spaces
aws devopsagent list-agent-spaces \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1

# Check associations for specific agent space
aws devopsagent list-associations \
--agent-space-id YOUR_AGENT_SPACE_ID \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1

# Get detailed agent space information
aws devopsagent get-agent-space \
--agent-space-id YOUR_AGENT_SPACE_ID \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1


Architecture Overview

Our final setup includes:

Agent Space Created:

Optimus Prime - Comprehensive multi-account monitoring with MCP integration

Account Configuration:

  • Primary Account (123456789012): Monitoring account with DevOps Agent roles
  • Secondary Account (987654321098): Source account with cross-account access roles

Integration Points:

  • Event Channel MCP Server: Webhook integration for external event processing
  • Operator Web App: Team access through IAM authentication
  • Cross-Account Monitoring: Seamless resource discovery across account boundaries

Benefits of CLI-Based Setup

Using AWS CLI for DevOps Agent setup provides several advantages:
  1. Automation: Scripts can be version-controlled and automated in CI/CD pipelines
  1. Consistency: Identical setup across environments and accounts
  1. Scalability: Easy to replicate across multiple accounts and regions
  1. Integration: Seamless integration with existing infrastructure-as-code workflows
  1. Auditability: All configuration changes are tracked and reproducible

Best Practices

Security Considerations

  • Use least-privilege IAM policies
  • Implement cross-account roles with external ID conditions
  • Regularly rotate access keys and review permissions
  • Monitor cross-account access patterns

Operational Excellence

  • Organize Agent Spaces by application or team boundaries
  • Use descriptive naming conventions for roles and policies
  • Implement proper tagging strategies for resource management
  • Set up monitoring for Agent Space activities

Cost Optimization

  • Monitor Agent Space usage during preview period
  • Plan for production pricing when service becomes generally available
  • Optimize resource discovery scope to reduce unnecessary API calls

Troubleshooting Common Issues

Cross-Account Role Assumption Failures

# Check role trust policy
aws iam get-role --role-name DevOpsAgentCrossAccountRole-OptimusPrime

# Verify external ID in trust policy matches agent space ARN
# Wait for IAM propagation (up to 60 seconds) before retrying associations


Service Association Errors

# List available services
aws devopsagent list-services \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1

# Check service-specific configuration requirements
aws devopsagent get-service \
--service-id SERVICE_ID \
--endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \
--region us-east-1


What's Next?

With your multi-account DevOps Agent setup complete, you can:
  1. Start Investigations: Use the web app to manually trigger investigations
  1. Configure Webhooks: Set up automatic incident response from monitoring tools
  1. Integrate Additional Services: Add GitHub, ServiceNow, Datadog, or other observability tools
  1. Expand Monitoring: Add more AWS accounts to your existing Agent Spaces
  1. Automate Deployment: Create CloudFormation or Terraform templates based on these CLI commands

Conclusion

AWS DevOps Agent's multi-account capabilities, combined with CLI-based setup, provide a powerful foundation for enterprise-scale incident response and system reliability. The programmatic approach ensures consistent, repeatable deployments while the multi-account architecture enables comprehensive monitoring across your entire AWS infrastructure.
As organizations continue to adopt complex multi-account strategies, having an autonomous agent that can correlate data and identify issues across account boundaries becomes increasingly valuable. The CLI-based setup approach ensures you can scale this capability efficiently across your entire organization.
Try AWS DevOps Agent today in the US East (N. Virginia) Region and experience how autonomous incident response can transform your operational efficiency.


AWS DevOps Agent is currently in preview and available at no charge with usage limits. Visit the  AWS DevOps Agent documentation  for the latest information and updates.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article