This content applies solely to Appian RPA, which must be purchased separately from the Appian base platform.

What is an agent?

The agent is a software component you install on the resource so it can communicate with the server. The agent must be running on the resource in order to execute a robotic process, so the resource has access to the data it needs to get started. You can also start a robotic process execution directly on the resource using the agent.

This page covers the steps to set up the agent and use it to monitor activity on the connected resource.

To set up the agent, you'll need to:

  1. Configure the resource
  2. Download the agent
  3. Launch the agent
  4. Check the agent is running

Configuring the resource

You can deploy, configure, and execute robotic process on one or several resources. A resource is a PC or virtual machine where robotic processes are executed. Resources require an agent be installed and running in order to execute a robotic process.

You can create a virtual machine in the leading virtualization systems, such as Citrix, VMware or VirtualBox, to use as a resource and execute robotic processes.

To download the agent, first add the resource in the Appian RPA console. You should create a resource entry for each resource you plan to connect to.

Be sure to add the resources to your Appian environment's firewall allow list, if applicable. The robotic process may not be able to execute successfully if the firewall blocks communication between the agent, resource, and server.

Choose a user

Before you launch the agent on the resource, be sure you sign in as the proper OS user. The agent will have the same privileges on the resource as the OS user you're using when you launch the agent.

For example, if you plan to use a virtual machine and want the agent to connect as needed, you should sign in as an administrator to launch the agent. The agent will need administrator privileges to unblock a locked session in order to run the robotic process on the resource.

Additionally, the agent may need administrator privileges to work with files on the resource, as well as access the web driver for browser actions. See the FAQ for more information.

Download the agent

You'll download the agent in the Appian RPA console from an available resource. To make setup easier, we recommend that you carry out the following steps on the resource where you wish to install the agent.

Install and run only one agent per resource. The agent executable file is associated with the resource entry in the Appian RPA console. This file can only be used on one resource. When you download the agent, any previously installations of the same agent are invalidated. There should be only one agent executable file per directory.

  1. Open the Appian RPA console.
  2. Go to the Resources tab.
  3. In the list, find and click the resource where you are installing the agent.
  4. In the upper right-hand corner, click Download client 951068.png.
  5. If you're not working on the resource already, copy the AppianRPAagent.exe file to the resource after it has finished downloading.
  6. Save the agent in an empty folder that's easy to access. For example, you could use the folder C:\AppianRPA on a Windows OS.

Launch the agent

To launch the agent on a resource, Java 8 or higher must be installed. If it is not installed, consult the Manual Configuration topic.

If you're using a Windows-based resource, download the .msi Java installer from the Oracle website to install on your resource. The .msi installer sets the Windows registry keys that the agent uses to determine if the correct version of Java is installed. The agent won't be able to detect the Java version if you use another installation file or package.

If you can't install JVM, it is possible to make the agent work using a version downloaded and located beside the agent itself. In this case, contact the Appian support team so they can provide a resource adapted to your needs.

To launch the agent on Windows:

  1. Navigate to the resource. It's recommended to log in as an administrator when you launch the agent to prevent connection disruptions in the future.
  2. Go to the folder where the agent is located.
  3. Open the file to launch the agent.
  4. Once the agent has started correctly, the Appian icon shows up in the taskbar.

You can check that the agent is running from the resource and the console.

To launch the agent on Mac or Linux:

  1. Navigate to the resource. It's recommended to log in as an administrator when you launch the agent to prevent connection disruptions in the future.
  2. Open the terminal.
  3. Change the location to the directory where you downloaded the agent.
  4. Grant permissions to the agent file using the command: chmod +x
  5. Run the file using the command ./
  6. Keep this terminal window open to maintain the connection to the console.

Check the agent is running

To check that the agent is running on the resource, look at the taskbar. The agent icon color appears blue when the agent is connected to the console.


You can also select Element inspector in the menu to check whether the connection is established or not.

To check that the agent is running on the console, go to the Resources tab. The resource's status is Online if the agent is properly connected and running.

Once the resource is configured, the agent is running and ready to execute robotic processes.

Agent menu

To view the agent's menu, right-click on the agent icon. You'll see a number of options.



The Robots menu lists robotic processes available for this resource. Click on a robotic process to execute it. You should only run robotic processes that do not have required input variables on their setup. If you launch a robotic process with required input variables in this way, the process won't run properly because it doesn't have the variables it needs to begin the execution.

Element inspector

The Element inspector shows information to help you develop your robotic process.


The Element inspector is a tool that shows detailed information about the application elements with which your robotic processes are going to interact (buttons, text fields, menus, etc.). The information provided is different depending on your robotic process's development strategy: keyboard commands, Windows API, image recognition, etc.

Additionally, this tool informs you of the connection status of the resource with the server, the position of the mouse pointer on the screen, and information about the active windows and controls. This window is very helpful for finding out the position of any control that your robotic process needs to interact with.

Your robotic processes can interact with Windows controls using their IDs, which the element inspector provides. To get the ID, place your mouse over the control on the active window. The ID appears in the Control > Identifier area of the element inspector. You can use the ID to reference that control from a robotic process and use it to read or enter data.

IDs may vary depending on the operating system version. Make sure you are running your robotic process in resources that use the same operating system version as the one used for its development.

Protect desktop

The Protect desktop option allows you to protect the desktop where the agent is running. This option obscures the screen so no one can see what's happening during execution. The window that appears covering the screen is an "invisible" window. If a user right-clicks on the screen, they would see the desktop menu.

To disable this window, click in the zone where the taskbar should be. When the taskbar appears, click on the agent again to deactivate desktop protection.

Create support image

You can use the agent to capture images and send them to robotic processes that will use them as support files.

Learn more about this option on the Image Recognition module page.

Generate config file

The configuration file is optional. If one exists, it must be in the same folder as agent's executable file. Both the agent and the file must share the same name, ignoring the extensions: <name>.exe for the client, and <name>.l4j.ini for the file.

The purpose is to customize the agent's JVM with values that are unknown at the time of being used, or with values that are expected to change throughout the robotic process's life. The configuration file is basically a properties file, in which each property takes up one line with the same format as system properties definitions (-D\<name\>=\<value\>) when you launch a Java program from the command line.

The most common parameters used in this file include:

  • Debug in "Listen" mode:
    • -Xdebug
    • -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=[PORT]
  • Debug in "Attach" mode:
    • -Xdebug
    • -Xrunjdwp:transport=dt_socket,server=n,suspend=n,address=[X.X.X.X]:[PORT]
  • Most often used parameters for proxy connections:
    • -Dhttp.proxyUser=USER
    • -Dhttp.proxyPassword=PASSWORD (the password can be encrypted using the agent itself)
    • -Dhttp.proxyHost=DIRECTION_PROXY
    • -Dhttp.proxyPort=8080
  • Run the agent increasing its associated memory (for example, 1GB):
    • -Xmx1Gb

Password encryption

Select Password encryption in the menu to obtain a hash from a password in plain text. This enables you to include encrypted passwords in the jidoka.l4j.ini configuration file, if necessary. The agent can detect if it is an encrypted password and will process it accordingly, thus protecting sensitive information.

Agent directory hierarchy

When you launch a robotic process, the agent communicates with the server and downloads the libraries and artifacts needed for execution. This download is done only for the first execution of that robotic process, since at that time no library has been downloaded to the resource. In later executions, these libraries should be available on the resource, and they will be downloaded only if they are not found. The number of libraries to download depends on the dependencies and modules used during development.

It is important that the agent is in a folder whose full path has no blanks to prevent it from encountering any problem during a robotic process execution.

The directory hierarchy is described below, assuming the agent is in the folder C:\AppianRPA. Upon execution, the agent will create the correct files and folders within C:\AppianRPA and run the robotic process.

  • C:\AppianRPA: Resource's root directory. You will find certain files here that serve as activity log files of your robotic processes.
    • AppianRPAagent.exe: Agent's executable file.
    • .jidoka-cache: Libraries required for robotic process's executions.
    • Jidoka-workspace: Libraries and other files required by the robotic processes.
    • example: Specific support files for the robotic process "example".
    • anotherRobot: Specific support files for the robotic process "anotherRobot".
  • .jidoka-cache: The folder in which the necessary libraries for the robotic process's proper operation will be stored.
  • Jidoka-workspace: Folder containing the individual directories of each robotic process. Within the folder Jidoka-workspace, there will be as many subfolders as robotic processes have been executed in that resource. The folders use the robotic process's unique ID, consisting of letters and numbers. For example, a robot called abc123 will have an associated subfolder in C:\AppianRPA\Jidoka-workspace\abc123, which is the folder where all components required for its specific execution will be downloaded, and the files created during its execution will be stored. Appian RPA provides easy access to this folder programmatically.

Agent upgrade behavior

Whenever Appian RPA upgrades to the latest version, active agents do as well. During the upgrade process, you may see a concurrency warning in the Appian RPA console. This message is temporary and expected. If you see this warning during an upgrade, try back in a few minutes.

To ensure smoother and faster upgrades, Appian recommends resources have more than the minimum 2 GB RAM. View System Requirements to learn more about required Appian RPA configurations.

If the warning persists or you have other issues during an upgrade, contact Appian Support for help troubleshooting the issue.

Open in Github Built: Fri, Nov 04, 2022 (07:10:52 PM)

On This Page