Feat support private messages (#330)

* Add scenarios from NegotiationArena

* [autofix.ci] apply automated fixes

* Refactor negotiation arena examples and update .gitignore

Refactored negotiation arena example scripts to use more explicit typing, improved agent profile retrieval logic, and removed unused OpenAI API key loading. Updated .gitignore to exclude negotiation_arena redis-data directory.

* Fix Mypy type errors in negotiation arena files

* Modify error handling and update readme

* Add multi-agent support for 3+ agents

* Add multi-agent test suite with documentation and examples

* Fix unused variable in evaluators

* Unify classes for all agent scenarios

Remove separation between 2-agent and multi-agent cases by consolidating duplicate classes and logic paths into unified implementations

* Support private messages (WIP)

* Add example of multi-agent private message

* Add field `to` for private messages

* Improve private message example

* Don't use special `private_message` action type, use `to` for all types

* change made on PM framework. check out envs/parallel.py for updates

* Remove manual backup of `envs/parallel.py`

* Remove unused `_actions_to_natural_language`

* Format with ruff

* Add README for `multi_agents_private_dm` example

* Fix typo in `test_rule_based_terminated_evaluator`

* changes in dm

* [autofix.ci] apply automated fixes

* Fix typing

* Remove commented code

* Make mypy happy

* Debug evaluator not collecting all agents' evaluation

* Try fix evaluator

* Make mypy happy

* [autofix.ci] apply automated fixes

* Update uv lock

* Remove debug prints

* Clean up evaluator agent counting

* [autofix.ci] apply automated fixes

* Format with ruff

* fixup! Clean up evaluator agent counting

* Remove unnecessary git ignores

* Remove private inbox, handle DM in observation creation

* Remove extraneous comments

* Remove changes under `examples/experimental/multi_agent_tests` from Keyu

* Add negotiation arena test

* Remove unused method

* Remove some comments to reduce diff

* Reduce diffs

* Simplify README

* Fix breaking change in `to_natural_language()`

* Fix typo

* Make `to` instructions clearer in system prompt

* Remove trick in evaluator

* Validate `to` field

* Make `to` error more detailed

* Add test for private messages

* Add test for invalid message recipients

* Use multi-agents in private message routing test

* Use pydantic field validator to check and filter `to` field in actions

* Remove private message specific hints in general prompt

* Fix action type in sampled actions being int instead of str literal

* Clean up parallel env tests

* [autofix.ci] apply automated fixes

* Validate instead of filtering `to` field in agent actions

* Regenerate when `to` field contains invalid names

* [autofix.ci] apply automated fixes

* Avoid unnecessary comment change

* Add tests to ensure private message is not visible to non-recipients

* Include private message `to` info in `AgentAction.to_natural_language()`

* merging docs

* modify pytest

---------

Co-authored-by: Keyu(Frank) He <[email protected]>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: rcwang937 <[email protected]>
Co-authored-by: Xuhui Zhou <[email protected]>

Author: 5 people

docs/pages/concepts/agents.md

@@ -3,10 +3,29 @@
 Agent is a concept in Sotopia to represent decision-making entities that can interact with each other in a social environment. Agents can be human participants, AI models, or other entities.  No matter which type of agent, they have the same interface to interact with the environment: the input is an [`Observation`](/python_API/messages/message_classes#observation) and the output is an [`AgentAction`](/python_API/messages/message_classes#agentaction), each of which is a subclass of [`Message`](/python_API/messages/message_classes#message). You can think of the environment and the agents are sending messages to each other, while the message from the environment is the observation for the agents, and the message from each of the agents is the action that they want to take in the environment. In Sotopia, we are simulating the interaction between agents with social roles, which includes both human characters and various AI assistants, which are defined as profiles [`AgentProfile`](/python_API/database/persistant_profile#agentprofile-class).
 
 ### Actions of agents
-The types of action is defined by the `ActionType` type alias, which is a literal type that can only take one of the following values: `none`, `speak`, `non-verbal communication`, `action`, `leave`. An agent can choose to n perform physical actions (`action`), use language (`speak`) or gestures or facial expressions (`non-verbal communication`) to communicate, or choose to do nothing (`none`), or leave the interaction (`leave`).
+The types of action is defined by the `ActionType` type alias, which is a literal type that can only take one of the following values: `none`, `speak`, `non-verbal communication`, `action`, `leave`. An agent can choose to perform physical actions (`action`), use language (`speak`) or gestures or facial expressions (`non-verbal communication`) to communicate, or choose to do nothing (`none`), or leave the interaction (`leave`).
 
 Apart from the type of action, the content of the action, e.g. the utterance, the concrete action, etc., is a free-form string in the `argument` attribute of the `AgentAction` class.
 
+#### Private Messages
+Agents can send private messages to specific recipients using the `to` field in `AgentAction`. When an action includes a `to` field with a list of recipient agent names:
+- The action is only visible to the sender and the specified recipients
+- Other agents will not see the private message in their observations
+- This enables private conversations, secret planning, and side-channel communication in multi-agent scenarios
+
+Example:
+```python
+# Public message (visible to all)
+action = AgentAction(action_type="speak", argument="Hello everyone!")
+
+# Private message (visible only to sender and "agent2")
+private_action = AgentAction(
+    action_type="speak",
+    argument="Psst, let's discuss this privately",
+    to=["agent2"]
+)
+```
+
 ### Profiles of agents
 The profiles of agents are passed in as either of two argument of [the constructor of agents](/python_API/agents/base_agent_api_docs#constructor): `uuid_str` or `agent_profile`. The `uuid_str` is used together with the Redis database to retrieve an agent profile, while the `agent_profile` is a Pydantic `AgentProfile` object.
 We strong recommend to use `uuid_str`, as it can more easily be used with other sotopia tools.
@@ -28,5 +47,5 @@ from sotopia.messages.message_classes import AgentAction, Observation
 
 class HelloWorldAgent(BaseAgent):
     async def aact(self, observation: Observation) -> AgentAction:
-        return AgentAction(type="speak", argument="Hello, world!")
+        return AgentAction(action_type="speak", argument="Hello, world!")
 ```

docs/pages/examples/examples.mdx

@@ -19,3 +19,35 @@ python examples/benchmark_evaluator.py --push-to-db --model=<the model used to b
 
 ## Example 2: Generate script-like episodes
 See `docs/simulation_modes.md` for more information.
+
+## Example 3: Multi-Agent Private Messages
+Sotopia supports private messaging between agents, allowing agents to send messages that are only visible to specific recipients. This enables private conversations, secret planning, and side-channel communication in multi-agent scenarios.
+
+See `examples/experimental/multi_agents_private_dm/README.md` for more information and example scripts.
+
+### Quick Example
+```python
+from sotopia.messages import AgentAction
+from sotopia.envs import ParallelSotopiaEnv
+
+# Create actions with private messages
+actions = {
+    "agent1": AgentAction(
+        action_type="speak",
+        argument="Psst, agent2, let's discuss this privately",
+        to=["agent2"]  # Only visible to agent1 and agent2
+    ),
+    "agent2": AgentAction(
+        action_type="speak",
+        argument="Hello everyone!"  # Public message, visible to all
+    ),
+    "agent3": AgentAction(
+        action_type="speak",
+        argument="I'll talk to agent1",
+        to=["agent1"]  # Only visible to agent1 and agent3
+    ),
+}
+
+# Each agent will see different observations based on message visibility
+observations, rewards, done, truncations, info = env.step(actions)
+```

docs/pages/index.mdx

@@ -51,7 +51,8 @@ with <Link href="https://sotopia.world/"><span className="font-display text-xl">
       <AccordionTrigger> Realistic social interaction </AccordionTrigger>
       <AccordionContent>
         <ul>
-          <li>Agents can talk, do non-verbal communication and performance physical actions.</li>
+          <li>Agents can talk, do non-verbal communication and perform physical actions.</li>
+          <li>Agents can send private messages to specific recipients, enabling secret conversations and side-channel communication.</li>
           <li>Characters have different personalities, backgrounds, and relationships.</li>
           <li>Agents can have different goals and motivations.</li>
         </ul>

docs/pages/python_API/envs/parallel.md

@@ -12,8 +12,8 @@ import random
 from typing import Any, Literal, Optional, Type, TypeVar
 from gin import configurable
 from gymnasium.spaces.dict import Dict
-from gymnasium.spaces.discrete import Discrete
 from gymnasium.spaces.text import Text
+from gymnasium.spaces import Space
 from pettingzoo.utils.env import ParallelEnv
 from redis_om.model.model import NotFoundError
 from sotopia.agents.llm_agent import Agents
@@ -95,10 +95,13 @@ def step(
     dict[str, dict[Any, Any]]
 ]
 ```
-Executes actions and returns new states.
+Executes actions and returns new states. Observations are filtered per-agent based on private message visibility.
 
 ##### Parameters
-- `actions` (dict[str, AgentAction] | dict[str, dict[str, int | str]]): Actions taken by agents.
+- `actions` (dict[str, AgentAction] | dict[str, dict[str, int | str]]): Actions taken by agents. Each action can be:
+  - An `AgentAction` object
+  - A dictionary with `action_type` (string literal like `"speak"`, `"none"`, etc.) and `argument` (string)
+  - Optionally includes a `to` field (list of strings) for private messages
 
 ##### Returns
 - `tuple[
@@ -109,6 +112,11 @@ Executes actions and returns new states.
         dict[str, dict[Any, Any]]
     ]`: Next state information, including observations, rewards, terminals, truncations, and additional info.
 
+##### Private Message Visibility
+- **Public actions** (no `to` field or `to=None`): Visible to all agents in their observations
+- **Private actions** (with `to` field): Only visible to the sender and agents listed in `to`
+- Each agent receives a filtered observation containing only actions they can see
+
 #### Usage Example
 ```python
 next_obs, rewards, done, truncations, info = env.step(actions)
@@ -126,10 +134,13 @@ async def astep(
     dict[str, dict[Any, Any]]
 ]
 ```
-Asynchronous version of `step`.
+Asynchronous version of `step`. Observations are filtered per-agent based on private message visibility.
 
 ##### Parameters
-- `actions` (dict[str, AgentAction] | dict[str, dict[str, int | str]]): Actions taken by agents.
+- `actions` (dict[str, AgentAction] | dict[str, dict[str, int | str]]): Actions taken by agents. Each action can be:
+  - An `AgentAction` object
+  - A dictionary with `action_type` (string literal like `"speak"`, `"none"`, etc.) and `argument` (string)
+  - Optionally includes a `to` field (list of strings) for private messages
 
 ##### Returns
 - `tuple[
@@ -140,6 +151,11 @@ Asynchronous version of `step`.
         dict[str, dict[Any, Any]]
     ]`: Next state information, including observations, rewards, terminals, truncations, and additional info.
 
+##### Private Message Visibility
+- **Public actions** (no `to` field or `to=None`): Visible to all agents in their observations
+- **Private actions** (with `to` field): Only visible to the sender and agents listed in `to`
+- Each agent receives a filtered observation containing only actions they can see
+
 #### Usage Example
 ```python
 next_obs, rewards, done, truncations, info = await env.astep(actions)
@@ -161,11 +177,13 @@ Close the environment (not implemented).
 
 ## Utility Functions
 
-### `_actions_to_natural_language`
+### `_actions_to_natural_language_for_viewer`
 ```python
-def _actions_to_natural_language(actions: dict[str, AgentAction]) -> str
+def _actions_to_natural_language_for_viewer(
+    actions: dict[str, AgentAction], viewer: str
+) -> str
 ```
-Converts agent actions to human-readable language.
+Converts agent actions to human-readable language, filtered for a specific viewer. Private messages are only included if the viewer is the sender or a recipient.
 
 ### `_map_gender_to_adj`
 ```python
@@ -206,6 +224,14 @@ Renders text viewable by a specific agent using XMLRenderer.
 
 ---
 
+## Action Space
+
+The action space for each agent is a `Dict` space with:
+- `action_type`: A `LiteralSpace` that samples string literals (e.g., `"speak"`, `"none"`, `"action"`) from `available_action_types`
+- `argument`: A `Text` space (max 256 characters) for the action content
+
+**Note**: The `action_type` is now a string literal, not an integer index. When sampling from the action space, you'll get strings like `"speak"` instead of integers like `0`.
+
 ## Usage Example
 Here's a typical usage example starting an episode in the environment:
 
@@ -221,15 +247,46 @@ observations = env.reset(
     seed=42,
     agents={
         "agent_1": Agent(...),
-        "agent_2": Agent(...)
+        "agent_2": Agent(...),
+        "agent_3": Agent(...)
     },
     omniscient=True
 )
 
-# Perform actions
+# Perform public actions (visible to all)
 actions = {
-    "agent_1": AgentAction(action_type="speak", argument="Hello!"),
+    "agent_1": AgentAction(action_type="speak", argument="Hello everyone!"),
     "agent_2": AgentAction(action_type="action", argument="waved"),
+    "agent_3": AgentAction(action_type="speak", argument="Hi there!"),
 }
 
 next_obs, rewards, done, truncations, info = env.step(actions)
+
+# Perform actions with private messages
+actions_with_private = {
+    "agent_1": AgentAction(
+        action_type="speak",
+        argument="Psst, agent_2, let's discuss this privately",
+        to=["agent_2"]  # Only visible to agent_1 and agent_2
+    ),
+    "agent_2": AgentAction(action_type="speak", argument="Hello everyone!"),  # Public
+    "agent_3": AgentAction(
+        action_type="speak",
+        argument="I'll talk to agent_1",
+        to=["agent_1"]  # Only visible to agent_1 and agent_3
+    ),
+}
+
+next_obs, rewards, done, truncations, info = env.step(actions_with_private)
+
+# Check observations - each agent sees different things
+print("Agent 1 sees:", next_obs["agent_1"].last_turn)
+# Includes both private messages (from agent_1 and agent_3) and public message from agent_2
+
+print("Agent 2 sees:", next_obs["agent_2"].last_turn)
+# Includes private message from agent_1 and public message from agent_2
+
+print("Agent 3 sees:", next_obs["agent_3"].last_turn)
+# Includes private message from agent_3 and public message from agent_2
+# Does NOT include the private message from agent_1 to agent_2
+```

docs/pages/python_API/messages/message_classes.md

@@ -74,16 +74,32 @@ Represents the environment's response to the interaction.
 
 ### `AgentAction`
 
-Represents an action taken by an agent.
+Represents an action taken by an agent. Actions can be either public (visible to all agents) or private (visible only to specific recipients).
 
 #### Attributes
 
-- `action_type: ActionType`: The type of action.
-- `argument: str`: The argument associated with the action.
+- `action_type: ActionType`: The type of action. Can be one of: `"none"`, `"speak"`, `"non-verbal communication"`, `"action"`, or `"leave"`.
+- `argument: str`: The argument associated with the action (e.g., the utterance for `"speak"`, the description for `"action"`).
+- `to: list[str] | None`: (Optional) List of recipient agent names. When specified, the action is a private message visible only to the sender and the listed recipients. When `None` or empty, the action is public and visible to all agents. Defaults to `None`.
 
 #### Methods
 
-- `to_natural_language(self) -> str`: Returns a string describing the agent's action.
+- `to_natural_language(self) -> str`: Returns a string describing the agent's action. Private messages are prefixed with `[private to {recipients}]`.
+
+#### Private Messages
+
+Private messages allow agents to communicate privately with specific recipients. When an action has a `to` field specified:
+
+- The action is only visible to the sender and the agents listed in `to`
+- Other agents will not see the action in their observations
+- The `to` field is validated to ensure recipients are valid agent names and the sender cannot target themselves
+
+#### Validation
+
+The `to` field is validated when creating an `AgentAction` with context:
+- Recipients must be valid agent names in the environment
+- Senders cannot send private messages to themselves
+- Invalid recipients will raise a `ValueError` with details about allowed recipients
 
 ### `ScriptInteraction`
 
@@ -134,8 +150,19 @@ response = ScriptEnvironmentResponse(
 )
 print(response.to_natural_language())
 
+# Public action (visible to all agents)
 action = AgentAction(action_type="speak", argument="Hello, how can I help you?")
 print(action.to_natural_language())
+# Output: said: "Hello, how can I help you?"
+
+# Private action (visible only to sender and specified recipients)
+private_action = AgentAction(
+    action_type="speak",
+    argument="Psst, let's discuss this privately",
+    to=["agent2", "agent3"]
+)
+print(private_action.to_natural_language())
+# Output: [private to ['agent2', 'agent3']] said: "Psst, let's discuss this privately"
 
 interaction_script = """
 Turn #1

examples/experimental/multi_agents_private_dm/README.md

@@ -0,0 +1,12 @@
+# Multi-Agent Tests
+
+This directory contains test scenarios for Sotopia's multi-agent (3+ agents)
+with private action support.
+
+Run the demo script:
+
+```sh
+mkdir -p examples/experimental/multi_agents_private_dm/redis-data
+redis-stack-server --dir examples/experimental/multi_agents_private_dm/redis-data
+uv run examples/experimental/multi_agents_private_dm/multi_agents_private_dm.py
+```