The agent module bundles the agent daemon and a couple code modules needed to run it. The agent itself is meant to be extended by plugins using the clacks.common.components.plugin.Plugin interface. When starting up the system, the agent looks for plugins in the setuptools system and registers them into to the clacks.common.components.registry.PluginRegistry. The same happens for objects in clacks.common.components.objects.ObjectRegistry.

After the PluginRegistry is ready with loading the modules, it orders them by priority and tries to determine whether it is

  • an ordinary plugin
  • an interface handler

Modules marked with the IInterfaceHandler interface provide a serve method which is instantly called in this case. Modules like i.e. a AMQP handler or an HTTP service can start their own threads and start processing what ever they need to process. When the service shuts down, the method stop is called and the module has the chance to cleanly shut down the process.

The agent is now in a state where it enters the main loop by sending AMQP NodeStatus events from time to time, joining threads and waiting to be stopped.

To provide real services an ordinary agent will load a couple of modules exposing functionality to the outside world. Here are some of them:

This happens automatically depending on what’s registered on the [agent.module] setuptools entrypoint.

The agent will send a NodeLeave event when shutting down.

If you’re looking for documentation on how to write plugins, please take a look at the Plugin section.

Using the binary

The clacks-agent binary gets installed when you run the setup process. It has a couple of command line arguments:

$ clacks-agent --help
usage: clacks-agent - the clacks core daemon

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -c FILE, --config FILE
                        read configuration from FILE [/etc/clacks]
  --url URL             AMQP broker URL
  --profile             write profiling information [False]


Take a look at the quickstart to see how the agent is controlled.

For production environments, just start the agent using the supervisor package.