Overview#

Mesa-LLM is an extension of Mesa that enables language-model-based reasoning inside agents. It does not modify Mesa’s execution model, scheduling, or environments. Agents created with Mesa-LLM are standard Mesa agents. The only difference is that their decision-making logic is delegated to a reasoning component backed by an LLM.

Separation#

What Mesa Provides#

  • Agent

  • Model

  • AgentSet & Scheduling

  • Space / Environment

  • Time Progression

  • Data Collection

  • Visualization

What Mesa-llm Adds#

  • Language Model Based reasoning inside Agent

Core Mesa-llm Concepts#

1. LLMAgent#

LLMAgent is the core abstraction introduced by Mesa-LLM. From Mesa’s perspective, an LLMAgent behaves exactly like a standard Mesa Agent:

  • It is created and registered in the same way.

  • It is scheduled and activated using Mesa’s normal execution flow.

The difference lies in how decisions are made. Instead of relying only on hard-coded logic, an LLMAgent delegates part (or all) of its decision-making process to a language model through a reasoning module.

class MyAgent(LLMAgent):
    def step(self):
        plan = self.reasoning.plan(prompt, obs)

2. Reasoning#

A reasoning module defines how an agent thinks, given:

  • A prompt.

  • Observations from the model or environment.

  • Optional memory and tools.

Reasoning modules are attached to agents to encapsulate how language-based reasoning is performed. While Mesa-LLM currently provides ReActReasoning, the reasoning logic is kept separate from the agent to allow extensibility without changing agent structure.

3. Memory#

Memory allows agents to retain information across simulation steps. In Mesa-LLM, memory is useful for reasoning-based agents. It enables agents to:

  • Reference past observations or interactions.

  • Maintain more consistent behavior over time.

  • Produce more coherent and contextual reasoning.

Memory is optional in Mesa-LLM. When present, it allows agents to retain information across steps and reason with context. When absent, agents reason purely from the current observation and prompt.

4. Tools#

Tools provide a structured way for agents to express or request actions when the simulation supports action execution.

Tools are optional and typically become relevant only when:

  • An environment exists (e.g. a grid).

  • Actions can be meaningfully executed.

In introductory models, action suggestions may appear only as part of the reasoning trace and are not executed. Mesa-LLM does not introduce new space or environment abstractions; it relies entirely on Mesa’s existing space modules.

5. Execution Model#

Mesa-LLM follows Mesa’s standard execution model. The simulation advances through calls to model.step(), and agents are activated using Mesa’s scheduling mechanisms.

When an agent is activated, its step() method is called. In Mesa-LLM, this method typically includes language-based reasoning before deciding what to do next.