AgentManagement

The VOLTTRON platform has several commands for controlling the lifecycle of agents. This page discusses how to use them, for details of operation please see PlatformConfiguration

These examples assume the VOLTTRON environment has been activated (. env/bin/activate). If not, add "bin/" to all commands.

Agent Packaging

The "volttron-pkg" command is used for packaging and configuring agents. It is not necessary to have the platform running to use this command. The platform uses Python Wheel for its packaging and follows the Wheel naming convention.

To create an agent package, call volttron-pkg <Agent Dir>.

For instance: volttron-pkg package examples/ListenerAgent

The package command uses the setup.py in the agent directory to create the package. The name and version number portion of the Wheel filename come from this. The resulting wheels are created at "~/.volttron/packaged".

For example: ~/.volttron/packaged/listeneragent-3.0-py2-none-any.whl.

Agent Configuration

Agent packages are configured with the volttron-pkg configure <AgentPackage> <ConfigFile> command. It is suggested that this file use json formatting but the agent can be written to interpret any format it requires. The configuration of a particular agent is opaque to the VOLTTRON platform. The location of the agent config file is passed as an environmental variable "AGENT_CONFIG" which the provided utilities read in and pass to the agent.

An example config file passing in some parameters:

{

    "agentid": "listener1",
    "message": "hello"    
}

Agent Installation and Removal

Agents are installed into the platform using: volttron-ctl install <package>. When agents are installed onto a platform, it creates a uuid for that instance of an agent. This allows multiple instances of the same agent package to be installed on the platform.

Agents can also be installed with a tag by using:

volttron-ctl install <TAG>=<PACKAGE>

This allows the user to refer to the agent with "--tag " instead of the uuid when issuing commands. This tag can also distinguish instances of an agent from each other.

A stopped agent can be removed with:

• volttron-ctl remove <AGENT_UUID>
• volttron-ctl remove --tag <AGENT_TAG>
• volttron-ctl remove --name <AGENT_NAME>

Removal by tag and name potentially allows multiple agents to be removed at once and should be used with caution. A "-f" option is required to delete more than one agent at a time.

Agent Control

Starting and Stopping an Agent

Agent that are installed in the platform can be launched with the "start" command. By default this operates off the agent's UUID but can be used with "--tag" or "--name" to launch agents by those attributes. This can allow multiple agents to be started at once. For instance: volttron-ctl start --name myagent-0.1 would start all instances of that agent regardless of their uuid, tag, or configuration information. After an agent is started, it will show up in AgentStatus as "running" with a process id.

Similarly, volttron-ctl stop <UUID> can also operate off the tag and name of agent(s). After an agent is stopped, it will show an exit code of 0 in AgentStatus

Running an agent

For testing purposes, an agent package not installed in the platform can be run by using: volttron-ctl run <PACKAGE>.

Agent Status

volttron-ctl list lists the agents installed on the platform and their priority The volttron-ctl status shows the list of installed agents and whether they are running or have exited. See AgentStatus for more details.