docs: supplement and improve the docs (#40)

Co-authored-by: wuqingfu.528 <[email protected]>

Author: BhAem

docs/docs/.vuepress/config.js

@@ -13,7 +13,7 @@ export default defineUserConfig({
 
     navbar: ['/', '/introduction'],
 
-    sidebar: ['introduction', 'installation', 'get-started', 'agent', 'memory', 'knowledgebase', 'tracing', 'evaluation', 'deploy', 'cli', 'veadk-studio']
+    sidebar: ['introduction', 'installation', 'get-started', 'agent', 'memory', 'tool', 'knowledgebase', 'tracing', 'evaluation', 'deploy', 'cli', 'veadk-studio']
   }),
 
   bundler: viteBundler(),

docs/docs/.vuepress/public/images/memory-optimization.png

@@ -1,23 +1,59 @@
 # 智能体
 
+智能体 Agent 是一个具备完整功能的执行单元，依托内置的大模型推理能力，其不仅可以独立完成各类任务、与用户进行智能交互、调用外部工具资源，还能实现与其他 Agent 之间的协同配合。
+
 ## 属性
 
-Agent中主要包括如下属性：
+Agent 中主要包括如下属性：
 
 | 属性 | 类型 | 说明 |
 | --- | --- | --- |
-| name | str | Agent的名称，即标识符 |
-| description | str | Agent的描述，后续会被构建为系统提示词的一部分；也被用来在A2A协议中进行Agent挑选 |
-| instruction | str | Agent中内置模型的系统提示词 |
-| tools | list | Function call中的工具列表，既可以是本地工具，也可以是MCP工具 |
-| sub_agents | list | 子Agent列表，用于多Agent之间交互 |
-| long_term_memory | Vector database | 长期记忆，后端通常为一个向量数据库（Vector database），能够检索 |
-| knowledgebase | Vector database | 知识库，后端通常为一个向量数据库（Vector database），能够检索 |
-| tracers | list | 追踪器列表，能够定义不同的追踪方式，并在Agent执行完毕后对整体Tracing信息保存至本地 |
+| name | str | Agent 的名称，即标识符 |
+| description | str | Agent 的描述，后续会被构建为系统提示词的一部分，也被用来在A2A协议中进行 Agent 挑选 |
+| instruction | str | Agent 中内置模型的系统提示词 |
+| model_name | str | Agent 中内置模型的名称，默认从环境变量中获取 |
+| model_provider | str | Agent 中内置模型的提供商，默认从环境变量中获取 |
+| model_api_base | str | Agent 中内置模型的 API Base，默认从环境变量中获取 |
+| model_api_key | str | Agent 中内置模型的 API Key，默认从环境变量中获取 |
+| tools | list | Function call 中的工具列表，既可以是本地工具，也可以是 MCP 工具 |
+| sub_agents | list | 子 Agent 列表，用于多 Agent 之间交互 |
+| knowledgebase | KnowledgeBase | 知识库，后端支持本地内存（local）和数据库（opensearch、viking、redis、mysql），通常设置为一个能够检索的向量数据库 |
+| long_term_memory | LongTermMemory | 长期记忆，后端支持本地内存（local）和数据库（opensearch、viking、redis、mysql），通常设置为一个能够检索的向量数据库 |
+| tracers | list | 追踪器列表，能够定义不同的追踪方式，并在 Agent 执行完毕后将整体 Tracing 信息保存至本地 |
+| serve_url | str | Agent 服务主机的 URL，将显示在 Agent Card 中 |
+
+## 运行
+
+在生产环境中，我们推荐您使用 VeADK 的`Runner`执行器来进行多租户服务与 Agent 运行，在多租场景下，`Runner`通过三个属性来确定资源空间：
+
+- `app_name`：应用名称
+- `user_id`：用户ID
+- `session_id`：某个用户某次会话的ID
+
+```python
+from veadk import Agent, Runner
+from veadk.memory.short_term_memory import ShortTermMemory
+
+# Define Runner config
+APP_NAME = "..."
+USER_ID = "..."
+SESSION_ID = "..."
+
+agent = Agent()
+
+runner = Runner(
+    agent=agent,
+    short_term_memory=ShortTermMemory(),
+    app_name=APP_NAME,
+    user_id=USER_ID
+)
+
+response = await runner.run(messages="...", session_id=SESSION_ID)
+```
 
-## A2A智能体
+## A2A 智能体
 
-当你的智能体部署到云上后，可以在本地被初始化为一个Remote Agent，也就是能够通过A2A协议来访问的智能体，初始化方法如下：
+当智能体部署到云上后，可以在本地被初始化为一个 Remote Agent，也就是能够通过 A2A 协议来访问的智能体，初始化方法如下：
 
 ```python
 remote_agent = RemoteVeAgent(
@@ -29,33 +65,50 @@ short_term_memory = ShortTermMemory()
 runner = Runner(
     agent=remote_agent,
     short_term_memory=short_term_memory
-    )
+)
 
 res = await runner.run(
     messages="...",
     session_id="sample_session"
-    )
+)
 ```
 
-## 运行
+## 多智能体
+
+使用 VeADK 可以构建多 Agent 协作， 主 Agent 通过 `sub_agents` 机制协调多个子 Agent 完成复杂任务。以下代码示例分别定义了三个 Agent：
+
+- weather_reporter：负责获取指定城市的天气信息（调用了 `get_city_weather` 工具）。
+- suggester：根据天气情况给出穿衣建议。
+- planner_agent：作为“调度员”，先调用 `weather_reporter` 获取天气，再调用 `suggester` 获取建议，最后将结果整合返回给用户。
 
-在生产环境中，我们推荐您使用`Runner`来进行多租户服务：
+该多智能体协作能更好的满足用户的需求。
 
 ```python
 from veadk import Agent, Runner
 from veadk.memory.short_term_memory import ShortTermMemory
+from veadk.tools.demo_tools import get_city_weather
 
-# Define runner config
-APP_NAME = ""
-USER_ID = ""
-SESSION_ID = ""
+session_id = "..."
+prompt = "..."
 
-agent = Agent()
+# define three agents, one for planner, two for write poem and polish
+weather_reporter = Agent(
+    name="weather_reporter",
+    description="A weather reporter agent to report the weather.",
+    tools=[get_city_weather],
+)
+suggester = Agent(
+    name="suggester",
+    description="A suggester agent that can give some clothing suggestions according to a city's weather.",
+)
 
-runner = Runner(
-    agent=agent,
-    short_term_memory=ShortTermMemory()
-    )
+planner_agent = Agent(
+    name="planner",
+    description="A planner that can generate a suggestion according to a city's weather.",
+    instruction="Invoke weather reporter agent first to get the weather, then invoke suggester agent to get the suggestion. Return the final response to user.",
+    sub_agents=[weather_reporter, suggester],
+)
 
+runner = Runner(agent=planner_agent, short_term_memory=ShortTermMemory())
 response = await runner.run(messages=prompt, session_id=session_id)
-```
+```

docs/docs/.vuepress/public/images/tracing-apmplus.png

@@ -1,72 +1,157 @@
 # 评测
 
-VeADK构建一套完整的自动化Evaluation流程，主要能力包括：
+VeADK 构建一套完整的自动化评测（Evaluation）流程，其主要功能包括：
 
-- 运行时数据采集：通过collect_runtime_data开启
-- 测试集文件生成：开启后自动dump到本地
-- 评测：通过不同的evaluator或adk eval命令进行测试
-- 反馈优化：自动根据评测结果（score reason等属性）优化prompts
+- 运行时数据采集：自动捕获 Agent 的运行时数据
+- 测试集文件生成：Agent 运行后自动将运行时数据作为测试数据集（Eval Set）导出到本地
+- 评测：通过多种评测器（Evaluator）进行评测
+- 反馈优化：根据评测结果（如评测得分，原因分析等）自动优化 prompts
 
 ## 运行时数据采集
 
+VeADK 可以通过两种方式采集 Agent 的运行时数据。
+
+对于 `agent.run()` 方法，在调用时设置 `collect_runtime_data=True` 即可开启数据采集。运行结束后，运行时数据构成的评测集文件将保存在 `agent._dump_path` 指定的路径。
+
+```python
+await agent.run(
+    prompt,
+    collect_runtime_data=True,
+    eval_set_id=f"eval_demo_set_{get_current_time()}",
+)
+# get expect output
+dump_path = agent._dump_path
+assert dump_path != "", "Dump eval set file failed! Please check runtime logs."
+```
+
+对于 `Runner` 执行器，在 Agent 运行结束后，通过调用 `runner.save_eval_set()` 将运行时数据构成的评测集文件保存在默认路径。
+
 ```python
-from veadk.evaluation import EvalSetRecorder
+runner = Runner(
+    agent=agent,
+    short_term_memory=ShortTermMemory(),
+)
 
-# 在希望进行数据dump处初始化一个EvalSetRecorder
-eval_set_recorder = EvalSetRecorder(session_service, eval_set_id)
+await runner.run(messages=prompts, session_id=session_id)
 
-# dump数据，为Json格式
-dump_path = await eval_set_recorder.dump(app_name, user_id, session_id)
+dump_path = await runner.save_eval_set(session_id=session_id)
+assert dump_path != "", "Dump eval set file failed! Please check runtime logs."
 ```
 
 ## 评测集文件
 
-评测集文件格式兼容Google Evaluation，详见[评测集文件格式](https://google.github.io/adk-docs/evaluate/#how-evaluation-works-with-the-adk)。
+评测集文件格式兼容 Google Evaluation 标准，详见[评测集文件格式](https://google.github.io/adk-docs/evaluate/#how-evaluation-works-with-the-adk)。评测集本地保存过程中，会考虑所有会话。
 
-评测集本地保存过程中，均考虑当前会话。下面是一些概念对齐：
+文件结构说明：
 
-- `test_case`：所有对话轮次
-- `invocation`：一轮对话
+- `eval_cases`：所有对话轮次
+- `conversation`：一轮对话
+  - `user_content`：用户的输入
+  - `final_response`：Agent 的最后输出
+  - `intermediate_data`：中间数据
+    - `tool_uses`：Agent 使用的工具
+    - `intermediate_responses`：Agent 的中间会话
 
-## 评测器
+## 评测
 
-当前VeADK支持Deepeval评测器，通过如下方式定义：
+VeADK 目前支持 [DeepEval](https://deepeval.com/) 评测器和 [ADKEval](https://google.github.io/adk-docs/evaluate/)，通过如下方式定义评测器：
 
 ```python
 from veadk.evaluation.deepeval_evaluator import DeepevalEvaluator
+from veadk.evaluation.adk_evaluator.adk_evaluator import ADKEvaluator
 
 # 当然，你还可以传入`judge_model`等相关信息
 evaluator = DeepevalEvaluator()
-```
 
-## 评测方法
+# Alternatively:
+# evaluator = ADKEvaluator()
+```
 
 启动标准的评测接口：
 
 ```python
 await evaluator.eval(eval_set_file_path=dump_path, metrics=metrics)
 ```
 
-其中，输入：
+参数说明：
 
 - `eval_set_file_path`：评测集文件路径
-- `metrics`：评测指标
-
-不同的评测指标在不同测试框架中可能不同。
+- `metrics`：评测指标，不同的评测指标在不同测试框架中可能不同。
 
 ## 数据上报
 
-评测结果可以自动上报至火山引擎的VMP平台，只需要在定义评估器的时候传入Prometheus pushgateway的相关参数：
+评测结果可以自动上报至火山引擎的 [VMP](https://console.volcengine.com/prometheus) 平台，只需要在定义评估器的时候传入 Prometheus pushgateway 等相关参数即可，可在 `config.yaml` 中进行配置并从环境变量中自动读取：
 
 ```python
 from veadk.evaluation.utils.prometheus import PrometheusPushgatewayConfig
 
-# 可以自动从环境变量中读取相关配置
+# Load Prometheus configuration (can be read from environment variables)
 prometheus_config = PrometheusPushgatewayConfig()
 
-# 传入到评估器中
+# Pass config into evaluator
 evaluator = DeepevalEvaluator(
     ...,
     prometheus_config=prometheus_config,
 )
+```
+
+## 完整示例
+
+以下是使用 DeepEval 评测器的完整例子。其中定义了 [GEval](https://deepeval.com/docs/metrics-llm-evals) 指标和 [ToolCorrectnessMetric](https://deepeval.com/docs/metrics-tool-correctness) 指标，分别用于整体输出质量评估和工具调用正确率评估，并将评测结果上报至火山引擎的 VMP 平台：
+
+```python
+import asyncio
+import os
+from builtin_tools.agent import agent
+
+from deepeval.metrics import GEval, ToolCorrectnessMetric
+from deepeval.test_case import LLMTestCaseParams
+from veadk.config import getenv
+from veadk.evaluation.deepeval_evaluator import DeepevalEvaluator
+from veadk.evaluation.utils.prometheus import PrometheusPushgatewayConfig
+from veadk.prompts.prompt_evaluator import eval_principle_prompt
+
+prometheus_config = PrometheusPushgatewayConfig()
+
+# 1. Rollout, and generate eval set file
+# await agent.run(
+#     prompt,
+#     collect_runtime_data=True,
+#     eval_set_id=f"eval_demo_set_{get_current_time()}",
+# )
+# # get expect output
+# dump_path = agent._dump_path
+# assert dump_path != "", "Dump eval set file failed! Please check runtime logs."
+
+# 2. Evaluate in terms of eval set file
+evaluator = DeepevalEvaluator(
+    agent=agent,
+    judge_model_name=getenv("MODEL_JUDGE_NAME"),
+    judge_model_api_base=getenv("MODEL_JUDGE_API_BASE"),
+    judge_model_api_key=getenv("MODEL_JUDGE_API_KEY"),
+    prometheus_config=prometheus_config,
+)
+
+# 3. Define evaluation metrics
+metrics = [
+    GEval(
+        threshold=0.8,
+        name="Base Evaluation",
+        criteria=eval_principle_prompt,
+        evaluation_params=[
+            LLMTestCaseParams.INPUT,
+            LLMTestCaseParams.ACTUAL_OUTPUT,
+            LLMTestCaseParams.EXPECTED_OUTPUT,
+        ],
+    ),
+    ToolCorrectnessMetric(
+        threshold=0.5
+    ), 
+]
+
+# 4. Run evaluation
+eval_set_file_path = os.path.join(
+    os.path.dirname(__file__), "builtin_tools", "evalsetf0aef1.evalset.json"
+)
+await evaluator.eval(eval_set_file_path=eval_set_file_path, metrics=metrics)
 ```