Add: climate negotiation multi-agent LLM example by BhoomiAgrawal12 · Pull Request #453 · mesa/mesa-examples

BhoomiAgrawal12 · 2026-03-30T10:13:47Z

Summary

Adds a new LLM example under llm/climate_negotiation/, a multi-agent simulation of international climate treaty negotiations. Six country agents (USA, EU, China, India, Brazil, Russia), each driven by an LLM, negotiate on a shared emissions-reduction target over multiple rounds until a 2/3 majority treaty is reached.

References issue #454

What makes this different from existing examples

The existing mesa-examples cover classic ABM patterns (opinion dynamic, resource competition, spatial movement). This is llm/ directory that uses LLM agents for structured multi-party
negotiation and a qualitatively different use-case where:

Agents hold persistent negotiating positions (pledge %, coalitions, acceptance state) that evolve across rounds through LLM decisions.
There is a shared global outcome (the treaty) that emerges only when agents reach consensus and not just individual behaviour.
Agents use targeted inter-agent communication (speak_to) and domain-specific tools rather than generic actions.

The closest existing example is deffuant_weisbuch (opinion convergence without LLMs). This model demonstrates how LLM reasoning produces qualitatively richer convergence: coalition-building, diplomatic counters, and conditional acceptance behaviours that rule-based agents cannot replicate.

Mesa-LLM features demonstrated

Feature	How it appears
`STLTMemory`	Short-term stores recent proposals; long-term consolidates committed positions across rounds
`ReActReasoning`	Agents reason about economic interests before acting
`speak_to` (inbuilt tool)	Targeted diplomatic messaging between specific countries
Custom `@tool` functions	`make_proposal`, `accept_proposal`, `form_coalition`, `reject_and_counter`
`vision=-1`	Full-room awareness as every agent observes all others and no spatial grid needed
`DataCollector`	Tracks `TotalProposals`, `AveragePledge`, `LargestCoalitionSize`, `TreatyReached` per round

Features

Two LLM hallucination failure modes are explicitly guarded:

Phantom agent IDs in form_coalition - partner_ids are filtered against the live agent set; invalid IDs are dropped and logged as WARNING.
Invalid proposer_id in accept_proposal - the ID is validated before recording; if wrong, an error listing valid IDs is returned to the LLM for self-correction.

Every agent's step prompt also includes an explicit VALID COUNTRY IDs block to reduce hallucination at the source.

Visualisation (Solara)

Pledge bar chart - bars turn green when a country accepts the treaty
Coalition status panel - live table of pledge, acceptance, coalition members
Pledge trajectories - line chart across rounds
Time-series plots - TotalProposals, AveragePledge, LargestCoalitionSize

Supported LLMs

Works with any LiteLLM-compatible model string. Tested with openai/gpt-4o (best emergent behaviour), gemini/gemini-2.0-flash (default), openai/gpt-4o-mini, anthropic/claude-haiku-4-5-20251001, and ollama/llama3.2.

File Structure

llm/climate_negotiation/
├── app.py # Solara visualisation entry point
├── README.md
└── climate_negotiation/
├── init.py # triggers tool registration on import
├── agents.py # CountryAgent + negotiation history helper
├── tools.py # four custom @tool negotiation functions
└── model.py # ClimateNegotiationModel + countries configs

To Try

pip install mesa-llm mesa solara python-dotenv rich
Set a valid API key in llm/climate_negotiation/.env
python -m climate_negotiation.model - confirm rounds print and treaty is reached within ~6 rounds with gpt-4o
solara run app.py - confirm all four visualisation panels render and update per round

for more information, see https://pre-commit.ci

sadrasabouri

I left some comments that may be helpful. My overall suggestion is to trim this PR down to an atomic contribution on top of deffuant_weisbuch. One possible direction:

LLM-driven dynamic opinion change: define a few agent types with distinct system prompts reflecting different personalities. Give each agent a personal stance on the topic (e.g., "I believe we should use ..."). Opinion updates come from querying an LLM with something like: "Given that agent X's argument is Y, rate how much do you agree with Z ? Answer between 0 and 1." This setup can simulate the echo-chamber effect by tuning $\epsilon$ from the original model.

X: other interacting agents
Y: X's opinion statement which gets updated as their opinion gets updated each round
Z: the subject that the whole model is going to be about (e.g., climate)

sadrasabouri · 2026-05-31T04:59:29Z

+### 1. Install dependencies
+
+```bash
+pip install mesa-llm mesa solara python-dotenv rich


Can you add a requirements.txt for this?

sadrasabouri · 2026-05-31T05:01:03Z

+## Robustness Against LLM Hallucinations
+
+Two common failure modes are guarded in code:
+
+- **Phantom agent IDs in `form_coalition`** - `partner_ids` are filtered against
+  the live agent set before being stored. Invalid IDs are dropped and logged as
+  `WARNING` in `climate_negotiation.log`.
+- **Invalid `proposer_id` in `accept_proposal`** - the ID is validated before
+  recording an acceptance. If it doesn't match any agent, an error string listing
+  valid IDs is returned to the LLM so it can self-correct on its next step.
+
+Every agent's step prompt also includes an explicit `VALID COUNTRY IDs` block so
+models are less likely to invent IDs in the first place.


I think the reader does not necessary benefit from this in readme as it's very low-level implementation details. Feel free to remove it.

sadrasabouri · 2026-05-31T05:02:56Z

+
+### 2. Set your API key
+
+Create a `.env` file in `llm/climate_negotiation/`:


nit: add a local .gitignore file avoid committing .env mistakenly.

sadrasabouri · 2026-05-31T06:03:40Z

+**Try different LLMs**: Change `llm_model` in `app.py`. `gpt-4o` produces richer diplomatic
+language; `gemini-2.0-flash` is faster and free.
+
+**Add more countries**: Add a new dict to the `COUNTRIES` list in `model.py` and assign it
+a system prompt encoding that country's real-world stance.
+
+**Change the treaty threshold**: Edit `_treaty_reached()` in `model.py`
+(currently requires a 2/3 majority).


These are nearly trivial edits. Feel free to remove them.

sadrasabouri · 2026-05-31T07:10:20Z

+
+from .agents import country_tool_manager
+
+if TYPE_CHECKING:


you don't need this if here. for your code as a application script you can just import the type and start using it.

sadrasabouri · 2026-05-31T07:22:09Z

+        Confirmation of coalition formation and the partners notified.
+    """
+    if isinstance(partner_ids, str):
+        import json


move it to the top of the file.

sadrasabouri · 2026-05-31T07:23:54Z

+        proposer_id: Unique ID of the country whose proposal you are rejecting.
+        counter_reduction_percent: Your alternative reduction percentage.
+        reason: Explanation of why you reject the original and what you offer instead.
+        agent: Provided automatically.


sadrasabouri · 2026-05-31T07:24:06Z

+    counter_reduction_percent = float(counter_reduction_percent or 20.0)
+    proposer_id = int(proposer_id or 0)


sadrasabouri · 2026-05-31T07:35:17Z

+        id_to_name = {
+            a.unique_id: getattr(a, "country_name", f"Agent {a.unique_id}")
+            for a in self.model.agents
+        }


having this dict as a model's parameter makes more sense.

sadrasabouri · 2026-05-31T07:39:41Z

+    Mesa-LLM features demonstrated
+    - STLTMemory   : short-term stores recent proposals; long-term consolidates
+                     committed positions across rounds.
+    - ReActReasoning: agents reason then act within each simulation step.
+    - speak_to     : inbuilt diplomatic messaging tool between agents.
+    - Custom tools  : make_proposal, accept_proposal, form_coalition,
+                      reject_and_counter.
+    - vision=-1    : agents observe all other parties (full-room awareness,
+                     no spatial grid needed).
+


I don't think you need this here

BhoomiAgrawal12 and others added 4 commits March 30, 2026 14:30

example: Climate negotiation model

68ff078

fix: move to llm/ and protection against hallucinated IDs

fd740c9

[pre-commit.ci] auto fixes from pre-commit.com hooks

ff8c876

for more information, see https://pre-commit.ci

fix : ruff

eee2e14

BhoomiAgrawal12 force-pushed the add/climate-negotiation branch from e6d4d4c to eee2e14 Compare March 30, 2026 10:48

sadrasabouri mentioned this pull request May 31, 2026

Add climate negotiation LLM example #454

Open

sadrasabouri suggested changes May 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add: climate negotiation multi-agent LLM example #453

Add: climate negotiation multi-agent LLM example #453
BhoomiAgrawal12 wants to merge 4 commits into
mesa:mainfrom
BhoomiAgrawal12:add/climate-negotiation

BhoomiAgrawal12 commented Mar 30, 2026 •

edited

Loading

Uh oh!

sadrasabouri left a comment

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

sadrasabouri May 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### 2. Set your API key

		Create a `.env` file in `llm/climate_negotiation/`:

		counter_reduction_percent = float(counter_reduction_percent or 20.0)
		proposer_id = int(proposer_id or 0)

Uh oh!

Conversation

BhoomiAgrawal12 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What makes this different from existing examples

Mesa-LLM features demonstrated

Features

Visualisation (Solara)

Supported LLMs

File Structure

To Try

Uh oh!

sadrasabouri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BhoomiAgrawal12 commented Mar 30, 2026 •

edited

Loading