AgentDevelopment

Agent Creation Walkthrough

It is recommended that developers look at the ListenerAgent before developing their own agent. That agent expresses the basic functionality this example with walk through and being familiar with the concepts will be useful.

Created Folders

In the Agents directory, create a new folder TestAgent
In TestAgent, create a new folder tester, this is the package where our python code will be created

Create Agent Code

In tester, create a file called "__init__.py" which tells Python to treat this folder as a package
In the tester package folder, create the file agent.py
Create a class called TestAgent
- Import the packages and classes we will need:

import sys

from volttron.lite.agent import BaseAgent, PublishMixin
from volttron.lite.agent import utils, matching
from volttron.lite.messaging import headers as headers_mod

- This agent will extend BaseAgent to get all the default functionality
- Since we want to publish we will use the PublishMixin. Mixins should be put first in the class definition

class TestAgent(PublishMixin, BaseAgent):

We don't need to add anything to the BaseAgent init method so we will not create our own

Setting up a Subscription

We will set our agent up to listen to heartbeat messages (published by ListenerAgent). Using the matching package, we declare we want to match all topics which start with "heartbeat/listeneragent". This will give us all heartbeat messages from all listeneragents but no others.

    @matching.match_start('heartbeat/listeneragent')
    def on_heartbeat_topic(self, topic, headers, message, match):
           print "TestAgent got\nTopic: {topic}, {headers}, Message: {message}".format(topic=topic, headers=headers, message=message)

Argument Parsing and Main

Our agent will need to be able to parse arguments being passed on the command line by the agent launcher. Use the utils.default-main method to handle argument parsing and other default behavior. Create a main method which can be called by the launcher.

def main(argv=sys.argv):
    '''Main method called by the eggsecutable.'''
    utils.default_main(TestAgent,
                       description='Test Agent',
                       argv=argv)


if __name__ == '__main__':
    # Entry point for script
    try:
        sys.exit(main())
    except KeyboardInterrupt:
        pass

Create Support Files for Agent

Volttron-Lite agents need some configuration files for packaging, configuration, and launching.

Packaging Configuration

In the TestAgent folder, create a file called "setup.py" (or copy the setup.py in ListenerAgent) which we will use to create an eggsecutable. This file sets up the name, version, required packages, method to execute, etc. for the agent. The packaging process will also use this information to name the resulting file.

from setuptools import setup, find_packages

packages = find_packages('.')
package = packages[0]

setup(
    name = package + 'agent',
    version = "0.1",
    install_requires = ['volttronlite'],
    packages = packages,
    entry_points = {
        'setuptools.installation': [
            'eggsecutable = ' + package + '.agent:main',
        ]
    }
)

Launch Configuration

In TestAgent, create a file called "testagent.launch.json". This is the file the platform will use to launch the agent. It can also contain configuration information for the agent.

For TestAgent,

{
    "agent": {
        "exec": "testeragent-0.1-py2.7.egg --config \"%c\" --sub \"%s\" --pub \"%p\""
    },
    "agentid": "Test1",
    "message": "hello"    
}

Packaging Agent

The agent code must now be packaged up for use by the platform. The build-agent.sh script will build the eggsecutable package using the setup.py file we defined earlier.

From the project directory: "volttron/scripts/build-agent.sh TestAgent".

This creates an egg file in the Agents directory which, along with the launch configuration file, would be sent to a deployed platform for installation. For local testing, you may need to change permissions on the file: "chmod +x Agents/testeragent-0.1-py2.7.egg"

Testing the Agent

From the Command Line

With the platform running, execute the following steps:

Start the platform by running "bin/volttron-lite -c dev-config.ini -l volttron.log -vv&"
Install the executable into the platform: "bin/volttron-ctrl install-executable Agents/testeragent-0.1-py2.7.egg"
Load the agent configuration file: "bin/volttron-ctrl load-agent Agents/TestAgent/testagent.launch.json"
Launch the agent by running "bin/volttron-ctrl start-agent testagent.launch.json"
Check that it is running: "bin/volttron-ctrl list-agents"
Check the log file for messages: "tail volttron.log"

In Eclipse

If you are working in Eclipse, create a run configuration for TestAgent based on the ListenerAgent configuration in EclipseDevEnvironment.
Launch the platform
Launch the TestAgent
Launch the ListenerAgent

TestAgent should start receiving the heartbeats from ListenerAgent