Support multiple and overlapping meta-agent memberships#3172
Support multiple and overlapping meta-agent memberships#3172
Conversation
Refactor MetaAgent to allow agents to belong to multiple meta-agent groups simultaneously. Previously, agents were limited to a single scalar 'meta_agent' reference, which prevented overlapping hierarchies. Update create_meta_agent to only merge agents into existing groups if the class name matches, enabling independent overlapping groups of different types. Maintain the 'agent.meta_agent' attribute for backward compatibility with existing model logic. Remove redundant model registration and deregistration calls in MetaAgent methods. These calls were unnecessary as agents register themselves on initialization, and were causing KeyErrors when agents participated in multiple groups or transitioned between them. Add a new test suite 'test_multi_level_meta_agents.py' to verify overlapping memberships and proper group removal behavior.
Refactor MetaAgent to allow agents to belong to multiple meta-agent groups simultaneously. Previously, agents were limited to a single scalar 'meta_agent' reference, which prevented overlapping hierarchies. Update create_meta_agent to only merge agents into existing groups if the class name matches, enabling independent overlapping groups of different types. Maintain the 'agent.meta_agent' attribute for backward compatibility with existing model logic. Remove redundant model registration and deregistration calls in MetaAgent methods. These calls were unnecessary as agents register themselves on initialization, and were causing KeyErrors when agents participated in multiple groups or transitioned between them. Add a new test suite 'test_multi_level_meta_agents.py' to verify overlapping memberships and proper group removal behavior.
|
Cool, seems like an obvious use case. I would let @tpike3 do the (initial) review, since he's the author of this module. |
|
Thanks @falloficarus22, this will be a great addition and is critical to get to the goal of rich agent behavior at the overlapping memberships which can allow for activation of different behaviors based on context and group memberships. Based on the new merges to fix the memory leak could you take a look at #3183 to resolve the conflicts, and if you have the time/desire take a look at the other issue I highlighted in the comments. Quick note: this is @tpike3 I just was logged into another account. |
sure |
|
@tpike3 @falloficarus22 for both of you, this idea might also be interesting: #2539 (comment) |
|
Hi @edgeofchaos42 / @tpike3 , I definitely agree with your point about the distinction between membership and existence. The current logic in The distinction you draw is essential for making meta-agents more robust. Regarding your point about ensuring cleanup when an agent is removed from the model, I'd like to propose a specific direction for discussion: Proposal: Bidirectional Cleanup Hooks Instead of horizontal orchestration, what if we leveraged hooks in the base lifecycle?
Do you think centralizing this cleanup inside the |
Hey, @EwoutH A few thoughts from an architectural perspective:
If an agent belongs to two different Household meta-agents (e.g., a shared residence in a complex model), the current Overall, I think the "is-a group" approach is the right direction. It eliminates a lot of boilerplate and makes the group-level analysis (like I'd be curious to hear if anyone has concerns about MRO or serialization (pickle/getstate) when mixing |
|
@falloficarus22 Based on the dev meeting yesterday, the plan is for a larger effort on meta-agents, so my proposal would we : What do you think? |
Agreed! I don't have the time to make the changes right away but I'll update the PR as early as tomorrow |
| agent.meta_agent = self | ||
|
|
||
| def remove_constituting_agents(self, remove_agents: set[Agent]): | ||
| def remove_constituting_agents(self, remove_agents: Iterable[Agent]): |
There was a problem hiding this comment.
Sorry I think I missed something or misunderstood.
Why are we switching to a generic iterable vs a set? With set we can use set.difference_update to remove agents quickly. This would also prevent us from touching agent.py.
Let me know what i am missing. Thanks
There was a problem hiding this comment.
Even if we used set.difference_update() on the collection, we still have to run an O(N) loop over every agent being removed to handle the cleanup of the agent's internal state (agent.meta_agents.discard(self)). A bulk set operation only updates the parent's list; it doesn't handle the child's reference. Since the loop is mandatory for the side effects, the performance gain of difference_update is negligible.
Without the change to agent.py, every time a user wants to remove multiple agents, they have to write a logic loop:
for a in agents_to_remove:
my_agentset.discard(a)By putting difference_update into the core AgentSet class, we encapsulate that logic. If we ever find a faster way to perform bulk removals in the future (e.g., if AgentSet moves away from a WeakKeyDictionary), we only have to optimize it in one place (agent.py) rather than fixing manual loops scattered across the whole codebase.
How would you prefer it?
There was a problem hiding this comment.
@falloficarus22 this is a good discussion and is helping understand the dynamics of meta-agents more deeply. I don't think we are quite synced up yet on our understanding.
I see the remove_constituting_agents as two transactions:
1 - meta-agent remove constituting_agents (parent remove child):
- thought is use pythons set.difference_update to remove these agents
2 - constituting_agents remove meta-agent (child remove parent):
- for loop through constituting_agents to remove meta-agent
How I understand your code is it is running two for loops:
1 - iterate through constituting_agents to remove from meta-agent (parent remove child)
2 - iterate through constituting_agents to remove meta-agent (child remove parent)
With this we can only optimize the first for loop since the references are centrally located in the meta-agent instance executing the transaction, we have to maintain the for loop for the second as each constituting_agent could have diverse set of meta-agent to which they belong.
Only to be thorough ---- What we are not doing is removing the constituting_agent or the meta-agent from the model, the user would have to specify different transaction(s) for that. Although at some point we may want to consider a boolean kwarg where the constituting_agent and /or meta-agent are entirely removed.
Again, i could be misunderstanding so please let me know your point of view.
Two other notes, regardless of next step.
1 - We want to try and stay clear of updating agent.py. This is for the larger goal of building out mesa modules (@EwoutH ) This will help us answer the question of how to make agent.py more extensible to allow for modular inputs.
2 - We would not want to call the function in agent.py difference_update as users could confuse it with the python native set function.
There was a problem hiding this comment.
The technical trade-off for remove_constituting_agents comes down to pass-count and performance:
- One Pass vs. Two: Your proposed 'two transaction' model (bulk removal + side-effect loop) requires two separate passes over the data. Since we have a mandatory requirement to update internal child states (
agent.meta_agents.discard(self)), a single-pass loop that handles both operations in one traversal is computationally more efficient. - The
AgentSetConstraint:AgentSetis not a native Python set. It only supportsdifference_updateif we modify the coreagent.py. If the architectural goal is to keepagent.pyminimal for modularity, then a local O(N) loop inmeta_agent.pyis the technically superior solution as it achieves the same result in one pass without requiring core library updates. - API Clarity: Avoiding the addition of a
difference_updatemethod toAgentSetsolves both the naming confusion and the modularity concern.
I will consolidate the logic into a single internal loop in meta_agent.py and revert the changes to agent.py. This maximizes local performance while respecting the boundary between experimental and core code.
There was a problem hiding this comment.
@falloficarus22 fair point -- one loop with each action parent remove child and child remove parent computationally looks more efficient than two transactions. However, python being written on C, when you have C optimized functions that you can employ, it can become counterintuitive (and this varies based on the situation). Running a simple test of 1,000,10,000, 100,000, 1,000,000 and 5,000,000 agents with different subagent discards of 1%, 10%, 25%, 50%, 75% and 90%. In these runs using difference_update is generally faster but not in all cases particularly around 100,000 agents and even then in some runs of the single loop maybe faster.
At this point, however, I think it is better to merge and then we can focus on the optimizations later. Thank you for all the work and conversation on this.
falloficarus22
force-pushed
the
feature/multi-level-meta-agents
branch
from
8139feb to
c7b1261
Compare
|
Thanks for this effort! Few questions/requests:
|
Possible follow up issues:
|
5 participants
Summary
This PR refactors the experimental MetaAgent module to support multiple and overlapping memberships. Agents can now belong to more than one meta-agent (e.g., a "Worker" in both a "Company" and a "Team"), enabling more complex, real-world hierarchical simulations.
Motive
The previous implementation used a single scalar reference (
agent.meta_agent = self), which restricted agents to a single-parent hierarchy. This made it impossible to model overlapping groups or modular organizational structures. Additionally, redundantmodel.register_agentcalls within the MetaAgent lifecycle were causingKeyErrorcrashes in multi-membership scenarios.Implementation
agent.meta_agentto a setagent.meta_agents.agent.meta_agentis maintained to ensure existing model logic that expects a single value does not break.register_agent/deregister_agentcalls from MetaAgent to align with Mesa's automatic agent registration lifecycle and prevent state-sync errors.Usage Examples
Creating Overlapping Groups:
Additional Notes
mesa.experimental.meta_agents. No changes were made to the core Agent,Model, orAgentSetclasses, ensuring full backward compatibility and zero side effects for standard models.