Add example for router agent

README.md

@@ -49,11 +49,11 @@ Start building LLM-empowered multi-agent applications in an easier way.
 
 - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-07-15]** AgentScope has implemented the Mixture-of-Agents algorithm. Refer to our [MoA example](https://github.com/modelscope/agentscope/blob/main/examples/conversation_mixture_of_agents) for more details.
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-14]** A new prompt tuning module is available in AgentScope to help developers generate and optimize the agents' system prompts! Refer to our [tutorial](https://modelscope.github.io/agentscope/en/tutorial/209-prompt_opt.html) for more details!
+- **[2024-06-14]** A new prompt tuning module is available in AgentScope to help developers generate and optimize the agents' system prompts! Refer to our [tutorial](https://modelscope.github.io/agentscope/en/tutorial/209-prompt_opt.html) for more details!
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-11]** The RAG functionality is available for agents in **AgentScope** now! [**A quick introduction to RAG in AgentScope**](https://modelscope.github.io/agentscope/en/tutorial/210-rag.html) can help you equip your agent with external knowledge!
+- **[2024-06-11]** The RAG functionality is available for agents in **AgentScope** now! [**A quick introduction to RAG in AgentScope**](https://modelscope.github.io/agentscope/en/tutorial/210-rag.html) can help you equip your agent with external knowledge!
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-09]** We release **AgentScope** v0.0.5 now! In this new version, [**AgentScope Workstation**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html) (the online version is running on [agentscope.io](https://agentscope.io)) is open-sourced with the refactored [**AgentScope Studio**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html)!
+- **[2024-06-09]** We release **AgentScope** v0.0.5 now! In this new version, [**AgentScope Workstation**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html) (the online version is running on [agentscope.io](https://agentscope.io)) is open-sourced with the refactored [**AgentScope Studio**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html)!
 
 - **[2024-05-24]** We are pleased to announce that features related to the **AgentScope Workstation** will soon be open-sourced! The online website services are temporarily offline. The online website service will be upgraded and back online shortly. Stay tuned...
 
@@ -163,12 +163,13 @@ the following libraries.
   - [Conversation with ReAct Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_react_agent)
   - [Conversation in Natural Language to Query SQL](https://github.com/modelscope/agentscope/blob/main/examples/conversation_nl2sql/)
   - [Conversation with RAG Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_RAG_agents)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation with gpt-4o](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_gpt-4o)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation with Software Engineering Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_swe-agent/)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation with Customized Tools](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_customized_services/)
+  - [Conversation with gpt-4o](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_gpt-4o)
+  - [Conversation with Software Engineering Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_swe-agent/)
+  - [Conversation with Customized Tools](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_customized_services/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Mixture of Agents Algorithm](https://github.com/modelscope/agentscope/blob/main/examples/conversation_mixture_of_agents/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation in Stream Mode](https://github.com/modelscope/agentscope/blob/main/examples/conversation_in_stream_mode/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation with CodeAct Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_codeact_agent/)
+  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Conversation with Router Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_router_agent/)
 
 
 - Game

README_ZH.md

@@ -50,11 +50,11 @@
 
 - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-07-15]** AgentScope 中添加了 Mixture of Agents 算法。使用样例请参考 [MoA 示例](https://github.com/modelscope/agentscope/blob/main/examples/conversation_mixture_of_agents)。
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-14]** 新的提示调优（Prompt tuning）模块已经上线 AgentScope，用以帮助开发者生成和优化智能体的 system prompt。更多的细节和使用样例请参考 AgentScope [教程](https://modelscope.github.io/agentscope/en/tutorial/209-prompt_opt.html)！
+- **[2024-06-14]** 新的提示调优（Prompt tuning）模块已经上线 AgentScope，用以帮助开发者生成和优化智能体的 system prompt。更多的细节和使用样例请参考 AgentScope [教程](https://modelscope.github.io/agentscope/en/tutorial/209-prompt_opt.html)！
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-11]** RAG功能现在已经整合进 **AgentScope** 中! 大家可以根据 [**简要介绍AgentScope中的RAG**](https://modelscope.github.io/agentscope/en/tutorial/210-rag.html) ，让自己的agent用上外部知识!
+- **[2024-06-11]** RAG功能现在已经整合进 **AgentScope** 中! 大家可以根据 [**简要介绍AgentScope中的RAG**](https://modelscope.github.io/agentscope/en/tutorial/210-rag.html) ，让自己的agent用上外部知识!
 
-- <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>**[2024-06-09]** AgentScope v0.0.5 已经更新！在这个新版本中，我们开源了 [**AgentScope Workstation**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html) (在线版本的网址是[agentscope.io](https://agentscope.io))！
+- **[2024-06-09]** AgentScope v0.0.5 已经更新！在这个新版本中，我们开源了 [**AgentScope Workstation**](https://modelscope.github.io/agentscope/en/tutorial/209-gui.html) (在线版本的网址是[agentscope.io](https://agentscope.io))！
 
 - **[2024-05-24]** 我们很高兴地宣布 **AgentScope Workstation** 相关功能即将开源。我们的网站服务暂时下线。在线服务会很快升级重新上线，敬请期待...
 
@@ -153,15 +153,13 @@ AgentScope支持使用以下库快速部署本地模型服务。
   - [与ReAct智能体对话](./examples/conversation_with_react_agent)
   - [通过对话查询SQL信息](./examples/conversation_nl2sql/)
   - [与RAG智能体对话](./examples/conversation_with_RAG_agents)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[与gpt-4o模型对话](./examples/conversation_with_gpt-4o)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[与自定义服务对话](./examples/conversation_with_customized_services/)
-
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[与SoftWare Engineering智能体对话](./examples/conversation_with_swe-agent/)
-  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[自定义工具函数](./examples/conversation_with_customized_services/)
+  - [与gpt-4o模型对话](./examples/conversation_with_gpt-4o)
+  - [自定义工具函数](./examples/conversation_with_customized_services/)
+  - [与SoftWare Engineering智能体对话](./examples/conversation_with_swe-agent/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Mixture of Agents算法](https://github.com/modelscope/agentscope/blob/main/examples/conversation_mixture_of_agents/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[流式对话](https://github.com/modelscope/agentscope/blob/main/examples/conversation_in_stream_mode/)
   - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[与CodeAct智能体对话](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_codeact_agent/)
-
+  - <img src="https://img.alicdn.com/imgextra/i3/O1CN01SFL0Gu26nrQBFKXFR_!!6000000007707-2-tps-500-500.png" alt="new" width="30" height="30"/>[Router Agent](https://github.com/modelscope/agentscope/blob/main/examples/conversation_with_router_agent/)
 
 - 游戏
   - [五子棋](./examples/game_gomoku)

examples/conversation_with_router_agent/README.md

@@ -0,0 +1,44 @@
+# Conversation with Router Agent
+
+This example will show
+- How to build a router agent to route questions to agents with different abilities.
+
+The router agent is expected to route questions to the corresponding agents according to the question type in the following response
+```text
+<thought>{The thought of router agent}</thought>
+<agent>{agent name}</agent>
+```
+If the router agent decides to answer the question itself, the response should be
+```text
+<thought>{The thought of router agent}</thought>
+<response>{The answer}</response>
+```
+
+## Note
+This example is only for demonstration purposes. We simply use two agents who are good at math and history respectively.
+You can replace them with any other agents according to your needs.
+
+Besides, the memory management of the involved agents is not considered in this example.
+For example, does the router agent need to know the answer from the sub-agents?
+Improvements are encouraged by developers according to their own needs.
+
+## Tested Models
+
+These models are tested in this example. For other models, some modifications may be needed.
+- gpt-4o
+- qwen-max
+
+
+## Prerequisites
+
+1. Fill your model configuration correctly in `main.py`.
+2. Install the latest version of Agentscope from GitHub.
+```bash
+git clone https://github.com/modelscope/agentscope.git
+cd agentscope
+pip install -e .
+```
+3. Run the example and input your questions.
+```bash
+python main.py
+```

examples/conversation_with_router_agent/main.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""The main script for the example of conversation with router agent."""
+from router_agent import RouterAgent
+
+import agentscope
+from agentscope.agents import DialogAgent, UserAgent
+
+# ================== Prepare model configuration =============================
+
+YOUR_MODEL_CONFIGURATION_NAME = "{YOUR_MODEL_CONFIGURATION_NAME}"
+YOUR_MODEL_CONFIGURATION = {
+    "config_name": YOUR_MODEL_CONFIGURATION_NAME,
+    # ...
+}
+
+# ============================================================================
+
+agentscope.init(
+    model_configs=YOUR_MODEL_CONFIGURATION,
+    project="Conversation with router agent",
+)
+
+# Let's build some working agents with different capabilities. For simplicity,
+# we just use the same agent. You can replace them with your own agents.
+agent_math = DialogAgent(
+    name="Math",
+    sys_prompt="You are a math assistant to help solve math problems.",
+    model_config_name=YOUR_MODEL_CONFIGURATION_NAME,
+)
+
+agent_history = DialogAgent(
+    name="History",
+    sys_prompt="You are an assistant who is good at history.",
+    model_config_name=YOUR_MODEL_CONFIGURATION_NAME,
+)
+
+# Init a router agent
+SYS_PROMPT_ROUTER = """You're a router assistant named {name}.
+
+## YOUR TARGET
+1. Given agents with different capabilities, your target is to assign questions to the corresponding agents according to the user requirement.
+2. You should make full use of the different abilities of the given agents.
+3. If no agent is suitable to answer user's question, then respond directly.
+
+## Agents You Can Use
+1. math: An agent who is good at math.
+2. history: An agent who is good at history.
+"""  # noqa
+
+router_agent = RouterAgent(
+    sys_prompt=SYS_PROMPT_ROUTER,
+    model_config_name=YOUR_MODEL_CONFIGURATION_NAME,
+)
+
+# Init a user agent
+user = UserAgent(name="user")
+
+# Start the conversation
+msg = None
+while True:
+    user_msg = user(msg)
+    if user_msg.content == "exit":
+        break
+
+    # Replied by router agent
+    router_msg = router_agent(user_msg)
+
+    # Route the question to the corresponding agents
+    if router_msg.metadata == "math":
+        msg = agent_math(user_msg)
+    elif router_msg.metadata == "history":
+        msg = agent_history(user_msg)
+    else:
+        # Answer the question by router agent directly
+        msg = router_msg

examples/conversation_with_router_agent/router_agent.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""The router agent which routes the questions to the corresponding agents."""
+from typing import Optional, Union, Sequence
+
+from agentscope.agents import AgentBase
+from agentscope.message import Msg
+from agentscope.parsers import RegexTaggedContentParser
+
+
+# Init a router agent
+class RouterAgent(AgentBase):
+    """
+    The router agent who routes the questions to the corresponding agents.
+    """
+
+    def __init__(
+        self,
+        sys_prompt: str,
+        model_config_name: str,
+    ) -> None:
+        """Init a router agent."""
+        self.name = "Router"
+
+        super().__init__(
+            name=self.name,
+            model_config_name=model_config_name,
+        )
+
+        self.sys_prompt = sys_prompt.format_map({"name": self.name})
+
+        self.memory.add(Msg(self.name, self.sys_prompt, "system"))
+
+        self.parser = RegexTaggedContentParser(
+            format_instruction="""Respond with specific tags as outlined below:
+
+- When routing questions to agents:
+<thought>what you thought</thought>
+<agent>the agent name, e.g. math, history</agent>
+
+- When answering questions directly:
+<thought>what you thought</thought>
+<response>what you respond</response>
+""",
+            required_keys=["thought"],
+        )
+
+    def reply(self, x: Optional[Union[Msg, Sequence[Msg]]] = None) -> Msg:
+        """The reply function."""
+        self.memory.add(x)
+
+        prompt = self.model.format(
+            self.memory.get_memory(),
+            Msg("system", self.parser.format_instruction, "system"),
+        )
+
+        response = self.model(prompt)
+
+        # To be compatible with streaming mode
+        self.speak(response.stream or response.text)
+
+        # Parse the response by predefined parser
+        parsed_dict = self.parser.parse(response).parsed
+
+        msg = Msg(self.name, response.text, "assistant")
+
+        # Assign the question to the corresponding agent in the metadata field
+        if "agent" in parsed_dict:
+            msg.metadata = parsed_dict["agent"]
+
+        self.memory.add(msg)
+
+        return msg