On this page:

Search Universal Agent topics:

The Universal Agent provides a central management point for administering runtime agents for diverse application environments and eases the management of large environments. The Universal Agent automates the tasks of installing, running, and maintaining AppDynamics runtime agents, such as the Machine Agent and Java Agent.

After you set up the Universal Agent, you can update the versions of the runtime agents by putting new distributions in the repository and updating the configuration with the new version. To further ease agent management in large and dynamic environment, the Universal Agent configuration supports remote JVM attachment and dynamic node naming. This topic describes how to set up and use the Universal Agent.

About the Universal Agent

The Universal Agent enables you to run and manage AppDynamics runtime agents by using a single configuration file, called a rulebook. The rulebook determines whether the Universal Agent installs, starts, and stops runtime agents. By default, the Universal Agent runs in controller mode and applies a shared rulebook stored and served by the Controller. Alternatively, you can run the Universal Agent in local mode, in which it uses a rulebook (stored in the Universal Agent home directory) that is specific to the instance of the agent. See Universal Agent Rulebooks for more details on operation modes.

When the Universal Agent finds a new rule for a runtime agent in the rulebook, it retrieves the runtime agent from a common repository, installs the agent as a local monitor, and starts the agent. You can manage multiple runtime agents on a single host, which allows for having different versions of the runtime agents for each JVM or for each host in your environment. 

Supported Environments 

The Universal Agent is available on Linux and Windows and supports deployment and management of the following runtime agents:

Some Universal Agent features (such as automatic JVM attachment and dynamic rulebook value propagation) have additional requirements and limitations, which are discussed in the feature documentation.   

Set Up Tasks

To use the Universal Agent you need to do the following tasks:

  1. Set up the runtime agent source repository as either a Controller repository or file system repository. A file system repository would typically be on a shared repository accessible to the Universal Agent host machines. 
  2. Install the Universal Agent on the machines to be monitored. 
  3. Create the rulebooks to manage your runtime agent instances. 

Getting Started

The following procedures walk you through the three set-up tasks for a simple scenario using a single Linux-based application server with an on-premises Controller. On Linux, these steps require sudo access to the application server machine, because the Universal Agent is installed as a service. 

When following these steps, adjust the values in the commands for your specific Controller, user, account, and so on.

Set up the runtime agent source repository

This procedure sets up a Controller source repository.

  1. Confirm that you have an on-premises Controller installed and running and you have access to the Controller machine. 
  2. On the controller, create the <controller_home>/agent_binaries directory. This serves as your Controller source repository for the runtime agent binaries.
  3. Put the Universal Agent ZIP file in the directory.
  4. Rename it to universalagent-
  5. Download the Machine Agent ZIP file to the Controller source repository, <controller_home>/agent_binaries directory.
  6. Rename the Machine Agent file to machine-
  7. Continue to the next section to install the Universal Agent.
Install the Universal Agent on the machines to be monitored
  1. Get the account key for your Controller: 

    1. From the Controller UI, open the License page and click the Accounts tab.
    2. Click the link to show the key. 
  2. From the application server machine, get the Universal Agent distribution. You can use the following cURL command to get the Universal Agent from the Controller repository.
    Replace the controller user, account, password, Controller host address and port with values for your system. The user should be an account in the Controller UI that has Universal Agent administration permissions. Replace account_access_key with your own key.

    curl -u '<controller-user>@<controller-account>:<controller-password>' -X POST -d 'action=downloadAgent&agentVersion=' -o ua4.3.0.0.zip 'http://<controller_host>:<primaryport>/controller/FileDownloadServlet'
    mkdir ua_install
    unzip ua4.3.0.0.zip -d ua_install/
    sudo ./ua_install/ua4.3.0.0/bin/install.sh --account_access_key <account_access_key>

    By default, the script installs the agent in /opt/appdynamics/universal-agent/. You can change that using the -target argument, but the steps (below) for creating your rulebooks assume the default installation location, /opt

Create the rulebook
  1.  From the application server machine (where the Universal Agent is installed) Execute a REST API command against your Controller to add  a single default rulebook.
    Replace controller-user, controller-account, controller-password, controller-host, and controller-port with the values for your Controller. 

    curl -i -X PUT -su '<controller-user>@<controller-account>:<controller-password>' -H "Content-type: application/json" -H "Accept:application/json"\
            "http://<controller-host>:<controller-port>/controller/universalagent/v1/user/rulebooks/byName/default-controller" --data '{
            "name": "default-controller",
            "comments": "An example rule book with a rule to start a machine agent monitor",
            "rules": [
                "config": {
                    "state": "started",
                    "version": ""
                "monitor": "machine",
                "comments": "This is a Machine rule",
                "condition": "True",
                "name": "Machine monitor"
                "name": "Unified Agent rule",
                "comments": "Unified Agent rule",
                "monitor": "universal",
                "config": {
                    "version": "",
                    "state": "started"
                "condition": "True"

    In the JSON rules, line indentation is important. Make sure that any new rules match the indentation style in the existing rules.

  2. After a few moments, verify that the Universal Agent retrieved and installed the Machine Agent. The machine agent files should now appear in the following directory:
  3. Check the status of the Universal Agent as reported to the Controller using the REST API, universalagent/v1/user/agents/summary. For instance, using cURL, enter the following command:

    curl -s -X GET -u 'appdadmin@customer1:welcome' -H 'Content-type: application/json' http://appd.sample.com:8090/controller/universalagent/v1/user/agents/summary

    Replace the username, password, and Controller address with values appropriate for your environment. The response should list the running agents with the version number and applied rulebook for each.