refine(docs): update docs

Author: yaozheng-fang

docs/content/1.introduction/1.overview.md

@@ -9,17 +9,17 @@ seo:
     effortlessly with Docus.
 ---
 
-欢迎使用火山引擎智能体框架 **VeADK（Volcengine Agent Development Kit）**，是由[火山引擎](https://www.volcengine.com/)推出的为 Agent 智能体的应用构建提供开发、部署、观测、评测等全流程云原生解决方案。
+火山引擎智能体框架 **VeADK（Volcengine Agent Development Kit）**，是由[火山引擎](https://www.volcengine.com/)推出的为 Agent 智能体的应用构建提供开发、部署、观测、评测等全流程云原生解决方案。
 
-相较于现有的智能体开发框架，具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
+相较于现有的智能体开发框架，VeADK 具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
 
-## 特性
+## 核心能力
 
 - **生态兼容**：与 Google ADK 完全兼容
-- **快速部署**：本地项目部署到云端的时延在分钟级别，并提供镜像部署、代码部署等多种部署形式
-- **一证通行**：基于火山引擎AK/SK进行企业级统一密钥管理
+- **快速部署**：本地项目分钟级部署云端，提供代码打包、镜像构建等多种部署形式
+- **一证通行**：基于火山引擎AK/SK进行企业级统一身份和密钥管理
 
-## 核心能力
+## 特性
 
 ### 更快速的企业级部署
 

docs/content/1.introduction/2.installation.md

@@ -1,6 +1,6 @@
 ---
 title: 安装
-description: VeADK安装方式
+description: VeADK 安装方式
 navigation:
   icon: i-lucide-download
 ---
@@ -21,19 +21,19 @@ pip install veadk-python==0.2.7
 
 :::
 
-<!-- 如果您使用知识库、长期记忆等进阶功能，请进一步安装 `veadk-python` 中的扩展包：
+如果您使用知识库、长期记忆等进阶功能，请进一步安装 `veadk-python` 中的扩展包：
 
 ```bash [Terminal]
 pip install veadk-python[extensions]
-``` -->
+```
 
 ## 从源码构建
 
 ::steps
 
 ### 下载源码至本地
 
-将VeADK的代码包从Github下载到本地：
+将 VeADK 的代码包从 Github 下载到本地：
 
 ```bash [Terminal]
 git clone https://github.com/volcengine/veadk-python.git

docs/content/1.introduction/3.quickstart.md

@@ -19,19 +19,58 @@ import asyncio
 from veadk import Agent
 
 agent = Agent()
-asyncio.run(agent.run("Hello world!"))
+response = asyncio.run(agent.run("Hello world!"))
+
+print(response)
 ```
 
 ### 执行
 
-您需要通过环境变量方式，来设置能够调用大模型的 API Key 或者其它身份验证信息。
+您需要通过环境变量方式，来设置能够调用大模型的 API Key 或者其它身份验证信息。例如，通过火山引擎方舟大模型平台的API Key：
 
 ```bash [Terminal]
-# 通过 API Key
 MODEL_AGENT_API_KEY=... python agent.py
+```
+
+或者通过火山引擎 AK/SK：
 
-# 通过火山引擎 AK/SK
+```bash [Terminal]
 VOLCENGINE_ACCESS_KEY=... VOLCENGINE_SECRET_KEY=... python agent.py
 ```
 
+::warning
+通过火山引擎 AK/SK 来运行智能体时，将会自动从您的方舟平台获取 API Key，这要求您在方舟平台至少已经创建一个 API Key。[了解如何创建方舟大模型平台API Key](https://www.volcengine.com/docs/82379/1361424)。
+::
+
+### 进阶
+
+您也可以在项目根目录下创建一个 `config.yaml` 来填入相关配置。
+
+::tip
+VeADK 可以自动将您根目录下的 `config.yaml` 文件根据层次使用下划线铺平，转为大写后设置为环境变量，详见[这里](../configurations/system)。
+::
+
+::code-tree{default-value="app/config.yaml"}
+
+```yaml [app/config.yaml]
+volcengine:
+  access_key:
+  secret_key:
+```
+
+```python [app/agent.py]
+import asyncio
+
+from veadk import Agent
+
+agent = Agent()
+response = asyncio.run(agent.run("Hello world!"))
+
+print(response)
+```
+
+::
+
+完整的配置项可以参考[这里](../configurations/envs)。
+
 ::

docs/content/1.introduction/4.troubleshooting.md

@@ -2,7 +2,7 @@
 title: Troubleshooting
 description: 安装、运行以及使用中的各类常见问题汇总
 navigation:
-  icon: i-lucide-wrench
+  icon: i-lucide-file-question-mark
 ---
 
 ## 安装

docs/content/2.configurations/1.system.md

@@ -2,7 +2,7 @@
 title: 配置管理系统
 description: 实现自动身份管理、云上资源设施管理等
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-settings
 ---
 
 VeADK 内置了一套配置管理系统，您能够通过定义一个 `config.yaml` 文件来管理您的各项配置。文件中的配置项将会在运行时被自动加载为对应的环境变量。

docs/content/2.configurations/2.envs.md

@@ -2,7 +2,7 @@
 title: 环境变量
 description: 更安全、更快捷的配置入口
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-settings
 ---
 
 ## 火山引擎生态

docs/content/2.configurations/3.consts.md

@@ -2,7 +2,7 @@
 title: 系统默认值
 description: VeADK 内置常量值
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-settings
 ---
 
 VeADK 中的内置常量值如下：

docs/content/3.agent/1.agent.md

@@ -1,19 +1,33 @@
 ---
-title: LLM Agent
-description: 基于 LLM 的自主决策 Agent
+title: Agent
+description: VeADK 中提供了多种类型的智能体来承载不同的任务需求
 navigation:
-  icon: i-lucide-heading-1
+  icon: i-lucide-lightbulb
 ---
 
-## 定义方法
+VeADK 中提供了多种类型的智能体来满足应用场景需要，提供可控要求下的自主决策。其中：
+
+- **自主决策 Agent：** 可以根据不同场景，由 LLM 自主决定调用哪些子智能体或工具
+- **工作流 Agent：** 根据不同智能体类别，采用硬编码模式来提供确定性的子智能体执行顺序
+
+## 自主决策 Agent
+
+### 使用示例
 
 ```python [agent.py]
+import asyncio
+
 from veadk import Agent
+from veadk.tools.demo_tools import get_city_weather
+
+agent = Agent(tools=[get_city_weather])
 
-agent = Agent()
+response = asyncio.run(agent.run("北京天气怎么样？"))
+
+print(response) # 北京天气晴朗，气温25°C。
 ```
 
-## 选项
+### 选项
 
 ::field-group
   ::field{name="name" type="string"}
@@ -48,19 +62,162 @@ agent = Agent()
   模型请求的额外配置
   ::
 
-  ::field{name="tools" type="list[ToolUnion]"}
+  ::field{name="tools" type="list[ToolUnion] | None"}
   提供给智能体的工具列表
   ::
 
-  ::field{name="sub_agents" type="list[BaseAgent]"}
+  ::field{name="sub_agents" type="list[BaseAgent] | None"}
   提供给该智能体的子智能体列表
   ::
 
-  ::field{name="knowledgebase" type="KnowledgeBase | null"}
+  ::field{name="knowledgebase" type="KnowledgeBase | None"}
   提供给智能体的知识库
   ::
 
-  ::field{name="long_term_memory" type="LongTermMemory | null"}
+  ::field{name="short_term_memory" type="ShortTermMemory | None"}
+  智能体的单会话上下文
+  ::
+
+  ::field{name="long_term_memory" type="LongTermMemory | None"}
   智能体的跨会话长期记忆（同一用户范围内）
   ::
 ::
+
+::note
+更多兼容字段请参考 [Google ADK LLM Agent 定义](https://github.com/google/adk-python/blob/main/src/google/adk/agents/llm_agent.py)。
+::
+
+## 工作流 Agent
+
+### 定义方法
+
+下面提供了不同类型工作流智能体的定义方法：
+
+#### 顺序类 `SequentialAgent`
+
+#### 循环类 `LoopAgent`
+
+```python [loop_agent.py]
+
+```
+
+#### 并行类 `ParallelAgent`
+
+```python [parallel_agent.py]
+
+```
+
+### 选项
+
+工作流 Agent 采用统一的参数：
+
+::field-group
+  ::field{name="name" type="string"}
+  智能体的名称
+  ::
+
+  ::field{name="description" type="string"}
+  默认为 `DEFAULT_DESCRIPTION` - 智能体的描述，在 A2A 场景下会有帮助
+  ::
+
+  ::field{name="instruction" type="string"}
+  默认为 `DEFAULT_INSTRUCTION` - 智能体的指令，例如函数调用的原则
+  ::
+
+  ::field{name="sub_agents" type="list[BaseAgent]"}
+  默认为 `[]` - 提供给该智能体的子智能体列表
+  ::
+
+  ::field{name="tracers" type="list[BaseTracer]"}
+  默认为 `[]` - 提供给该智能体的 tracer
+  ::
+::
+
+::note
+更多兼容字段请参考 [Google ADK Agents 定义](https://github.com/google/adk-python/blob/main/src/google/adk/agents/)。
+::
+
+## 多智能体协作
+
+使用 VeADK 可以构建多 Agent 协作， 主 Agent 通过 `sub_agents` 机制协调多个子 Agent 完成复杂任务。
+
+### 自主决策 Agent
+
+利用能够自主决策的 Agent 来定义一个生活提醒智能体，分别定义了三个智能体：
+
+- `weather_reporter`：负责通过 `get_city_weather` 工具来获取指定城市的天气信息
+- `suggester`：根据天气情况给出穿衣建议
+- `planner`：作为“调度员”，先调用 `weather_reporter` 获取天气，再调用 `suggester` 获取建议，最后将结果整合返回给用户。
+
+```python [agent.py]
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.tools.demo_tools import get_city_weather
+
+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.",
+)
+
+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(planner_agent)
+response = asyncio.run(runner.run("北京穿衣建议"))
+
+print(response)
+# Based on the weather in Beijing today - Sunny with a temperature of 25°C, here are some clothing suggestions for you:
+
+# It's a comfortable and warm day. You can choose light and breathable clothes. For example, a short - sleeved T - shirt or a thin shirt paired with casual pants or a skirt would be great. Since it's sunny, don't forget to wear a hat and sunglasses to protect yourself from the sun. Also, you can carry a light jacket in case the temperature drops in the evening, but it might not be necessary. Enjoy your day in Beijing!
+```
+
+### `SequentialAgent`
+
+```python [sequential_agent.py]
+import asyncio
+
+from veadk import Agent, Runner
+from veadk.agents.sequential_agent import SequentialAgent
+
+greeting_agent = Agent(
+    name="greeting_agent",
+    description="A friendly agent that greets the user.",
+    instruction="Greet the user warmly.",
+)
+
+goodbye_agent = Agent(
+    name="goodbye_agent",
+    description="A polite agent that says goodbye to the user.",
+    instruction="Say goodbye to the user politely.",
+)
+
+root_agent = SequentialAgent(sub_agents=[greeting_agent, goodbye_agent])
+
+runner = Runner(root_agent)
+response = asyncio.run(runner.run("你好"))
+
+print(response)
+```
+
+### `LoopAgent`
+
+```python [loop_agent.py]
+
+```
+
+### `ParallelAgent`
+
+```python [parallel_agent.py]
+
+```