Agent servers support running any type of agent

README.md

@@ -124,6 +124,7 @@ the following libraries.
   - [Distributed Conversation](./examples/distributed_basic)
   - [Distributed Debate](./examples/distributed_debate)
   - [Distributed Parallel Search](./examples/distributed_search)
+  - [Distributed Large Scale Simulation](./examples/distributed_simulation)
 
 More models, services and examples are coming soon!
 

README_ZH.md

@@ -113,6 +113,7 @@ AgentScope支持使用以下库快速部署本地模型服务。
   - [分布式对话](./examples/distributed_basic)
   - [分布式辩论](./examples/distributed_debate)
   - [分布式并行搜索](./examples/distributed_search)
+  - [分布式大规模仿真](./examples/distributed_simulation)
 
 更多模型API、服务和示例即将推出！
 

docs/sphinx_doc/en/source/conf.py

@@ -49,6 +49,11 @@
 
 autodoc_member_order = "bysource"
 
+autodoc_default_options = {
+    "members": True,
+    "special-members": "__init__",
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/sphinx_doc/en/source/tutorial/208-distribute.md

@@ -12,78 +12,166 @@ This tutorial will introduce the implementation and usage of AgentScope distribu
 
 ## Usage
 
-In AgentScope, the process that runs the application flow is called the "main process", and all agents will run in separate processes.
-According to the different relationships between the main process and the agent process, AgentScope supports two distributed modes: Master-Slave and Peer-to-Peer mode.
-In the Master-Slave mode, developers can start all agent processes from the main process, while in the Peer-to-Peer mode, the agent process is independent of the main process and developers need to start the agent service on the corresponding machine.
+In AgentScope, the process that runs the application flow is called the **main process**, and each agent can run in a separate process named **agent server process**.
+According to the different relationships between the main process and the agent server process, AgentScope supports two modes for each agent: **Child Process** and **Independent Process** mode.
 
-The above concepts may seem complex, but don't worry, for application developers, they only have minor differences when creating agents. Below we introduce how to create distributed agents.
+- In the Child Process Mode, agent server processes will be automatically started as sub-processes from the main process.
+- While in the Independent Process Mode, the agent server process is independent of the main process and developers need to start the agent server process on the corresponding machine.
 
-### Step 1: Create a Distributed Agent
+The above concepts may seem complex, but don't worry, for application developers, you only need to convert your existing agent to its distributed version.
 
-First, the developer's agent must inherit the `agentscope.agents.AgentBase` class. `AgentBase` provides the `to_dist` method to convert the agent into its distributed version. `to_dist` mainly relies on the following parameters to implement the distributed deployment of the agent:
+### Step 1: Convert your agent to its distributed version
 
-- `host`: the hostname or IP address of the machine where the agent runs, defaults to `localhost`.
-- `port`: the port of this agent's RPC server, defaults to `80`.
-- `launch_server`: whether to launch an RPC server locally, defaults to `True`.
+All agents in AgentScope can automatically convert to its distributed version by calling its {func}`to_dist<agentscope.agents.AgentBase.to_dist>` method.
+But note that your agent must inherit from the {class}`agentscope.agents.AgentBase<agentscope.agents.AgentBase>` class, because the `to_dist` method is provided by the `AgentBase` class.
 
 Suppose there are two agent classes `AgentA` and `AgentB`, both of which inherit from `AgentBase`.
 
-#### Master-Slave Mode
+```python
+a = AgentA(
+    name="A"
+    # ...
+)
+b = AgentB(
+    name="B"
+    # ...
+)
+```
+
+Next we will introduce the conversion details of both modes.
 
-In the Master-Slave mode, since all agent processes depend on the main process, all processes actually run on the same machine.
-We can start all agent processes from the main process, that is, the default parameters `launch_server=True` and `host="localhost"`, and we can omit the `port` parameter. AgentScope will automatically find an available local port for the agent process.
+#### Child Process Mode
+
+To use this mode, you only need to call each agent's `to_dist()` method without any input parameter. AgentScope will automatically start all agent server processes from the main process.
 
 ```python
+# Child Process mode
 a = AgentA(
     name="A"
     # ...
 ).to_dist()
+b = AgentB(
+    name="B"
+    # ...
+).to_dist()
 ```
 
-#### Peer-to-Peer Mode
+#### Independent Process Mode
 
-In the Peer-to-Peer mode, we need to start the service of the corresponding agent on the target machine first. For example, deploy an instance of `AgentA` on the machine with IP `a.b.c.d`, and its corresponding port is 12001. Run the following code on this target machine:
+In the Independent Process Mode, we need to start the agent server process on the target machine first.
+For example, start two agent server processes on the two different machines with IP `ip_a` and `ip_b`(called `Machine1` and `Machine2` accrodingly).
+You can run the following code on `Machine1`:
 
 ```python
-from agentscope.agents import RpcAgentServerLauncher
+# import some packages
 
+agentscope.init(
+    ...
+)
 # Create an agent service process
-server_a = RpcAgentServerLauncher(
-    agent_class=AgentA,
-    agent_kwargs={
-        "name": "A"
-        ...
-    },
-    host="a.b.c.d",
-    port=12001,
+server = RpcAgentServerLauncher(
+    host="ip_a",
+    port=12001,  # choose an available port
 )
 
 # Start the service
-server_a.launch()
-server_a.wait_until_terminate()
+server.launch()
+server.wait_until_terminate()
 ```
 
-Then, we can connect to the agent service in the main process with the following code. At this time, the object `a` created in the main process can be used as a local proxy for the agent, allowing developers to write the application flow in a centralized way in the main process.
+And run the following code on `Machine2`:
+
+```python
+# import some packages
+
+agentscope.init(
+    ...
+)
+# Create an agent service process
+server = RpcAgentServerLauncher(
+    host="ip_b",
+    port=12002, # choose an available port
+)
+
+# Start the service
+server.launch()
+server.wait_until_terminate()
+```
+
+Then, you can connect to the agent servers from the main process with the following code.
 
 ```python
 a = AgentA(
     name="A",
     # ...
 ).to_dist(
-    host="a.b.c.d",
+    host="ip_a",
     port=12001,
-    launch_server=False,
+)
+b = AgentB(
+    name="B",
+    # ...
+).to_dist(
+    host="ip_b",
+    port=12002,
+)
+```
+
+The above code will deploy `AgentA` on the agent server process of `Machine1` and `AgentB` on the agent server process of `Machine2`.
+And developers just need to write the application flow in a centralized way in the main process.
+
+#### Advanced Usage of `to_dist`
+
+All examples described above convert initialized agents into their distributed version through the {func}`to_dist<agentscope.agents.AgentBase.to_dist>` method, which is equivalent to initialize the agent twice, once in the main process and once in the agent server process.
+For agents whose initialization process is time-consuming, the `to_dist` method is inefficient. Therefore, AgentScope also provides a method to convert the Agent instance into its distributed version while initializing it, that is, passing in `to_dist` parameter to the Agent's initialization function.
+
+In Child Process Mode, just pass `to_dist=True` to the Agent's initialization function.
+
+```python
+# Child Process mode
+a = AgentA(
+    name="A",
+    # ...
+    to_dist=True
+)
+b = AgentB(
+    name="B",
+    # ...
+    to_dist=True
+)
+```
+
+In Independent Process Mode, you need to encapsulate the parameters of the `to_dist()` method in  {class}`DistConf<agentscope.agents.DistConf>` instance and pass it into the `to_dist` field, for example:
+
+```python
+a = AgentA(
+    name="A",
+    # ...
+    to_dist=DistConf(
+        host="ip_a",
+        port=12001,
+    ),
+)
+b = AgentB(
+    name="B",
+    # ...
+    to_dist=DistConf(
+        host="ip_b",
+        port=12002,
+    ),
 )
 ```
 
+Compared with the original `to_dist()` function call, this method just initializes the agent once in the agent server process.
+
 ### Step 2: Orchestrate Distributed Application Flow
 
 In AgentScope, the orchestration of distributed application flow is exactly the same as non-distributed programs, and developers can write the entire application flow in a centralized way.
 At the same time, AgentScope allows the use of a mixture of locally and distributed deployed agents, and developers do not need to distinguish which agents are local and which are distributed.
 
 The following is the complete code for two agents to communicate with each other in different modes. It can be seen that AgentScope supports zero-cost migration of distributed application flow from centralized to distributed.
 
-- All agents are centralized:
+- All agents are centralized
 
 ```python
 # Create agent objects
@@ -104,7 +192,9 @@ while x is None or x.content == "exit":
     x = b(x)
 ```
 
-- Agents are deployed in a distributed manner (Master-Slave mode):
+- Agents are deployed in a distributed manner
+  - `AgentA` in Child Process mode
+  - `AgentB` in Independent Process Mode
 
 ```python
 # Create agent objects
@@ -116,7 +206,10 @@ a = AgentA(
 b = AgentB(
     name="B",
     # ...
-).to_dist()
+).to_dist(
+    host="ip_b",
+    port=12002,
+)
 
 # Application flow orchestration
 x = None
@@ -148,9 +241,20 @@ By implementing each Agent as an Actor, an Agent will automatically wait for its
 
 #### PlaceHolder
 
-Meanwhile, to support centralized application orchestration, AgentScope introduces the concept of Placeholder. A Placeholder is a special message that contains the address and port number of the agent that generated the Placeholder, which is used to indicate that the input message of the Agent is not ready yet.
-When the input message of the Agent is ready, the Placeholder will be replaced by the real message, and then the actual `reply` method will be executed.
+Meanwhile, to support centralized application orchestration, AgentScope introduces the concept of {class}`Placeholder<agentscope.message.PlaceholderMessage>`.
+A Placeholder is a special message that contains the address and port number of the agent that generated the placeholder, which is used to indicate that the output message of the Agent is not ready yet.
+When calling the `reply` method of a distributed agent, a placeholder is returned immediately without blocking the main process.
+The interface of placeholder is exactly the same as the message, so that the orchestration flow can be written in a centralized way.
+When getting values from a placeholder, the placeholder will send a request to get the real values from the source agent.
+A placeholder itself is also a message, and it can be sent to other agents, and let other agents to get the real values, which can avoid sending the real values multiple times.
 
 About more detailed technical implementation solutions, please refer to our [paper](https://arxiv.org/abs/2402.14034).
 
+#### Agent Server
+
+In agentscope, the agent server provides a running platform for various types of agents.
+Multiple agents can run in the same agent server and hold independent memory and other local states but they will share the same computation resources.
+As long as the code is not modified, an agent server can provide services for multiple main processes.
+This means that when running mutliple applications, you only need to start the agent server for the first time, and it can be reused subsequently.
+
 [[Back to the top]](#208-distribute-en)