aiomas.agent — aiomas 0.2.0 documentation

# `aiomas.agent`

This module implements the base class for agents (`Agent`) and containers for agents (`Container`).

Every agent must live in a container. A container can contain one ore more agents. Containers are responsible for making connections to other containers and agents. They also provide a factory function for spawning new agent instances and registering them with the container.

Thus, the `Agent` base class is very light-weight. It only has a name, a reference to its container and an RPC router (see `aiomas.rpc`).

class `aiomas.agent.` `Container`(addr, codec=None, clock=None)

  Container for agents.

  It can instantiate new agents via `spawn()` and can create connections to other agents (via `connect()`).

  In order to destroy a container and close all of its sockets, call `shutdown()`.

  When a container is created, it also creates a server socket and binds it to addr which is a `('host', port)` tuple (see the host and port parameters of `asyncio.BaseEventLoop.create_server()` for details).

  You can optionally also pass a codec instance (`JSON` or `MsgPack` (default)). Containers can only “talk” to containers using the same codec.

  To decouple a multi-agent system from the system clock, you can pass an optional clock object which should be an instance of `BaseClock`. This makes it easier to integrate your system with other simulators that may provide a clock for you or to let your MAS run as fast as possible. By default, `AsyncioClock` will be used.

  `spawn`(agent_type, *args, **kwargs)

    Create an instance of agent_type, passing a reference to this container, a name and the provided args and kwargs to it.

    This is equivalent to `agent = agent_type(container, name, *args, **kwargs)`, but also registers the agent with the container.

  `connect`(url)

    Connect to the argent available at url and return a proxy to it.

    url is a string `agent://<host>:<port>/<agent-name>`.

    If the remote agent belongs to a different container than the connecting agent, return a `aiomas.rpc.Proxy` (which performs remote procedure calls via TCP sockets). If the remote agent lives in the same containers as the connecting agent, return a `LocalProxy` (which uses direct method calls and no networking). Both proxy types have the same behavior and raise a `RemoteException` if an exception is raised in the remote methods.

  `get_url_for`(agent)

    Return the agent URL for agent.

  `shutdown`(async=False)

    Close the container’s server socket and the RPC services for all outgoing TCP connections.

    If async is left to `False`, this method calls `asyncio.BaseEventLoop.run_until_complete()` in order to wait until all sockets are closed.

    If the event loop is already running when you call this method, set async to `True`. The return value then is a coroutine that you need to `yield from` in order to actually shut the container down:

        yield from container.shutdown(async=True)

class `aiomas.agent.` `Agent`(container, name)

  Base class for all agents.

  `rpc`

    Descriptor that creates an RPC `Router` for every agent instance.

    You can override this in a sub-class if you need to. (Usually, you don’t.)

  `container`

    The `Container` that the agent lives in.

  `name`

    The agent’s name. It is formatted like an agent URL and can usually (but not necessarily) be used to connect to this agent.

class `aiomas.agent.` `LocalProxy`(obj, path)

  Proxy for local objects and functions.

  It has the same interface as the actual `Proxy` but directly calls the proxied methods instead of sending messages over the network.