How to Set Up and Run Multi-Agent Simulations Using NetLogo

NetLogo is a dedicated agent-based modeling environment where you create autonomous agents (turtles), define their behavior rules in the Code tab, and run simulations via Setup and Go buttons to observe emergent system-level phenomena.

NetLogo stands out as the primary tool for teaching and building multi-agent simulations in the Microsoft AI-For-Beginners curriculum. The environment's intuitive design lets you move from installation to running complex emergent behavior models within minutes, making it ideal for exploring concepts like flocking, traffic patterns, and disease spread.

Core NetLogo Architecture

Understanding NetLogo's three fundamental components is essential before building simulations. According to [lessons/6-Other/23-MultiagentSystems/README.md](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/6-Other/23-MultiagentSystems/README.md), the architecture separates responsibilities across distinct agent types:

Turtles: Mobile Agents

Turtles are the primary moving agents in any NetLogo simulation. Create them with create-turtles and organize related agents into breeds for specialized behavior:

;; Create a breed of cats with individual instances
breed [cats cat]
breed [dogs dog]

create-cats 10
create-dogs 5

ask cats [
  forward 10
  set color orange
]

The breed declaration (breed [cats cat]) establishes both the plural and singular forms used throughout your code.

Patches: Static Environment Cells

Patches are the fixed square grid cells that form your simulation world. Turtles interact with their current patch using built-in reporters and commands:

ask turtles [
  ;; Check patch color beneath the turtle
  if pcolor = green [
    set energy energy + 10  ;; Gain energy on green patches
  ]
]

ask patches [
  ;; Patches can run their own logic
  if random 100 < 5 [
    set pcolor green  ;; Random grass growth
  ]
]

Observer: Global Controller

The observer is the unique top-level agent that manages simulation-wide operations. It executes setup procedures, creates initial populations, and handles global variables that no single turtle or patch should control.

Installing NetLogo and Running Your First Simulation

Step 1: Download and Install

NetLogo runs on Windows, macOS, and Linux. Download the official installer from the NetLogo download page referenced in the repository at line 48 of the README.

Step 2: Explore the Models Library

NetLogo ships with hundreds of pre-built simulations. Access them through File → Models Library:

Model Category	Example	Demonstrates
Biology	Flocking	Emergent coordination from local rules
Social Science	Traffic Basic	Traffic jam formation without bottlenecks
Art	Fireworks	Particle system emergent patterns

The Models Library screenshot at lines 50-56 shows the hierarchical organization that makes examples easy to locate.

Step 3: Run an Existing Model

Open Biology → Flocking to see the standard interface layout described at lines 68-75:

• View: The 2D/3D visualization of agents
• Interface Tab: Buttons (Setup, Go), sliders, switches, and plots
• Code Tab: The NetLogo script driving behavior

Run the simulation:

;; Setup button calls this procedure
to setup
  clear-all
  create-turtles 200 [
    set color gray
    set size 2
    setxy random-xcor random-ycor
  ]
  reset-ticks
end

;; Go button calls this repeatedly
to go
  ask turtles [
    flock
  ]
  tick
end

Press Setup to initialize, then Go to start continuous execution. The go procedure definition appears at lines 76-82 in repository documentation.

Building Custom Multi-Agent Simulations

When creating your own models in the Code tab, follow this architectural workflow:

1. Define Agent Structure

;; Custom breed with properties
breed [predators predator]
breed [prey a-prey]

predators-own [
  energy
  hunting-success
]

prey-own [
  alert-level
  flock-mates
]

2. Implement Behavior Rules

NetLogo's ask primitive executes code for agent sets. Lines 90-91 note that execution happens in parallel—all turtles complete their current step before any proceed to the next:

to flock  ;; turtle procedure
  ;; Three classic flocking forces
  let nearby-turtles other turtles in-radius 3
  
  ;; ALIGNMENT: match average heading
  if any? nearby-turtles [
    turn-towards average-heading nearby-turtles 7
  ]
  
  ;; COHESION: steer toward center
  turn-towards mean-position nearby-turtles 3
  
  ;; SEPARATION: avoid collision (lines 94-99)
  if any? other turtles in-radius 1 [
    turn-away mean-position other turtles in-radius 1 10
  ]
  
  forward 1
end

The flocking rules implementation demonstrates how simple local interactions produce global coordination without central control.

3. Expose Experimental Parameters

Add sliders and switches in the Interface tab to make your model interactive:

• Sliders: Population size, speed limits, detection radii
• Switches: Enable/disable specific behaviors
• Plots: Real-time visualization of aggregate metrics

4. Observe Emergent Phenomena

Use monitors and plots to track properties that emerge from agent interactions rather than being explicitly programmed:

;; Plot average cluster size
plot count turtles with [count turtles in-radius 2 > 5]

Key Files in Microsoft/AI-For-Beginners

File Path	Purpose
[lessons/6-Other/23-MultiagentSystems/README.md](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/6-Other/23-MultiagentSystems/README.md)	Complete NetLogo documentation with installation steps, architecture explanation, and code samples
[lessons/6-Other/23-MultiagentSystems/assignment.md](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/6-Other/23-MultiagentSystems/assignment.md)	Hands-on exercise: modify the Virus model to simulate real-world epidemic scenarios
translations/*/lessons/6-Other/23-MultiagentSystems/README.md	Localized documentation for global accessibility

Summary

• NetLogo provides a complete environment for multi-agent simulations with three core components: turtles (mobile agents), patches (environment cells), and the observer (global controller).
• Installation is straightforward via the official download, and the Models Library offers immediate access to proven examples like Flocking and Traffic.
• Simulations run through Setup and Go buttons that execute procedures defined in the Code tab.
• Parallel execution of agent code produces emergent behavior from simple local rules—no global controller needed.
• The Microsoft AI-For-Beginners repository provides structured lessons and assignments at lessons/6-Other/23-MultiagentSystems/ to advance from running models to building custom simulations.

Frequently Asked Questions

What programming language does NetLogo use?

NetLogo uses its own domain-specific language designed specifically for agent-based modeling. The syntax is Logo-inspired—concise, readable, and optimized for turtles, patches, and observer commands. You write procedures in the Code tab using primitives like ask, create-turtles, forward, and of.

Can I run NetLogo simulations without the GUI?

Yes. NetLogo includes a headless mode for batch execution and parameter sweeping. Use netlogo-headless.sh (or .bat on Windows) with command-line arguments to run experiments, export results, and automate replication studies without the graphical interface overhead.

How does NetLogo differ from general-purpose simulation frameworks?

NetLogo trades flexibility for accessibility. Unlike Python Mesa or Java Repast, NetLogo wraps agent parallelism, spatial grids, and visualization into a batteries-included environment. You sacrifice some performance optimization control but gain rapid prototyping capabilities that the AI-For-Beginners curriculum leverages for educational multi-agent systems exploration.

What does the assignment.md file contain?

The [assignment.md](https://github.com/microsoft/AI-For-Beginners/blob/main/lessons/6-Other/23-MultiagentSystems/assignment.md) file provides a structured exercise where you modify NetLogo's Virus model to simulate realistic epidemic scenarios. You adjust infection probabilities, recovery rates, and population movement patterns—directly applying multi-agent simulation concepts to public health modeling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}