feat: Add support for multi-agent communication (#4)

## Overview
This PR enhances the agent communication system by adding support for multi-agent messaging, allowing an agent to send messages to multiple recipients simultaneously. It also includes several improvements to error handling and message formatting.

### Key Changes
- Added support for sending messages to multiple agents at once via `talk_to` method
- Enhanced error handling for agent communication with better error messages
- Improved message formatting for both single and multi-agent conversations
- Added reminder in prompt template to close XML tags
- Fixed return type annotations for `ask` and `talk_to` methods
- Bumped version from 0.3.0 to 0.3.1

### Implementation Details
- Modified `Interaction` class to store receivers as a list of agents
- Updated `AgentInteractionManager` to handle multiple receivers
- Added support for "all" keyword to broadcast messages to all agents
- Enhanced error messages for invalid agent IDs
- Improved string representation of interactions for better readability

### Testing
- Added new test cases for multi-agent communication
- Updated existing tests to accommodate the new receiver list format
- Added tests for manual and automatic action execution

### Breaking Changes
None. All changes are backward compatible as single-agent communication continues to work as before.

Author: Thytu

agentarium/Agent.py

@@ -79,6 +79,8 @@ class Agent:
 <ACTION>
 [{{One of the following actions: {list_of_actions}}}]
 </ACTION>
+
+Don't forget to close each tag that you open.
 """
 
     def __init__(self, **kwargs):
@@ -343,7 +345,12 @@ def act(self) -> str:
             temperature=0.4,
         )
 
-        regex_result = re.search(r"<ACTION>(.*?)</ACTION>", response.choices[0].message.content, re.DOTALL).group(1).strip()
+        try:
+            regex_result = re.search(r"<ACTION>(.*?)</ACTION>", response.choices[0].message.content, re.DOTALL).group(1).strip()
+        except AttributeError as e:
+            logging.error(f"Received a response without any action: {response.choices[0].message.content=}")
+            raise e
+
         action_name, *args = [value.replace("[", "").replace("]", "").strip() for value in regex_result.split("]")]
 
         if action_name not in self._actions:
@@ -391,7 +398,7 @@ def get_interactions(self) -> List[Interaction]:
         """
         return self._interaction_manager.get_agent_interactions(self)
 
-    def ask(self, message: str) -> None:
+    def ask(self, message: str) -> str:
         """
         Ask the agent a question and receive a contextually aware response.
 
@@ -507,7 +514,7 @@ def remove_action(self, action_name: str) -> None:
 
         del self._actions[action_name]
 
-    def talk_to(self, agent: Agent, message: str) -> None:
+    def talk_to(self, agent: Agent | list[Agent], message: str) -> Dict[str, Any]:
         """
         Send a message from one agent to another and record the interaction.
         """
@@ -516,7 +523,10 @@ def talk_to(self, agent: Agent, message: str) -> None:
             # Did you really removed the default "talk" action and expect the talk_to method to work?
             raise RuntimeError("Talk action not found in the agent's action space.")
 
-        self.execute_action("talk", agent.agent_id, message)
+        if isinstance(agent, Agent):
+            return self.execute_action("talk", agent.agent_id, message)
+        else:
+            return self.execute_action("talk", ','.join([agent.agent_id for agent in agent]), message)
 
     def think(self, message: str) -> None:
         """

agentarium/AgentInteractionManager.py

@@ -78,7 +78,7 @@ def get_agent(self, agent_id: str) -> Agent | None:
         """
         return self._agents.get(agent_id)
 
-    def record_interaction(self, sender: Agent, receiver: Agent, message: str) -> None:
+    def record_interaction(self, sender: Agent, receiver: Agent | list[Agent], message: str) -> None:
         """
         Record a new interaction between two agents.
 
@@ -87,15 +87,21 @@ def record_interaction(self, sender: Agent, receiver: Agent, message: str) -> No
 
         Args:
             sender (Agent): The agent initiating the interaction.
-            receiver (Agent): The agent receiving the interaction.
+            receiver (Agent | list[Agent]): The agent(s) receiving the interaction.
             message (str): The content of the interaction.
         """
 
+        from .Agent import Agent
+
         if sender.agent_id not in self._agents:
             raise ValueError(f"Sender agent {sender.agent_id} is not registered in the interaction manager.")
 
-        if receiver.agent_id not in self._agents:
-            raise ValueError(f"Receiver agent {receiver.agent_id} is not registered in the interaction manager.")
+        if isinstance(receiver, Agent):
+            receiver = [receiver]
+
+        if any(_receiver.agent_id not in self._agents for _receiver in receiver):
+            invalid_receivers = [_receiver for _receiver in receiver if _receiver.agent_id not in self._agents]
+            raise ValueError(f"Receiver agent(s) {invalid_receivers} not registered in the interaction manager.")
 
         interaction = Interaction(sender=sender, receiver=receiver, message=message)
 
@@ -105,8 +111,9 @@ def record_interaction(self, sender: Agent, receiver: Agent, message: str) -> No
         # Record in private interactions for both sender and receiver
         self._agent_private_interactions[sender.agent_id].append(interaction)
 
-        if receiver.agent_id != sender.agent_id:
-            self._agent_private_interactions[receiver.agent_id].append(interaction)
+        for _receiver in receiver:
+            if _receiver.agent_id != sender.agent_id:
+                self._agent_private_interactions[_receiver.agent_id].append(interaction)
 
     def get_all_interactions(self) -> List[Interaction]:
         """

agentarium/Interaction.py

@@ -23,8 +23,8 @@ class Interaction:
     sender: Agent
     """The agent who initiated the interaction."""
 
-    receiver: Agent
-    """The agent who received the interaction."""
+    receiver: list[Agent]
+    """The agent(s) who received the interaction."""
 
     message: str
     """The content of the interaction between the agents."""
@@ -35,7 +35,7 @@ def dump(self) -> dict:
         """
         return {
             "sender": self.sender.agent_id,
-            "receiver": self.receiver.agent_id,
+            "receiver": [receiver.agent_id for receiver in self.receiver],
             "message": self.message,
         }
 
@@ -46,7 +46,11 @@ def __str__(self) -> str:
         Returns:
             str: A formatted string showing sender, receiver, and the interaction message.
         """
-        return f"Interaction from {self.sender.name} ({self.sender.agent_id}) to {self.receiver.name} ({self.receiver.agent_id}): {self.message}"
+
+        if len(self.receiver) == 1:
+            return f"{self.sender.name} ({self.sender.agent_id}) said to {self.receiver[0].name} ({self.receiver[0].agent_id}): {self.message}"
+        else:
+            return f"{self.sender.name} ({self.sender.agent_id}) said to {', '.join([_receiver.name + f'({_receiver.agent_id})' for _receiver in self.receiver])}: {self.message}"
 
     def __repr__(self) -> str:
         """
@@ -56,4 +60,3 @@ def __repr__(self) -> str:
             str: A formatted string showing sender, receiver, and the interaction message.
         """
         return self.__str__()
-

agentarium/__init__.py

@@ -3,7 +3,7 @@
 from .actions.Action import Action
 from .Interaction import Interaction
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "Agent",

agentarium/actions/default_actions.py

@@ -20,7 +20,7 @@ def talk_action_function(*args, **kwargs):
     Returns:
         dict: A dictionary containing:
             - sender (str): The ID of the sending agent
-            - receiver (str): The ID of the receiving agent
+            - receiver (str | list[str]): The ID of the receiving agent
             - message (str): The content of the message
 
     Raises:
@@ -34,19 +34,32 @@ def talk_action_function(*args, **kwargs):
     if "agent" not in kwargs:
         raise RuntimeError(f"Couldn't find agent in  {kwargs=} for TALK action")
 
-    receiver = kwargs["agent"]._interaction_manager.get_agent(args[0])
+    # Retrieve the receiver IDs
+    receiver_ids = [_rec.strip() for _rec in args[0].split(',') if len(_rec.strip()) != 0]
 
-    if receiver is None:
+    # If the receiver is "all", talk to all agents
+    if "all" in receiver_ids:
+        receiver_ids = [agent.agent_id for agent in kwargs["agent"]._interaction_manager._agents.values()]
+
+    # Retrieve the receivers from their IDs
+    receivers = [kwargs["agent"]._interaction_manager.get_agent(_receiver_id) for _receiver_id in receiver_ids]
+
+    # Check if the receivers are valid
+    if any(receiver is None for receiver in receivers):
         logger.error(f"Received a TALK action with an invalid agent ID {args[0]=} {args=} {kwargs['agent']._interaction_manager._agents=}")
-        raise RuntimeError(f"Received a TALK action with an invalid agent ID: {args[0]}. {args=}")
+        raise RuntimeError(f"Received a TALK action with an invalid agent ID: {args[0]=}. {args=}")
 
     message = args[1]
 
-    kwargs["agent"]._interaction_manager.record_interaction(kwargs["agent"], receiver, message)
+    if len(message) == 0:
+        logger.warning(f"Received empty message for talk_action_function: {args=}")
+
+    # Record the interaction
+    kwargs["agent"]._interaction_manager.record_interaction(kwargs["agent"], receivers, message)
 
     return {
         "sender": kwargs["agent"].agent_id,
-        "receiver": receiver.agent_id,
+        "receiver": [receiver.agent_id for receiver in receivers],
         "message": message,
     }
 
@@ -88,9 +101,15 @@ def think_action_function(*args, **kwargs):
 
 
 # Create action instances at module level
+talk_action_description = """\
+Talk to agents by specifying their IDs followed by the content to say:
+- To talk to a single agent: Enter an agent ID (e.g. "1")
+- To talk to multiple agents: Enter IDs separated by commas (e.g. "1,2,3")
+- To talk to all agents: Enter "all"\
+"""
 talk_action = Action(
     name="talk",
-    description="Talk to the agent with the given ID.",
+    description=talk_action_description,
     parameters=["agent_id", "message"],
     function=talk_action_function,
 )

tests/test_agent.py

@@ -67,15 +67,15 @@ def test_agent_interaction(agent_pair):
     # Check Alice's interactions
     alice_interactions = alice.get_interactions()
     assert len(alice_interactions) == 1
-    assert alice_interactions[0].sender == alice
-    assert alice_interactions[0].receiver == bob
+    assert alice_interactions[0].sender.agent_id == alice.agent_id
+    assert alice_interactions[0].receiver[0].agent_id == bob.agent_id
     assert alice_interactions[0].message == message
 
     # Check Bob's interactions
     bob_interactions = bob.get_interactions()
     assert len(bob_interactions) == 1
-    assert bob_interactions[0].sender == alice
-    assert bob_interactions[0].receiver == bob
+    assert bob_interactions[0].sender.agent_id == alice.agent_id
+    assert bob_interactions[0].receiver[0].agent_id == bob.agent_id
     assert bob_interactions[0].message == message
 
 
@@ -89,8 +89,8 @@ def test_agent_think(agent_pair):
 
     interactions = agent.get_interactions()
     assert len(interactions) == 1
-    assert interactions[0].sender == agent
-    assert interactions[0].receiver == agent
+    assert interactions[0].sender.agent_id == agent.agent_id
+    assert interactions[0].receiver[0].agent_id == agent.agent_id
     assert interactions[0].message == thought
 
 
@@ -110,3 +110,35 @@ def test_agent_reset(base_agent):
     base_agent.reset()
     assert len(base_agent.get_interactions()) == 0
     assert len(base_agent.storage) == 0
+
+
+def test_display_interaction(agent_pair):
+    """Test displaying an interaction."""
+    alice, bob = agent_pair
+    message = "Hello Bob!"
+
+    alice.talk_to(bob, message)  # One receiver
+    alice.talk_to([bob, alice], message)  # Multiple receivers
+
+    # just check that it doesn't raise an error
+    print(alice.get_interactions()[0]) # one receiver
+    print(alice.get_interactions()[1]) # multiple receivers
+
+
+def test_agent_actions_manualy_executed(base_agent):
+    """Test agent actions."""
+
+    base_agent.add_action(Action("test", "A test action", ["message"], lambda message, *args, **kwargs: {"message": message}))
+
+    action = base_agent.execute_action("test", "test message")
+    assert action["message"] == "test message"
+
+
+def test_agent_actions_automatically_executed(base_agent):
+    """Test agent actions."""
+
+    base_agent.add_action(Action("test", "A test action", ["message"], lambda message, *args, **kwargs: {"message": message}))
+    base_agent.think("I need to do the action 'test' with the message 'test message'")
+
+    action = base_agent.act()
+    assert action["message"] == "test message"

tests/test_interaction_manager.py

@@ -1,7 +1,7 @@
 import pytest
-from agentarium import Agent, Interaction
-from agentarium.AgentInteractionManager import AgentInteractionManager
 
+from agentarium.Agent import Agent
+from agentarium.AgentInteractionManager import AgentInteractionManager
 
 @pytest.fixture
 def interaction_manager():
@@ -34,8 +34,8 @@ def test_interaction_recording(interaction_manager, agent_pair):
     assert len(alice.get_interactions()) == 1
 
     interaction = alice.get_interactions()[0]
-    assert interaction.sender is alice
-    assert interaction.receiver is bob
+    assert interaction.sender.agent_id == alice.agent_id
+    assert interaction.receiver[0].agent_id == bob.agent_id
     assert interaction.message == message
 
 def test_get_agent_interactions(interaction_manager, agent_pair):
@@ -89,16 +89,20 @@ def test_self_interaction(interaction_manager, agent_pair):
 
     interactions = interaction_manager.get_agent_interactions(alice)
     assert len(interactions) == 1
-    assert interactions[0].sender is alice
-    assert interactions[0].receiver is alice
+    assert interactions[0].sender.agent_id == alice.agent_id
+    assert interactions[0].receiver[0].agent_id == alice.agent_id
     assert interactions[0].message == thought
 
 def test_interaction_validation(interaction_manager, agent_pair):
     """Test validation of interaction recording."""
 
     alice, _ = agent_pair
 
-    unregistered_agent = type("UnregisteredAgent", (object,), {"agent_id": "some_unregistered_id"})
+    unregistered_agent = type("UnregisteredAgent", (Agent,), {
+        "agent_id": "some_unregistered_id",
+        "__init__": lambda self, *args, **kwargs: None,
+        "agent_informations": {},
+    })()
 
     with pytest.raises(ValueError):
         interaction_manager.record_interaction(unregistered_agent, alice, "Hello")