SPADE: a Python multi-agent platform that routes agent traffic over XMPP

The problem SPADE solves: agents that need identities and presence, not just function calls

Most Python agent code starts as a function that returns a string, then grows a loop, then grows a queue, and eventually someone asks how agent A finds agent B on another machine. SPADE answers that question by refusing to invent an answer. Each agent is an XMPP client with a Jabber ID, and the platform inherits from instant messaging what a hand-rolled framework has to build: addressing, presence, message delivery and large file transfer. The README describes it as a multi-agent systems platform written in Python and based on instant messaging (XMPP), and the feature list names presence notification as the mechanism that lets the system know the current state of agents in real time. That is the specific gap it fills. If your agents are long-lived processes that come and go, and other agents need to know when they are online, presence is the part you would otherwise write yourself. The audience is therefore narrower than the phrase multi-agent systems suggests: researchers and developers building distributed agent experiments, simulations with agents spread over hosts, or systems where a human chat client should be able to message an agent directly, since the README states agents can chat both with other agents and humans.

Behaviour model, asyncio and the XMPP substrate

The architecture visible in the material is three layers. At the bottom, XMPP carries the messages. SPADE ships a custom XMPP server (PyJabber) but the feature list also says you can use any XMPP server, so the server is a dependency you can substitute rather than a fixed component. In the middle, the agent runtime is asyncio-based and Python >=3.10, which sets the concurrency model: agents are coroutines on an event loop, not threads. At the top, the agent model is based on behaviours. This is the part worth understanding before writing code, because it determines how you structure logic. You do not write a while loop that polls a mailbox; you register behaviour objects with an agent, and the runtime schedules them. FIPA metadata is supported through XMPP Data Forms (XEP-0004), which is how structured fields such as conversation identifiers travel inside messages. Large file share goes over HTTP via XEP-0363 rather than through the message channel, so sending a payload does not mean base64-encoding it into a stanza. There is also a web-based interface listed among the features. The repository layout reflects the plugin strategy: spade_bdi, spade_pubsub, spade_artifact, spade_norms and spade_bokeh live in separate repositories with their own documentation sites, so the core package stays small and the optional semantics (belief-desire-intention agents, publish-subscribe, artifacts, norms, plotting) are installed only when needed.

Installing SPADE and what the documentation gives you

The material here does not include the installation commands, so I am not going to invent a pip invocation and present it as verified. What is confirmed: the package is on PyPI (the README carries a PyPI version badge and a downloads badge), the license is MIT, and the supported Python is >=3.10. The documented entry points are the official site at spadeagents.eu, with a latest documentation path and a develop path, plus legacy docs on readthedocs that the README labels temporary. That last detail matters operationally: if you find an older tutorial, check which of the three documentation trees it belongs to before trusting an API name, because the project is mid-transition between documentation hosts and between the 4.1.x and 5.0.0 lines. The plugin ecosystem has its own docs, one site per plugin, and each plugin is a separate repository, so a version mismatch between core and plugin is a real possibility you should test rather than assume. Code size, language count and coverage badges appear in the README but tell you nothing about whether the behaviour API suits your design, so read the behaviour documentation before writing a prototype.

Where SPADE is the wrong tool

The clearest limitation follows from the design itself: XMPP is not optional in spirit even if the server is swappable. If your agents run inside one process, or you want a library that embeds a single LLM call chain into an existing web application, SPADE adds an account model, a server, and a stanza protocol to a problem that does not have a routing problem. The presence feature that justifies the design is dead weight there. Second, a 5.0.0b1 beta exists alongside 4.1.4 and 4.1.3 releases, which means the project is actively changing its major line; pinning matters more than usual, and a plugin built against 4.1.x may not track the beta. Third, the asyncio requirement is a constraint, not a preference: blocking calls inside a behaviour will stall the loop, and the material gives no indication of a thread-based fallback. Fourth, the README is a feature list, not a tutorial. It names XEP-0004 and XEP-0363 and links the specifications, but it does not show the code that uses them, so expect to read the external docs and the XMPP extensions themselves. Finally, the custom PyJabber server is a convenience for getting started; the README does not describe its operational limits, so I cannot tell you how it behaves under load, and you should not assume it replaces a production XMPP deployment.

Compared with a plain asyncio message bus

The obvious alternative for many readers is not another agent framework but the asyncio primitives already in the standard library: queues, tasks and a dictionary of agent objects. The difference is not sophistication, it is topology. A queue-based design keeps every agent in one interpreter and one address space, so discovery is a dictionary lookup, presence is a boolean you set yourself, and there is no wire format to debug. SPADE trades that simplicity for distribution: agents get network identities, can run on different hosts, and can be reached by a human using a normal XMPP client. You also inherit solved problems instead of writing them: file transfer over HTTP via XEP-0363, structured metadata via XEP-0004 data forms, and presence as a protocol-level signal rather than an application convention. The cost is a server to run or connect to, a protocol to understand when messages do not arrive, and an event loop you must not block. If your agents never leave one process, the queue wins. If they need to be addressed, discovered and observed from outside, SPADE is doing work you would otherwise do badly.

Maintenance, versioning and what MIT means here

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That is a statement about the licence text, not legal advice; if you ship SPADE inside a product, read the licence file and your own compliance requirements. The maintenance picture from the material is a project that is alive but in transition. The last push is recent, and releases arrive in a steady pattern: 4.1.3, then 5.0.0b1, then 4.1.4, which shows the stable line still receiving fixes while a beta major version is being prepared. The upgrade cost is concentrated in two places. First, the core behaviour API across a major version boundary, which you should verify against the develop documentation rather than the legacy site. Second, the plugin boundary: spade_bdi, spade_pubsub, spade_artifact, spade_norms and spade_bokeh are separate repositories with separate release cycles, so a core upgrade can outpace them. Pin the core version in your dependency file, and test the plugin you depend on against that pinned version before upgrading. The documentation split (official site, develop path, temporary legacy readthedocs) is itself a maintenance cost: expect to check which tree a given page belongs to.

Who should adopt SPADE, and what to confirm first

Adopt SPADE when your problem is genuinely distributed: agents on multiple hosts, agents that need to be discovered and observed, or agents that a person should be able to message from an XMPP client. The presence mechanism, the FIPA metadata support and the HTTP file transfer are the concrete reasons to choose it over a hand-rolled asyncio bus. Do not adopt it for a single-process agent pipeline, and do not adopt it if you cannot accept an XMPP server as part of your deployment, because the server is the substrate, not a detail. Before you commit, verify three things against the actual documentation at spadeagents.eu rather than the legacy readthedocs tree: which installation path applies to your Python version (the README confirms >=3.10 but not the commands), whether the behaviour API you plan to use matches the 4.1.x line or the 5.0.0 beta, and whether the plugin you need has a release that tracks your pinned core version. Do that verification on a two-agent prototype that exchanges one message and one file, because message delivery and file transfer are exactly the two paths where an XMPP misconfiguration shows up first.

Editorial conclusion

Adopt SPADE if your agents need to talk to each other and to humans across machines or organisations, and you are willing to run or connect to an XMPP server. Do not adopt it if your agents are a single-process pipeline, or if you cannot accept XMPP as your transport. Before committing, verify which of the two documented installation paths works for your environment, and check whether the plugin you need (spade_bdi, spade_pubsub, spade_artifact, spade_norms, spade_bokeh) is maintained against the 4.1.x line or the 5.0.0 beta.

Official sources

1. Issues
2. javipalanca/spade on GitHub
3. License: MIT
4. README
5. Releases