Besides inheriting from the
Agent-class there is another option to integrate features into an agent: the role API.
The idea of using roles is to divide the functionality of an agent by responsibility in a structured way. The target of this API is to increase the reusability and the maintainability of the agents components. To achieve this the role API works with orchestration rather than inheriting to extend the agents features.
The role context is the API to the environment of the role. It provides functionality to interact with other roles, to send messages to other agents or simply to fetch some meta data.
To implement a role you have to extend the abstract class
mango.Role. Concrete instances of implementations can be assigned to the general
The first step in the roles life is the instantiation via
__init__. This is done by the user itself and can be used to configure the roles behavior. The next step is adding the role to a
add_role. The role will get notified by this through the method
setup. After adding the role the
RoleContext is available, which represents the environment (container, agent, other roles). When the role or agent got removed, or the container shut down, the hook-method
on_stop will be called, so you can do some cleanup or send last messages before the life ends.
After a shutdown or removal a role is not supposed to be reused! When you want to deactivate a role temporarily use the methods
deactivate of the RoleContext.
As in a normal agent implementation, roles can handle incoming messages. To add a message handler you can use
RoleContext.subscribe_message. This method expects, besides the role and a handle method, a message condition function. The handle method must have exactly two arguments (excl.
meta. The condition function must have exactly one argument
content. The idea of the condition function is to allow to define a condition filtering incoming messages, so you only handle one type of message per handler. Furthermore you can define a
priority of the message subscription, this will be used to determine the message dispatch order (lower number = earlier execution, default=0).
... class MyRole(Role): def setup(self): self.context.subscribe_message(self, self.handle_ping, lambda content: isinstance(content, Ping)) def handle_ping(self, content, meta): print('Ping received!')
Deactivate/Activate other Roles¶
Sometimes you might want to deactivate the functionality of a whole role, for example when you entered a new coalition you don’t want to accept new coalition invites. It would of course be possible to manage this case with shared data and controlling flags, but this requires a lot of additional code and might lead to errors when implementing it. Furthermore, it increases the complexity of the implemented roles. To tackle this scenario a native deactivation/activation of roles is possible in mango. To deactivate a role the method
RoleContext.deactivate can be used. To activate it again, use
RoleContext.activate. When a role is deactivated
it is not possible to handle messages anymore
the role will not get updates on shared models anymore
all scheduled tasks get suspended.
When a role activated again all three point are completely reverted.
Suspending of tasks might not work immediately, as it intercepts