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

> Easily set up and run multi-agent simulations with NetLogo. Learn to define agent behaviors and observe emergent phenomena in this powerful modeling environment.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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)](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:

```netlogo
;; 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:

```netlogo
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](https://ccl.northwestern.edu/netlogo/download.shtml) 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:

```netlogo
;; 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

```netlogo
;; 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:

```netlogo
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:

```netlogo
;; 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)](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)](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`](https://github.com/microsoft/AI-For-Beginners/blob/main/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/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.