Agent Lifecyle Management¶
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 “vpkg” 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 vpkg <Agent Dir>
.
For instance: vpkg 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
vpkg 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¶
vctl 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:
vctl 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:
vctl remove <AGENT_UUID>
vctl remove --tag <AGENT_TAG>
vctl 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:
vctl 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: vctl run <PACKAGE>
.
Agent Status¶
olttron-
| vctl list
lists the agents installed on the platform and their priority
| The vctl status
shows the list of installed agents and whether they are running or have exited.
| See AgentStatus for more details.