doc:update datasource docs

docs/data_analysis_planning_agent.md

@@ -0,0 +1,302 @@
+# Data Analysis Planning Agent
+
+基于`react_agent.py`开发的具有自主规划能力的数据分析智能体，能够理解数据分析需求、制定分析计划并系统性地执行。
+
+## 核心特性
+
+### 🎯 自主规划能力
+- **需求理解**: 深度理解业务问题和分析目标
+- **计划制定**: 创建系统性的数据分析步骤计划
+- **动态调整**: 根据分析结果动态调整后续步骤
+
+### 📊 全流程分析
+- **数据源检查**: 自动识别和检查可用数据源
+- **数据加载**: 智能加载和预处理数据
+- **探索性分析**: 进行全面的数据探索
+- **统计分析**: 执行统计检验和深度分析
+- **可视化**: 生成图表和可视化结果
+- **洞察提取**: 提供业务洞察和建议
+
+### 🤖 智能决策
+- **步骤优化**: 根据数据特点优化分析步骤
+- **工具选择**: 智能选择最适合的分析工具
+- **结果验证**: 验证分析结果的可靠性
+
+## 架构设计
+
+### 继承结构
+```
+DataAnalysisPlanningAgent
+├── 继承自 ConversableAgent
+├── 扩展 ReActAgent 的规划能力
+└── 集成数据分析专用工具
+```
+
+### 核心组件
+
+#### 1. 规划状态管理
+```python
+class DataAnalysisPlanningAgent(ConversableAgent):
+    analysis_plan: Optional[List[Dict[str, Any]]]  # 分析计划
+    current_step: int = Field(default=0)           # 当前步骤
+    planning_complete: bool = Field(default=False) # 规划完成状态
+```
+
+#### 2. 专用工具集
+- `create_analysis_plan`: 创建分析计划
+- `examine_data_sources`: 检查数据源
+- `load_data`: 加载数据
+- `explore_data`: 探索性分析
+- `statistical_analysis`: 统计分析
+- `create_visualization`: 创建可视化
+- `generate_insights`: 生成洞察
+
+#### 3. 智能提示模板
+```python
+_DATA_AGENT_SYSTEM_TEMPLATE = """
+You are an expert data analyst with strong planning and execution capabilities.
+
+1. Planning Phase: 理解目标、识别数据、创建计划
+2. Execution Phase: 加载数据、执行分析、生成结果  
+3. Communication Phase: 展示发现、提供洞察、建议后续
+"""
+```
+
+## 使用方法
+
+### 基础使用
+
+```python
+from dbgpt.agent.expand.data_agent import DataAnalysisPlanningAgent
+from dbgpt.agent.resource import ToolPack, ResourcePack
+
+# 1. 创建工具
+tools = [DataSourceTool(), LoadDataTool(), ExploreDataTool()]
+tool_pack = ToolPack(tools=tools)
+
+# 2. 创建资源包
+resource_pack = ResourcePack()
+resource_pack._resources["tools"] = tool_pack
+
+# 3. 创建Agent
+agent = DataAnalysisPlanningAgent(resource=resource_pack)
+
+# 4. 发送分析请求
+message = AgentMessage(content="分析销售数据趋势，提供业务洞察")
+response = await agent.act(message, sender=None)
+```
+
+### 高级配置
+
+```python
+# 自定义规划参数
+agent = DataAnalysisPlanningAgent(
+    max_retry_count=25,  # 增加重试次数
+    resource=resource_pack,
+    llm_client=your_llm_client
+)
+
+# 设置分析目标
+agent.profile.goal = "专注于电商数据分析，提供精准的业务洞察"
+```
+
+## 工作流程
+
+### 1. 需求理解阶段
+```
+用户输入 → 理解业务问题 → 识别分析目标 → 确定数据需求
+```
+
+### 2. 规划制定阶段
+```
+数据需求 → 检查数据源 → 制定分析计划 → 估算时间和资源
+```
+
+### 3. 执行分析阶段
+```
+执行计划 → 数据加载 → 探索分析 → 深度分析 → 结果验证
+```
+
+### 4. 结果呈现阶段
+```
+分析结果 → 生成洞察 → 创建可视化 → 提供建议 → 完成任务
+```
+
+## 示例场景
+
+### 场景1: 销售趋势分析
+```python
+question = "分析我们的销售数据，识别趋势并提供业务规划洞察"
+
+# Agent会自动执行：
+# 1. 创建销售趋势分析计划
+# 2. 检查可用的销售数据源
+# 3. 加载销售数据
+# 4. 进行趋势分析
+# 5. 生成可视化图表
+# 6. 提供业务洞察和建议
+```
+
+### 场景2: 客户细分分析
+```python
+question = "进行客户细分分析，识别不同客户群体特征"
+
+# Agent会自动执行：
+# 1. 制定客户细分分析计划
+# 2. 检查客户数据
+# 3. 执行细分算法
+# 4. 分析各群体特征
+# 5. 提供营销建议
+```
+
+## 扩展开发
+
+### 添加自定义工具
+
+```python
+class CustomAnalysisTool(BaseTool):
+    @property
+    def name(self) -> str:
+        return "custom_analysis"
+    
+    @property
+    def description(self) -> str:
+        return "执行自定义分析逻辑"
+    
+    async def async_execute(self, **kwargs):
+        # 实现自定义分析逻辑
+        return {"result": "自定义分析结果"}
+
+# 添加到Agent
+agent.resource._resources["custom_analysis"] = CustomAnalysisTool()
+```
+
+### 自定义规划逻辑
+
+```python
+class CustomDataAnalysisAgent(DataAnalysisPlanningAgent):
+    async def create_custom_plan(self, objective: str):
+        # 实现自定义规划逻辑
+        custom_plan = [
+            {"step": 1, "action": "custom_preprocessing"},
+            {"step": 2, "action": "custom_analysis"},
+        ]
+        self.analysis_plan = custom_plan
+        return custom_plan
+```
+
+## 最佳实践
+
+### 1. 数据准备
+- 确保数据源可访问
+- 提供数据文档和元数据
+- 预处理常见数据质量问题
+
+### 2. 目标设定
+- 明确分析目标和业务问题
+- 提供背景信息和约束条件
+- 设定期望的输出格式
+
+### 3. 工具配置
+- 根据分析需求配置合适工具
+- 确保工具参数正确设置
+- 提供工具使用文档
+
+### 4. 结果验证
+- 验证分析结果的合理性
+- 检查数据质量影响
+- 确认业务洞察的准确性
+
+## 故障排除
+
+### 常见问题
+
+#### 1. 规划失败
+```
+问题: Agent无法创建有效的分析计划
+解决: 检查数据源可用性，明确分析目标
+```
+
+#### 2. 工具执行错误
+```
+问题: 数据分析工具执行失败
+解决: 检查工具参数，验证数据格式
+```
+
+#### 3. 结果质量差
+```
+问题: 分析结果不够深入或准确
+解决: 提供更多背景信息，调整分析策略
+```
+
+### 调试方法
+
+```python
+# 启用详细日志
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# 检查Agent状态
+print(f"Planning complete: {agent.planning_complete}")
+print(f"Current step: {agent.current_step}")
+print(f"Analysis plan: {agent.analysis_plan}")
+```
+
+## 性能优化
+
+### 1. 缓存策略
+- 缓存数据加载结果
+- 缓存分析计算结果
+- 缓存常用查询结果
+
+### 2. 并行处理
+- 并行执行独立分析任务
+- 异步处理数据加载
+- 批量处理相似请求
+
+### 3. 资源管理
+- 合理管理内存使用
+- 优化计算资源分配
+- 控制并发任务数量
+
+## 未来规划
+
+### 短期目标
+- [ ] 添加更多预定义分析模板
+- [ ] 优化规划算法
+- [ ] 增强错误处理能力
+
+### 中期目标
+- [ ] 支持多数据源联合分析
+- [ ] 集成机器学习模型
+- [ ] 添加实时分析能力
+
+### 长期目标
+- [ ] 支持自然语言交互
+- [ ] 自动化报告生成
+- [ ] 智能推荐系统
+
+## 贡献指南
+
+欢迎提交Issue和Pull Request来改进这个项目！
+
+### 开发环境设置
+```bash
+# 安装依赖
+pip install -r requirements.txt
+
+# 运行测试
+pytest tests/
+
+# 代码格式化
+black src/
+```
+
+### 提交规范
+- 使用清晰的提交信息
+- 添加适当的测试用例
+- 更新相关文档
+
+## 许可证
+
+MIT License - 详见LICENSE文件

docs/docs/getting-started/concepts/architecture.md

@@ -0,0 +1,139 @@
+---
+sidebar_position: 0
+title: Architecture
+summary: "DB-GPT repo layout and ReAct-centered runtime architecture"
+read_when:
+  - You want the shortest mental model for how DB-GPT is organized
+  - You need to understand how UI, API, agents, skills, tools, and data resources connect
+---
+
+# Architecture
+
+DB-GPT is organized as a Python monorepo with a ReAct-centered agent runtime.
+The Web UI sends requests to the application layer, the ReAct Agent executes in an
+agent runtime loop, and the agent uses tools, skills, databases, and knowledge
+resources to produce analysis results back to the UI.
+
+## Repository layout
+
+```text
+DB-GPT/
+├── packages/
+│   ├── dbgpt-core/        # Core agent, memory, planning, RAG, model abstractions
+│   ├── dbgpt-app/         # Application server, API routes, scenes, UI asset hosting
+│   ├── dbgpt-serve/       # Service layer: knowledge, flow, agent resources, app services
+│   ├── dbgpt-ext/         # Extensions: datasources, storage backends, RAG connectors
+│   ├── dbgpt-client/      # Python client SDK
+│   ├── dbgpt-sandbox/     # Sandbox execution runtime for safe code/tool execution
+│   └── dbgpt-accelerator/ # Acceleration packages
+├── web/                   # Next.js Web UI
+├── skills/                # Built-in skills and reusable workflows
+├── configs/               # TOML configuration files
+└── docs/                  # Docusaurus documentation
+```
+
+## Package roles
+
+| Package | Role |
+|---|---|
+| `dbgpt-core` | Core agent framework, ReAct parser/action flow, memory, planning, RAG, model interfaces |
+| `dbgpt-app` | FastAPI application server, chat APIs, runtime orchestration, static UI hosting |
+| `dbgpt-serve` | Resource services for knowledge, datasource, flow, app, and agent support |
+| `dbgpt-ext` | External connectors such as database/storage/RAG integrations |
+| `dbgpt-client` | Client SDK for DB-GPT APIs |
+| `dbgpt-sandbox` | Isolated execution runtimes for code and tool execution |
+| `skills/` | Packaged domain workflows, scripts, templates, and references |
+
+## High-level architecture
+
+```mermaid
+flowchart TB
+    User["User"] --> UI["Web UI / Chat Apps"]
+    UI --> API["dbgpt-app API"]
+
+    subgraph Runtime["agent_runtime"]
+        Agent["ReAct Agent"]
+        Loop["Thought -> Action -> Observation Loop"]
+        Action["Tool / Skill / Resource Selection"]
+        Agent --> Loop --> Action --> Agent
+    end
+
+    API --> Runtime
+
+    subgraph Resources["External resources"]
+        DB["Structured databases"]
+        KB["Unstructured data / knowledge space"]
+        Skill["Skills"]
+        Tool["Built-in tools"]
+        Sandbox["Sandbox runtime"]
+    end
+
+    Action --> DB
+    Action --> KB
+    Action --> Skill
+    Action --> Tool
+    Action --> Sandbox
+
+    Runtime --> Result["Analysis result / report / chart"]
+    Result --> UI
+```
+
+## How it works
+
+1. The user interacts with the Web UI or another client.
+2. `dbgpt-app` receives the request and routes it to the agent chat API.
+3. The request enters the `agent_runtime` execution loop.
+4. The ReAct Agent reasons step by step and chooses the next action.
+5. The agent loads and uses external resources as needed:
+   - structured databases for SQL analysis
+   - unstructured knowledge spaces for retrieval
+   - skills for reusable workflows
+   - built-in tools for task execution
+   - sandbox runtimes for safe code execution
+6. The agent combines observations and produces the final analysis output.
+7. The result is streamed back to the UI for display.
+
+## Agent runtime model
+
+The runtime is the conceptual execution layer that drives the ReAct loop.
+In the codebase, this is implemented through the agent builder, resource manager,
+ReAct parser/action flow, and the API streaming handlers that connect to the UI.
+
+Key implementation anchors:
+
+- `packages/dbgpt-core/src/dbgpt/agent/expand/react_agent.py`
+- `packages/dbgpt-core/src/dbgpt/agent/util/react_parser.py`
+- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
+- `web/hooks/use-react-agent-chat.ts`
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
+
+## Resources used by the agent
+
+### Structured data
+
+Databases and queryable tabular sources are used for SQL-style analysis, schema
+linking, and report generation.
+
+### Unstructured data
+
+Knowledge spaces and document collections provide retrieval support for
+unstructured content.
+
+### Skills
+
+Built-in skills package repeatable workflows into reusable task units. The agent
+can load and execute them during a session.
+
+### Built-in tools
+
+Tools include SQL execution, shell/code execution, HTML rendering, search, and
+other task-specific operations registered through the resource manager.
+
+## Result delivery
+
+The output path is designed to be user-facing:
+
+`ReAct Agent` → `agent_runtime` → `streamed result` → `Web UI`
+
+This makes the architecture suitable for interactive data analysis, report
+generation, and tool-assisted reasoning.

docs/docs/installation/integrations/doris_install.md

@@ -0,0 +1,40 @@
+# Apache Doris
+
+Apache Doris is a real-time analytical data warehouse supported by DB-GPT through
+the native connector in `dbgpt_ext.datasource.rdbms.conn_doris`.
+
+### Install Dependencies
+
+Doris uses the MySQL-compatible driver path.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "datasource_mysql" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare Apache Doris
+
+Prepare a Doris instance and start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### Apache Doris Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- driver (`mysql+pymysql`)
+
+The Doris connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_doris.py`

docs/docs/installation/integrations/gaussdb_install.md

@@ -0,0 +1,41 @@
+# GaussDB
+
+GaussDB is an enterprise-grade relational database supported by DB-GPT through the
+native connector in `dbgpt_ext.datasource.rdbms.conn_gaussdb`.
+
+### Install Dependencies
+
+GaussDB uses the PostgreSQL-compatible driver path.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "datasource_postgres" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare GaussDB
+
+Prepare a GaussDB instance and start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### GaussDB Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- schema
+- driver (`postgresql+psycopg2`)
+
+The GaussDB connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_gaussdb.py`

docs/docs/installation/integrations/mysql_install.md

@@ -0,0 +1,46 @@
+# MySQL
+
+MySQL is a widely used open-source relational database system. DB-GPT includes a
+native MySQL datasource connector in `dbgpt_ext.datasource.rdbms.conn_mysql`.
+
+### Install Dependencies
+
+First, install the MySQL datasource dependency set.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "datasource_mysql" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare MySQL
+
+Prepare a MySQL service and database, then start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+Optionally:
+
+```bash
+uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml
+```
+
+### MySQL Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- driver (`mysql+pymysql`)
+
+The MySQL connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_mysql.py`

docs/docs/installation/integrations/oceanbase_install.md

@@ -0,0 +1,40 @@
+# OceanBase
+
+OceanBase is a distributed SQL database supported by DB-GPT through the native
+connector in `dbgpt_ext.datasource.rdbms.conn_oceanbase`.
+
+### Install Dependencies
+
+OceanBase support is built on the OceanBase-compatible MySQL driver path already
+used by the connector.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare OceanBase
+
+Prepare an OceanBase instance and start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### OceanBase Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- driver (`mysql+ob`)
+
+The OceanBase connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_oceanbase.py`

docs/docs/installation/integrations/sqlite_install.md

@@ -0,0 +1,37 @@
+# SQLite
+
+SQLite is a lightweight embedded relational database. DB-GPT includes a native
+SQLite connector in `dbgpt_ext.datasource.rdbms.conn_sqlite`.
+
+### Install Dependencies
+
+SQLite support is available in the base installation and does not require an
+additional datasource extra.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare SQLite
+
+Prepare a SQLite database file path such as `./data/demo.db`, then start the server:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### SQLite Configuration
+
+Use the datasource UI or configuration fields for:
+
+- path
+- check_same_thread
+- driver (`sqlite`)
+
+The SQLite connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_sqlite.py`

docs/docs/installation/integrations/starrocks_install.md

@@ -0,0 +1,40 @@
+# StarRocks
+
+StarRocks is a high-performance analytical database supported by DB-GPT through
+the native connector in `dbgpt_ext.datasource.rdbms.conn_starrocks`.
+
+### Install Dependencies
+
+Install the base dependency set and the StarRocks SQLAlchemy driver required by
+your environment.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare StarRocks
+
+Prepare a StarRocks instance and start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### StarRocks Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- driver (`starrocks`)
+
+The StarRocks connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_starrocks.py`

docs/docs/installation/integrations/vertica_install.md

@@ -0,0 +1,40 @@
+# Vertica
+
+Vertica is an analytical SQL data warehouse supported by DB-GPT through the native
+connector in `dbgpt_ext.datasource.rdbms.conn_vertica`.
+
+### Install Dependencies
+
+Install the Vertica datasource extra.
+
+```bash
+uv sync --all-packages \
+--extra "base" \
+--extra "datasource_vertica" \
+--extra "rag" \
+--extra "storage_chromadb" \
+--extra "dbgpts"
+```
+
+### Prepare Vertica
+
+Prepare a Vertica instance and start the DB-GPT webserver:
+
+```bash
+uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
+```
+
+### Vertica Configuration
+
+Use the datasource UI or configuration fields for:
+
+- host
+- port
+- user
+- password
+- database
+- driver (`vertica+vertica_python`)
+
+The Vertica connector is implemented in:
+
+- `packages/dbgpt-ext/src/dbgpt_ext/datasource/rdbms/conn_vertica.py`

docs/docs/overview.mdx

@@ -8,11 +8,9 @@ import CommandCopyCard from "@site/src/components/mdx/CommandCopyCard";
 # DB-GPT
 
 <p align="center">
-  <img src={'/img/dbgpt.png'} width="560px" />
+  <img src={'/img/dbgpt_vision.png'} width="860px" />
 </p>
 
-> *"In the Data 3.0 era, based on models and databases, enterprises and developers can build their own bespoke applications with less code."*
-
 <p align="center">
   <strong>An open-source AI data assistant that connects to your data, writes SQL and code, runs skills in sandboxed environments, and turns analysis into reports, insights, and action.</strong><br />
   DB-GPT is also a platform for building AI-native data agents, workflows, and applications with agents, AWEL, RAG, and multi-model support.

docs/docs/sandbox/index.md

@@ -0,0 +1,245 @@
+---
+sidebar_position: 0
+title: Sandbox Overview
+---
+
+# Sandbox Overview
+
+DB-GPT uses a sandbox to let agents execute code and tools in an isolated runtime
+instead of running directly in the host environment.
+
+This matters for agent workflows because an agent often needs to do more than
+reason in text. It may need to run code, execute shell commands, install
+dependencies, generate files, and keep execution state across multiple steps.
+
+The sandbox is the execution boundary that makes those actions safer and more
+manageable.
+
+## What is a sandbox?
+
+In DB-GPT, a sandbox is an isolated execution environment used by an agent when it
+needs to execute code, run commands, or manipulate files as part of a task.
+
+Instead of letting the agent operate directly on the host system, the sandbox
+provides:
+
+- process isolation
+- resource limits
+- controlled working directories
+- optional dependency installation
+- session lifecycle management
+- a clear boundary between reasoning and execution
+
+## How the sandbox works with agents
+
+The agent decides **what** to do next. The sandbox executes **how** that action is
+run.
+
+```mermaid
+flowchart TB
+    User["User / UI"] --> API["dbgpt-app API"]
+    API --> Agent["ReAct Agent / Agent Logic"]
+    Agent --> Decide["Select tool or code action"]
+    Decide --> Sandbox["Sandbox Runtime"]
+
+    subgraph SandboxLayer["Sandbox execution"]
+        Session["Session lifecycle"]
+        Exec["Code / shell execution"]
+        Files["File & report generation"]
+        Limits["Memory / CPU / timeout / isolation"]
+    end
+
+    Sandbox --> Session
+    Sandbox --> Exec
+    Sandbox --> Files
+    Sandbox --> Limits
+
+    Exec --> Observation["Execution result / observation"]
+    Observation --> Agent
+    Agent --> Result["Final answer / report / UI output"]
+```
+
+## Why agents need a sandbox
+
+An agent that can execute code without isolation is difficult to operate safely in
+real environments. The sandbox gives DB-GPT a dedicated runtime for actions such
+as:
+
+- code execution
+- shell command execution
+- dependency installation
+- file creation and retrieval
+- multi-step stateful analysis
+
+This is especially important for data analysis, report generation, and tool-driven
+workflows where the agent must combine reasoning with real execution.
+
+## DB-GPT's current sandbox solution
+
+DB-GPT's sandbox implementation lives in:
+
+- `packages/dbgpt-sandbox/`
+
+The current design is a layered, extensible sandbox runtime with multiple backend
+options.
+
+### Runtime backends
+
+The runtime factory automatically chooses the best available backend in this order:
+
+- Docker
+- Podman
+- Nerdctl
+- Local runtime
+
+Implementation anchor:
+
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
+
+This allows DB-GPT to prefer container isolation when available and fall back to a
+local execution mode for development or environments without container support.
+
+## Layered architecture in `dbgpt-sandbox`
+
+DB-GPT's sandbox is implemented as a small runtime system with several layers.
+
+### 1. Execution layer
+
+The execution layer provides the runtime implementations and the core abstractions.
+
+- `base.py` defines shared runtime/session/result/config interfaces
+- `docker_runtime.py`, `podman_runtime.py`, `nerdctl_runtime.py`, `local_runtime.py`
+  implement concrete runtimes
+- `runtime_factory.py` selects the runtime backend
+
+### 2. Control layer
+
+The control layer manages task lifecycle and execution orchestration.
+
+Implementation anchor:
+
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
+
+This layer handles operations such as:
+
+- connect
+- configure
+- execute
+- status
+- disconnect
+- get file
+
+It also manages session creation and session-scoped execution.
+
+### 3. User layer
+
+The user layer exposes the sandbox service interface used by callers.
+
+Implementation anchors:
+
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/service.py`
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/schemas.py`
+
+### 4. Display layer
+
+The display layer packages outputs for runtime-specific display or file-oriented
+results.
+
+Implementation anchor:
+
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/display_layer/display_layer.py`
+
+## Session model and stateful execution
+
+One important part of the DB-GPT sandbox design is that it supports **session-based
+stateful execution**.
+
+That means:
+
+- a sandbox session can be created once
+- multiple execution steps can run in the same session
+- installed dependencies can remain available in later steps
+- files produced in one step can be reused in the next step
+
+This is important for agent workflows where a task is solved through multiple
+reasoning and execution rounds rather than a single tool call.
+
+## Current integration in DB-GPT app
+
+Today, DB-GPT already uses sandbox execution in application-side agent tooling.
+
+For example, the `shell_interpreter` tool in:
+
+- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
+
+uses `dbgpt-sandbox` `LocalRuntime` to execute shell commands with:
+
+- process isolation
+- memory limits
+- timeout limits
+- security validation
+
+The current implementation there is **stateless per call** for shell execution: each
+tool call creates a temporary sandbox session and destroys it after completion.
+
+So the repo currently contains both:
+
+- a more complete `dbgpt-sandbox` design for reusable sandbox sessions
+- a practical app-side integration already using sandboxed execution for tools
+
+## What DB-GPT supports today
+
+Based on the current `dbgpt-sandbox` implementation, DB-GPT is moving toward a
+general-purpose agent runtime that supports:
+
+- multi-runtime sandbox execution
+- safe code and shell execution
+- stateful sandbox sessions
+- dependency installation inside the sandbox
+- task lifecycle control
+- file retrieval from sandbox sessions
+
+This makes the sandbox suitable for agent scenarios such as:
+
+- code agents
+- data analysis agents
+- report generation agents
+- browser/computer style execution runtimes in future extensions
+
+## High-level view of the current DB-GPT sandbox direction
+
+```mermaid
+flowchart TB
+    Apps["Agent applications"] --> Access["Access layer"]
+    Access --> Runtime["Agent sandbox runtime"]
+
+    subgraph AccessLayer["Access layer"]
+        SDK["SDK / API / CLI"]
+    end
+
+    subgraph RuntimeLayer["Sandbox runtime"]
+        Code["Code execution"]
+        Browser["Browser / GUI style execution"]
+        SessionMgmt["Lifecycle / snapshot / state / files"]
+        Isolation["Isolation / limits / runtime selection"]
+    end
+
+    Runtime --> Code
+    Runtime --> Browser
+    Runtime --> SessionMgmt
+    Runtime --> Isolation
+```
+
+This diagram is conceptual. It shows the direction of the sandbox as a dedicated
+runtime layer under agent applications, while the current repo implementation
+already provides the execution, control, session, and runtime selection foundations
+in `dbgpt-sandbox`.
+
+## Key implementation anchors
+
+- `packages/dbgpt-sandbox/README.md`
+- `packages/dbgpt-sandbox/src/docs/architecture.md`
+- `packages/dbgpt-sandbox/src/docs/usage.md`
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
+- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
+- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`

docs/sidebars.js

@@ -155,11 +155,19 @@ const sidebars = {
               type: "category",
               label: "Datasource Integrations",
               items: [
+                { type: "doc", id: "installation/integrations/mysql_install" },
+                { type: "doc", id: "installation/integrations/sqlite_install" },
                 { type: "doc", id: "installation/integrations/clickhouse_install" },
                 { type: "doc", id: "installation/integrations/postgres_install" },
                 { type: "doc", id: "installation/integrations/duckdb_install" },
+                { type: "doc", id: "installation/integrations/hive_install" },
                 { type: "doc", id: "installation/integrations/mssql_install" },
                 { type: "doc", id: "installation/integrations/oracle_install" },
+                { type: "doc", id: "installation/integrations/oceanbase_install" },
+                { type: "doc", id: "installation/integrations/gaussdb_install" },
+                { type: "doc", id: "installation/integrations/doris_install" },
+                { type: "doc", id: "installation/integrations/starrocks_install" },
+                { type: "doc", id: "installation/integrations/vertica_install" },
               ],
             },
             {
@@ -250,6 +258,14 @@ const sidebars = {
         },
       ],
     },
+    {
+      type: "category",
+      label: "Sandbox",
+      collapsed: true,
+      collapsible: true,
+      items: [{ type: "doc", id: "sandbox/index", label: "Overview" }],
+    },
+
 
     {
       type: "category",
@@ -353,8 +369,6 @@ const sidebars = {
       collapsible: true,
       items: [
         { type: "doc", id: "modules/rag", label: "RAG Overview" },
-        { type: "doc", id: "application/graph_rag", label: "GraphRAG" },
-        { type: "doc", id: "application/apps/chat_knowledge", label: "Chat Knowledge Base" },
         {
           type: "category",
           label: "RAG Integrations",
@@ -376,10 +390,10 @@ const sidebars = {
             { type: "doc", id: "awel/cookbook/first_rag_with_awel" },
           ],
         },
-        { type: "doc", id: "application/advanced_tutorial/rag", label: "Advanced RAG" },
       ],
     },
 
+
     {
       type: "category",
       label: "Datasources",
@@ -388,7 +402,6 @@ const sidebars = {
       items: [
         { type: "doc", id: "modules/connections", label: "Connections Overview" },
         { type: "doc", id: "application/datasources", label: "Datasources" },
-        { type: "doc", id: "agents/introduction/database", label: "Agent + Database" },
         {
           type: "category",
           label: "Datasource Integrations",
@@ -538,11 +551,19 @@ const sidebars = {
               type: "category",
               label: "Datasource Integrations",
               items: [
+                { type: "doc", id: "installation/integrations/mysql_install" },
+                { type: "doc", id: "installation/integrations/sqlite_install" },
                 { type: "doc", id: "installation/integrations/clickhouse_install" },
                 { type: "doc", id: "installation/integrations/postgres_install" },
                 { type: "doc", id: "installation/integrations/duckdb_install" },
+                { type: "doc", id: "installation/integrations/hive_install" },
                 { type: "doc", id: "installation/integrations/mssql_install" },
                 { type: "doc", id: "installation/integrations/oracle_install" },
+                { type: "doc", id: "installation/integrations/oceanbase_install" },
+                { type: "doc", id: "installation/integrations/gaussdb_install" },
+                { type: "doc", id: "installation/integrations/doris_install" },
+                { type: "doc", id: "installation/integrations/starrocks_install" },
+                { type: "doc", id: "installation/integrations/vertica_install" },
               ],
             },
             {
@@ -583,18 +604,25 @@ const sidebars = {
   sidebarDatasources: [
     { type: "doc", id: "modules/connections", label: "Connections Overview" },
     { type: "doc", id: "application/datasources", label: "Datasources" },
-    { type: "doc", id: "agents/introduction/database", label: "Agent + Database" },
     {
       type: "category",
       label: "Datasource Integrations",
       collapsed: false,
       collapsible: false,
       items: [
+        { type: "doc", id: "installation/integrations/mysql_install" },
+        { type: "doc", id: "installation/integrations/sqlite_install" },
         { type: "doc", id: "installation/integrations/clickhouse_install" },
         { type: "doc", id: "installation/integrations/postgres_install" },
         { type: "doc", id: "installation/integrations/duckdb_install" },
+        { type: "doc", id: "installation/integrations/hive_install" },
         { type: "doc", id: "installation/integrations/mssql_install" },
         { type: "doc", id: "installation/integrations/oracle_install" },
+        { type: "doc", id: "installation/integrations/oceanbase_install" },
+        { type: "doc", id: "installation/integrations/gaussdb_install" },
+        { type: "doc", id: "installation/integrations/doris_install" },
+        { type: "doc", id: "installation/integrations/starrocks_install" },
+        { type: "doc", id: "installation/integrations/vertica_install" },
       ],
     },
     {
@@ -611,6 +639,8 @@ const sidebars = {
       ],
     },
   ],
+  sidebarSandbox: [{ type: "doc", id: "sandbox/index", label: "Overview" }],
+
 
   sidebarAwel: [
     { type: "doc", id: "awel/awel", label: "What is AWEL?" },
@@ -711,7 +741,6 @@ const sidebars = {
   sidebarKnowledge: [
     { type: "doc", id: "modules/rag", label: "RAG Overview" },
     { type: "doc", id: "application/graph_rag", label: "GraphRAG" },
-    { type: "doc", id: "application/apps/chat_knowledge", label: "Chat Knowledge Base" },
     {
       type: "category",
       label: "RAG Integrations",
@@ -735,7 +764,6 @@ const sidebars = {
         { type: "doc", id: "awel/cookbook/first_rag_with_awel" },
       ],
     },
-    { type: "doc", id: "application/advanced_tutorial/rag", label: "Advanced RAG" },
   ],
 
   sidebarTools: [
@@ -912,6 +940,13 @@ module.exports = {
       collapsible: true,
       items: sidebars.sidebarDatasources,
     },
+    {
+      type: "category",
+      label: "Sandbox",
+      collapsed: true,
+      collapsible: true,
+      items: sidebars.sidebarSandbox,
+    },
     {
       type: "category",
       label: "AWEL",