SPADE 3: Building BDI Multi-Agent Systems for Social Simulation in Python

Overview

SPADE (Smart Python Agent Development Environment) is an open-source multi-agent system (MAS) framework built on Python and the XMPP messaging protocol. Version 3 introduced a fully asynchronous architecture based on Python's asyncio, making it one of the most practical platforms for implementing Belief-Desire-Intention (BDI) agents in social simulation research. Unlike grid-based ABM tools such as Mesa or NetLogo, SPADE targets scenarios where agents must communicate, negotiate, and coordinate through structured message-passing — making it particularly well-suited for modeling social institutions, markets, and organizational behavior.

BDI Architecture in SPADE 3

The BDI cognitive model is the theoretical backbone of SPADE agents. Each agent maintains:

• Beliefs: a knowledge base representing the agent's current world-state (implemented as Python dictionaries or custom objects)
• Desires: high-level goals the agent wants to achieve
• Intentions: the active plans currently being executed to satisfy desires

In SPADE 3, agent behavior is decomposed into behaviours — reusable, composable units of logic that run concurrently within a single agent. The framework provides several built-in behaviour types:

This composable design allows a single agent to simultaneously run a perception loop, a negotiation protocol, and a reporting behaviour — mirroring the parallel cognitive processes of real social actors.

XMPP-Based Communication

SPADE's distinguishing feature is its use of XMPP (Extensible Messaging and Presence Protocol) as the agent communication layer. Each agent registers as an XMPP user (e.g., buyer_agent@localhost) and exchanges messages through a Jabber/XMPP server such as Prosody or ejabberd. Messages follow the FIPA ACL (Agent Communication Language) standard, supporting performatives such as INFORM, REQUEST, PROPOSE, ACCEPT-PROPOSAL, and REJECT-PROPOSAL.

This architecture provides several advantages for social simulation:

1. Distributed deployment: agents can run on separate machines, enabling large-scale distributed simulations
2. Interoperability: FIPA-compliant agents can interact with agents built in other frameworks (JADE, Jason)
3. Presence awareness: agents can detect when peers come online or go offline, enabling dynamic coalition formation
4. Asynchronous messaging: asyncio-native message handling eliminates blocking and scales to hundreds of concurrent agents

Practical Example: Bilateral Negotiation Protocol

The following illustrates a simplified contract-net protocol between a buyer and seller agent — a common pattern in market simulation studies:

import spade
from spade.agent import Agent
from spade.behaviour import CyclicBehaviour
from spade.message import Message

class SellerAgent(Agent):
    class OfferBehaviour(CyclicBehaviour):
        async def run(self):
            msg = await self.receive(timeout=10)
            if msg and msg.get_metadata("performative") == "REQUEST":
                reply = msg.make_reply()
                reply.set_metadata("performative", "PROPOSE")
                reply.body = "100"  # price offer
                await self.send(reply)

    async def setup(self):
        self.add_behaviour(self.OfferBehaviour())

class BuyerAgent(Agent):
    class NegotiateBehaviour(CyclicBehaviour):
        async def run(self):
            msg = await self.receive(timeout=10)
            if msg and msg.get_metadata("performative") == "PROPOSE":
                price = float(msg.body)
                reply = msg.make_reply()
                if price <= self.agent.max_price:
                    reply.set_metadata("performative", "ACCEPT-PROPOSAL")
                else:
                    reply.set_metadata("performative", "REJECT-PROPOSAL")
                await self.send(reply)

    async def setup(self):
        self.add_behaviour(self.NegotiateBehaviour())

This pattern scales naturally to multi-round auctions, supply-chain negotiations, and labor-market matching models.

Social Simulation Use Cases

SPADE 3 is particularly effective for the following social simulation scenarios:

Institutional Modeling

Agents can represent actors operating under formal rules (laws, contracts, norms). FSMBehaviour enables encoding of multi-step institutional procedures — permit applications, regulatory compliance workflows, or legislative processes — as explicit state machines that are auditable and reproducible.

Organizational Dynamics

Hierarchical organizations can be modeled with supervisor agents delegating tasks to worker agents via REQUEST/INFORM cycles. Emergent phenomena such as bottlenecks, information cascades, and authority conflicts arise naturally from the message-passing dynamics.

Market Microstructure

Double-auction markets, posted-offer markets, and bilateral bargaining can be implemented with FIPA ACL performatives. The asynchronous architecture ensures that simultaneous bid submissions are handled without artificial serialization artifacts.

Epidemic Diffusion on Social Networks

Combining SPADE's presence-awareness with network topology data (e.g., from NetworkX) allows researchers to simulate disease or information spreading through contact networks where agents dynamically form and dissolve connections.

Performance Considerations

SPADE 3's asyncio foundation means that I/O-bound workloads (message passing, database queries) scale well within a single process. For CPU-bound simulations with thousands of agents, the recommended approach is to distribute agents across multiple XMPP accounts on a shared server, or to use Python's multiprocessing module to parallelize agent groups.

Benchmarks from the SPADE development team show that a single machine can sustain approximately 500–1,000 concurrently active agents with sub-100 ms message latency on a local XMPP server. For larger populations, containerized deployment (Docker + Kubernetes) with multiple XMPP server instances is the standard scaling strategy.

Installation and Getting Started

pip install spade
# Install a local XMPP server (Prosody recommended for development)
# Ubuntu: sudo apt install prosody

Full documentation, tutorials, and example models are available at:

• Official docs: https://spade-mas.readthedocs.io/
• GitHub repository: https://github.com/javipalanca/spade
• FIPA ACL specification: http://www.fipa.org/specs/fipa00037/
• XMPP standards: https://xmpp.org/extensions/

Comparison with Alternative Frameworks

Conclusion

SPADE 3 fills an important niche in the social simulation toolkit: it brings production-grade multi-agent communication infrastructure to Python researchers who need more than shared-memory ABM but less than a full enterprise MAS platform. Its BDI behaviour model, FIPA ACL messaging, and asyncio architecture make it an excellent choice for modeling negotiation, institutional dynamics, and distributed social processes. Researchers already comfortable with Python will find the transition from Mesa or SimPy straightforward, while gaining access to a richer agent interaction model suited to complex social phenomena.