Agent#
Agent related classes.
Core Objects: Agent.
- class Agent(model: M, *args, **kwargs)[source]#
Base class for a model agent in Mesa.
Notes
Agents must be hashable to be used in an AgentSet. In Python 3, defining __eq__ without __hash__ makes an object unhashable, which will break AgentSet usage. unique_id is unique relative to a model instance and starts from 1
Create a new agent.
- Parameters:
model (Model) – The model instance in which the agent exists.
args – Passed on to super.
kwargs – Passed on to super.
Notes
to make proper use of python’s super, in each class remove the arguments and keyword arguments you need and pass on the rest to super
- remove() None[source]#
Remove and delete the agent from the model.
If the agent is currently performing an action, the action’s scheduled completion event is cancelled silently. The action’s on_interrupt() callback is NOT fired, because the agent is being destroyed — not making a behavioral decision. The action moves to no defined end state; it is simply abandoned.
If your action holds external resources (e.g., a Resource slot, a reservation, a lock), override Agent.remove() and call self.cancel_action() before super().remove() to ensure on_interrupt() fires and cleanup logic runs:
- def remove(self):
self.cancel_action() # Fires on_interrupt for cleanup super().remove()
Notes
This is a deliberate design choice. The default silent cleanup is safe and avoids callbacks touching agent state during teardown. Models that need cleanup should opt in explicitly.
- classmethod create_agents(model: Model, n: int, *args, **kwargs) AgentSet[T][source]#
Create N agents.
- Parameters:
model – the model to which the agents belong
args – arguments to pass onto agent instances each arg is either a single object or a sequence of length n
n – the number of agents to create
kwargs – keyword arguments to pass onto agent instances each keyword arg is either a single object or a sequence of length n
- Returns:
AgentSet containing the agents created.
- classmethod from_dataframe(model: Model, df: pd.DataFrame, **kwargs) AgentSet[T][source]#
Create agents from a pandas DataFrame.
Each row of the DataFrame represents one agent. The DataFrame columns are mapped to the agent’s constructor as keyword arguments. Additional keyword arguments (**kwargs) can be used to set constant attributes for all agents.
- Parameters:
model – The model instance.
df – The pandas DataFrame. Each row represents an agent.
**kwargs – Constant values to pass to every agent’s constructor. Only non-sequence data is allowed in kwargs to avoid ambiguity with DataFrame columns.
- Returns:
AgentSet containing the agents created.
Note
If you need to pass variable data or sequences, add them as columns to the DataFrame before calling this method.
- property rng: Generator#
Return a seeded np.random rng.
- property scenario#
Return the scenario associated with the model.
- start_action(action: Action) Action[source]#
Start performing an action.
The action must be in PENDING or INTERRUPTED state and the agent must not be currently performing another action.
- Parameters:
action – The Action to perform. Must have been created with this agent as its agent.
- Returns:
The started Action.
- Raises:
ValueError – If the agent is already performing an action, or if the action doesn’t belong to this agent.
- interrupt_for(new_action: Action) bool[source]#
Interrupt the current action and start a new one.
If there is no current action, simply starts the new one. If the current action is non-interruptible, returns False and does nothing.
- Parameters:
new_action – The Action to perform instead.
- Returns:
True if the new action was started (either no current action, or the current one was successfully interrupted). False if the current action is non-interruptible.