Getting Started with Mesa

Mesa is an agent-based modeling framework for Python. With Loom's Mesa module (31 base nodes, plus 15 optional Mesa Geo nodes), you can build Mesa models visually — defining agents, behaviors, and data collection on a canvas, then generating runnable Python code.

What You'll Build

A Mesa model in Loom consists of:

  • A grid space where agents live and move
  • One or more agent archetypes with properties and behaviors
  • Optional data collectors to track metrics over time
  • Optional scenario parameters to make your model configurable

The Editor

When you open a Mesa project, the editor has a left panel and a graph canvas. The left panel shows:

  • Archetypes — Your agent types (click + to add)
  • Behaviors — Visual graphs for the selected archetype
  • Properties — Data fields on the selected archetype
  • Scenario Parameters — Model-level configurable values (appear as sliders in visualization)
  • Data Collectors — Metrics to track over time
  • Interface Contract — Input/output ports for federation (advanced)

Loom generates Mesa 3.x code using MultiGrid for the spatial grid and Solara for browser-based visualization.

Creating Agents

  1. In the left panel, click + next to Archetypes
  2. Double-click the archetype name to rename it (e.g., "Walker")
  3. Add properties if needed (e.g., "energy" as a float)

Building Behaviors

Each archetype can have multiple behaviors. A behavior is a visual graph that starts with a Trigger node — either On Init (runs once when the agent is created) or On Step (runs every model tick). Click Add Behavior to create one, then build logic using nodes.

Common first behavior: connect Trigger (On Step) → Move to make agents walk randomly.

Running Your Model

After generating code, install Mesa and run:

pip install mesa[viz] solara
solara run app.py

This launches a browser-based visualization with play/pause controls, step-by-step execution, and parameter sliders.