Update README.md for distributed_debate (#306)

examples/distributed_debate/README.md

@@ -1,54 +1,80 @@
-# Distributed debate competition
+# Distributed Debate Competition
 
-This example simulate a debate competition with three participant agents, including the affirmative side (**Pro**), the negative side (**Con**), and the adjudicator (**Judge**).
-**You can join in the debate as Pro or Con or both.**
+This example demonstrates:
+- How to simulate a debate competition with three participant agents
+- How to allow human participation in the debate
 
-Pro believes that AGI can be achieved using the GPT model framework, while Con contests it.
-Judge listens to both sides' arguments and provides an analytical judgment on which side presented a more compelling and reasonable case.
+## Background
 
-Each agent is an independent process and can run on different machines.
-You can join the debate as Pro or Con by providing the `--is-human` argument.
-Messages generated by any agents can be observed by other agents in the debate.
+This example simulates a debate competition with three participant agents:
+1. The affirmative side (**Pro**)
+2. The negative side (**Con**)
+3. The adjudicator (**Judge**)
 
-Before running the example, please install the distributed version of AgentScope, fill in your model configuration correctly in `configs/model_configs.json`, and modify the `model_config_name` field in `configs/debate_agent_configs.json` accordingly.
+The debate topic is whether AGI can be achieved using the GPT model framework. Pro argues in favor, while Con contests it. Judge listens to both sides' arguments and provides an analytical judgment on which side presented a more compelling case.
 
-### Step 1: setup Pro, Con agent servers
+Each agent is an independent process and can run on different machines. Human participants can join as Pro or Con.
 
+## Tested Models
+
+These models are tested in this example. For other models, some modifications may be needed.
+- Ollama Chat (qwen2:1.5b)
+- Dashscope Chat (qwen-Max)
+- Gemini Chat (gemini-pro)
+
+## Prerequisites
+
+Before running the example:
+- Install the distributed version of AgentScope by running
+```bash
+# On windows
+pip install -e .[distribute]
+# On mac / linux
+pip install -e .\[distribute\]
+```
+- Fill in your model configuration correctly in `configs/model_configs.json`
+- Modify the `model_config_name` field in `configs/debate_agent_configs.json` accordingly
+- Ensure the specified ports are available and IP addresses are accessible
+
+## Setup and Execution
+
+### Step 1: Setup Pro and Con agent servers
+
+For an LLM-based Pro:
 ```shell
 cd examples/distributed_debate
-# setup LLM-based Pro
 python distributed_debate.py --role pro --pro-host localhost --pro-port 12011
-# or join the debate as Pro by yourself
-# python distributed_debate.py --role pro --pro-host localhost --pro-port 12011 --is-human
 ```
 
+(Alternatively) for human participation as Pro:
+```shell
+python distributed_debate.py --role pro --pro-host localhost --pro-port 12011 --is-human
+```
+
+For an LLM-based Con:
 ```shell
-# setup LLM-base Con
 python distributed_debate.py --role con --con-host localhost --con-port 12012
-# or join the debate as Con by yourself
-# python distributed_debate.py --role con --con-host localhost --con-port 12012 --is-human
 ```
 
-> Please make sure the ports are available and the ip addresses are accessible, here we use localhost as an example.
-> If you run all agent servers on the same machine, you can ignore the host field, it will use localhost by default.
+(Alternatively) for human participation as Con:
+```shell
+python distributed_debate.py --role con --con-host localhost --con-port 12012 --is-human
+```
 
-### step 2: run the main process
+### Step 2: Run the main process
 
 ```shell
-# setup main (Judge is in it)
 python distributed_debate.py --role main --pro-host localhost --pro-port 12011 --con-host localhost --con-port 12012
 ```
 
-### step 3: watch or join in the debate in your terminal
+### Step 3: Watch or join the debate in your terminal
 
-Suppose you join the debate as Con, you will see the following in your command line.
+If you join as Con, you'll see something like:
 
 ```text
 System: Welcome to the debate on whether Artificial General Intelligence (AGI) can be achieved
 ...
-
 Pro: Thank you. I argue that AGI can be achieved using the GPT model framework.
 ...
-
 User Input:
 ```