Merge pull request #93 from alipay/dev_fanen

Add: peer case docs. Fix：only check dashscope key when used instead of init

agentuniverse/agent/action/knowledge/embedding/dashscope_embedding.py

@@ -8,6 +8,7 @@
 import aiohttp
 import requests
 from typing import List, Generator, Optional
+from pydantic import Field
 import json
 
 from agentuniverse.base.util.env_util import get_from_env
@@ -27,14 +28,9 @@ def batched(inputs: List,
 
 class DashscopeEmbedding(Embedding):
     """The Dashscope embedding class."""
-    dashscope_api_key: Optional[str] = None
-
-    def __init__(self, **kwargs):
-        """Initialize the dashscope embedding class, need dashscope api key."""
-        super().__init__(**kwargs)
-        self.dashscope_api_key = get_from_env("DASHSCOPE_API_KEY")
-        if not self.dashscope_api_key:
-            raise Exception("No DASHSCOPE_API_KEY in your environment.")
+    dashscope_api_key: Optional[str] = Field(
+        default_factory=lambda: get_from_env("DASHSCOPE_API_KEY")
+    )
 
 
     def get_embeddings(self, texts: List[str]) -> List[List[float]]:
@@ -69,7 +65,8 @@ class DashscopeEmbedding(Embedding):
             )
             resp_json = response.json()
             return resp_json
-
+        if not self.dashscope_api_key:
+            raise Exception("No DASHSCOPE_API_KEY in your environment.")
         result = []
         post_params = {
             "model": self.embedding_model_name,
@@ -128,7 +125,8 @@ class DashscopeEmbedding(Embedding):
                 ) as resp:
                     resp_json = await resp.json()
             return resp_json
-
+        if not self.dashscope_api_key:
+            raise Exception("No DASHSCOPE_API_KEY in your environment.")
         result = []
         post_params = {
             "model": self.embedding_model_name,

docs/guidebook/en/0_index.md

@@ -82,6 +82,8 @@
 * 6.2 ReAct-Type Agent Examples
   * 6.2.1 [Python Code Generation and Execution Agent](7_1_1_Python_Auto_Runner.md)
 * 6.3 [Discussion Group Based on Multi-Turn Multi-Agent Mode](6_2_1_Discussion_Group.md)
+* 6.4 PEER Multi-Agent Cooperation Examples
+  * 6.4.1 [Financial Event Analysis Case](./6_4_1_Financial_Event_Analysis_Case.md)
 
 **7. Series of Articles**
 

docs/guidebook/en/6_4_1_Financial_Event_Analysis_Case.md

@@ -0,0 +1,75 @@
+# Financial Event Analysis Case
+## Case Description
+This case is based on PeerPlanner and showcases a multi-agent collaborative example for analyzing financial events. Regarding the topic of "Buffett's 2023 Reduction in BYD Shares"， it demonstrates how to use the PEER multi-agent collaboration model in agentUniverse and details the configuration and output examples for each agent in PEER.
+
+This case study utilizes the GPT-4o model by OPENAI. Before using it, you need to configure the `OPENAI_API_KEY` in your environment variables.
+
+## Agents
+### Planning Agent 
+Reference the original code files:
+- [Configuration file](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_planning_agent.yaml)
+- [Prompt file](../../../sample_standard_app/app/core/prompt/planning_agent_cn.yaml)  
+
+The Planning Agent is responsible for breaking down the original financial problem into multiple sub-problems that can be individually solved and provided to the subsequent Executing Agent. In this case, the original question "Analyze the reasons for Buffett's reduction in BYD shares" can be decomposed into several sub-questions as shown in the diagram below:
+![planning_result](../_picture/6_4_1_planning_result.png)
+You can debug the Planning Agent individually in the [test file](../../../sample_standard_app/app/test/test_planning_agent.py).
+
+### Executing Agent 
+Reference the original code files:
+- [Configuration file](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_executing_agent.yaml)
+- [Prompt file](../../../sample_standard_app/app/core/prompt/executing_agent_cn.yaml)
+
+In this Agent, we provide a tool [google_search_tool](../../../sample_standard_app/app/core/tool/google_search_tool.py) for searching information on Google. To use this tool, you should configure `SERPER_API_KEY` in your environment. For convenience, if `SERPER_API_KEY ` is not configured, this tool will return a pre-set query result related to this case, which you can find in the [mock_search_tool](../../../sample_standard_app/app/core/tool/mock_search_tool.py).
+
+
+The Executing Agent is responsible for solving the sub-problems broken down by the Planning Agent. In this case, the execution results of the Executing Agent are as follows:  
+![executing_result](../_picture/6_4_1_executing_result.png)
+The result is lengthy, so only the execution results of the first two questions are shown here. You can debug the Executing Agent individually in the [test file](../../../sample_standard_app/app/test/test_executing_agent.py) to obtain the complete results.
+
+### Expressing Agent 
+Reference the original code files:
+- [Configuration file](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_expressing_agent.yaml)
+- [Prompt file](../../../sample_standard_app/app/core/prompt/expressing_agent_cn.yaml)  
+
+The Expressing Agent is responsible for summarizing all the results output by the Executing Agent and formulating them into an answer to the original question according to the requirements in the prompt file. In this case, the output result of the Expressing Agent is as follows:
+![expressing_result](../_picture/6_4_1_expressing_result.png)
+You can debug the Expressing Agent individually in the [test file](../../../sample_standard_app/app/test/test_expressing_agent.py).
+
+### Reviewing Agent 
+Reference the original code files:
+- [Configuration file](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_reviewing_agent.yaml)
+
+The Reviewing Agent is responsible for evaluating whether the result produced by the Expressing Agent is an effective answer to the original question. In this case, the Reviewing Agent accepted the answer from the Expressing Agent:
+![reviewing_result](../_picture/6_4_1_reviewing_result.png)
+You can debug the Reviewing Agent individually in the [test file](../../../sample_standard_app/app/test/test_reviewing_agent.py).
+
+### PEER Agent 
+```yaml
+info:
+  name: 'demo_peer_agent'
+  description: 'demo peer agent'
+plan:
+  planner:
+    name: 'peer_planner'
+    eval_threshold: 60
+    retry_count: 2
+    planning: 'demo_planning_agent'
+    executing: 'demo_executing_agent'
+    expressing: 'demo_expressing_agent'
+    reviewing: 'demo_reviewing_agent'
+metadata:
+  type: 'AGENT'
+  module: 'agentuniverse.agent.default.peer_agent.peer_agent'
+  class: 'PeerAgent'
+```
+Users can configure the four Agents mentioned above into a complete PEER Agent through the `peer_planner` collaboration model. The configurations include:
+- name: Fixed as `peer_planner`, indicating the use of the PEER multi-agent collaboration model.
+- eval_threshold: The minimum score for the Reviewing Agent to accept the answer.
+- retry_count: The number of retries for the PEER Agent if the Reviewing Agent does not accept the answer.
+- planning：The Agent responsible for the Plan part.
+- executing：The Agent responsible for the Execute part.
+- expressing：The Agent responsible for the Express part.
+- reviewing：The Agent responsible for the Review part.
+
+You can run the complete case in the [example file](../../../sample_standard_app/app/examples/peer_chat_bot.py).
+

docs/guidebook/zh/0_目录.md

@@ -86,6 +86,8 @@
 * 6.2 ReAct类Agent案例
   * 6.2.1 [Python代码生成与执行Agent](7_1_1_Python自动执行案例.md)
 * 6.3 [基于多轮多Agent的讨论小组](6_2_1_讨论组.md)
+* 6.4 PEER多Agent协作案例
+  * 6.4.1 [金融事件分析案例](./6_4_1_金融事件分析案例.md)
 
 **7.系列文章**
 

docs/guidebook/zh/6_4_1_金融事件分析案例.md

@@ -0,0 +1,75 @@
+# 金融事件分析案例
+## 案例说明
+本案例基于PeerPlanner，搭建了一个用于分析金融事件的多智能体协作案例，并以“巴菲特2023年减持比亚迪”事件为例，展示了如何在agentUniverse中使用PEER多智能体协作模式，并详细展示了PEER中每种智能体的配置方式及输出样例。
+
+该案例基于OPENAI的gpt-4o模型，使用前需要您在环境变量中配置`OPENAI_API_KEY`。
+
+## Agents
+### Planning Agent 
+原始代码文件可参考
+- [配置文件](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_planning_agent.yaml)
+- [提示词](../../../sample_standard_app/app/core/prompt/planning_agent_cn.yaml)  
+
+Planning Agent负责将原始的金融问题拆分为多个可被单独解决的子问题，提供给后续的Executing Agent执行。在这个案例中，原始问题“分析下巴菲特减持比亚迪的原因”可以被拆解为下图中的数个子问题：  
+![planning_result](../_picture/6_4_1_planning_result.png)
+您可以在[测试文件](../../../sample_standard_app/app/test/test_planning_agent.py)中单独调试Planning Agent。
+
+### Executing Agent 
+原始代码文件可参考
+- [配置文件](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_executing_agent.yaml)
+- [提示词](../../../sample_standard_app/app/core/prompt/executing_agent_cn.yaml)
+
+在这个Agent中，我们提供了一个用于在google上搜索信息的工具[google_search_tool](../../../sample_standard_app/app/core/tool/google_search_tool.py)，该工具的使用需要在环境信息中配置`SERPER_API_KEY`。为了方便您进行简单的尝试，当环境配置中没有`SERPER_API_KEY`时，该工具会返回一段预设好的关于本案例问题的查询结果，具体内容您可以在[mock_search_tool](../../../sample_standard_app/app/core/tool/mock_search_tool.py)中查看。
+
+
+Executing Agent负责解决Planning Agent拆分出的子问题。在本案例中，Executing Agent对拆解问题的执行结果如下：  
+![executing_result](../_picture/6_4_1_executing_result.png)
+结果较长，这里只展示了前两问的执行结果。您可以在[测试文件](../../../sample_standard_app/app/test/test_executing_agent.py)中单独调试Executing Agent获得完整的结果。
+
+### Expressing Agent 
+原始代码文件可参考
+- [配置文件](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_expressing_agent.yaml)
+- [提示词](../../../sample_standard_app/app/core/prompt/expressing_agent_cn.yaml)  
+
+Expressing Agent负责将Executing Agent输出的所有结果进行汇总，并根据提示词中的要求总结表达为对原始问题的回答，在该案例中，Expressing Agent的输出结果如下：  
+![expressing_result](../_picture/6_4_1_expressing_result.png)
+您可以在[测试文件](../../../sample_standard_app/app/test/test_expressing_agent.py)中单独调试Expressing Agent。
+
+### Reviewing Agent 
+原始代码文件可参考
+- [配置文件](../../../sample_standard_app/app/core/agent/peer_agent_case/demo_reviewing_agent.yaml)
+
+Reviewing Agent负责对Expressing Agent产出的结果进行评价，看是否对于原问题是有效的回答，在本案例中，Reviewing Agent接受了Expressing Agent的答案：  
+![reviewing_result](../_picture/6_4_1_reviewing_result.png)
+您可以在[测试文件](../../../sample_standard_app/app/test/test_reviewing_agent.py)中单独调试Reviewing Agent。
+
+### PEER Agent 
+```yaml
+info:
+  name: 'demo_peer_agent'
+  description: 'demo peer agent'
+plan:
+  planner:
+    name: 'peer_planner'
+    eval_threshold: 60
+    retry_count: 2
+    planning: 'demo_planning_agent'
+    executing: 'demo_executing_agent'
+    expressing: 'demo_expressing_agent'
+    reviewing: 'demo_reviewing_agent'
+metadata:
+  type: 'AGENT'
+  module: 'agentuniverse.agent.default.peer_agent.peer_agent'
+  class: 'PeerAgent'
+```
+用户可以通过配置文件的形式将上文中的四个Agent经由`peer_planner`的协作模式，组装为完整的PEER Agent。其中：
+- name: 固定为`peer_planner`，表示该Agent使用了PEER多智能体协作模式。
+- eval_threshold: 表示Reviewing Agent采纳答案时的最低分数。
+- retry_count: 表示Reviewing Agent未采纳答案后，PEER Agent的重试次数
+- planning：负责Plan部分的Agent名称
+- executing：负责Execute部分的Agent名称
+- expressing：负责Express部分的Agent名称
+- reviewing：负责Review部分的Agent名称
+
+您可以在[示例文件](../../../sample_standard_app/app/examples/peer_chat_bot.py)中完整运行本案例。
+