---
title: "智能诊断 Agent（obdiag agent） - 敏捷诊断工具 V4.3.0 | OceanBase 文档中心"
description: 智能诊断 Agent（obdiag agent） 自 V4.3.0 起，交互式智能诊断入口变更为顶级命令 obdiag agent 。V4.x 曾提供的 obdiag tool ai_assistant 命令已移除，请使用 obdiag agent 命令。 Agent 基于 Pydantic-AI 与 MCP ，支持…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*5ZXST55u540AAAAAAAAAAAAADiGDAQ/original) 敏捷诊断工具V 4.3.0

# 智能诊断 Agent（obdiag agent）

更新时间：2026-07-23 16:06:05

[编辑](https://github.com/oceanbase/odt-doc/edit/V4.3.0/zh-CN/490.obdiag_agent.md)  

自 **V4.3.0** 起，交互式智能诊断入口变更为顶级命令 `obdiag agent`。V4.x 曾提供的 `obdiag tool ai_assistant` 命令已移除，请使用 `obdiag agent` 命令。

Agent 基于 **Pydantic-AI** 与 **MCP**，支持自然语言描述诊断需求，并调用 obdiag 的采集、分析、巡检、根因分析等能力。

#### 注意

该功能为 **BETA 版本**，需配置 LLM（如 OpenAI 或兼容接口）。默认启用内置 MCP 将诊断能力以工具形式暴露给模型；可按需在 `agent.yml` 中接入外部 MCP。

## 功能介绍

| 能力 | 说明 |
| --- | --- |
| **自然语言交互** | 用自然语言描述需求（如“收集日志”、“巡检集群”、“根因分析”），由 Agent 解析并调用相应工具。 |
| **内置 MCP 工具** | 默认启用内置 MCP，将 gather/analyze/check/rca 等命令封装为工具，由模型按需调用。 |
| **多集群** | 默认使用 `~/.obdiag/config.yml` 文件；会话中可用 `/use` 切换配置文件或短名。 |
| **会话续跑** | 退出时自动保存会话，可通过 `obdiag agent --resume <session_id>` 恢复会话。 |
| **Skills** | 支持 pydantic-ai-skills；预设技能可在初始化时同步至 `~/.obdiag/agent/skills/`（见 `config/agent.yml` 文件中 `skills` 模块）。 |

## 注意事项

- **API 费用**：调用外部 LLM 可能产生费用，请注意用量与密钥安全。
 - **敏感信息**：请通过 `tool_approval` 等配置控制 SQL、bash 等敏感操作前的确认行为。
 - **网络与权限**：执行 gather/check/rca 等工具时，对 SSH、集群连通性的要求与直接执行对应 obdiag 子命令一致。

## 前置配置

配置文件路径：`~/.obdiag/config/agent.yml`，若目录不存在可先创建并复制样例。源码安装时，样例位于 obdiag 仓库 `conf/agent.yml.example`；RPM 安装通常在 `/opt/oceanbase-diagnostic-tool/conf/agent.yml.example`。

```bash
mkdir -p ~/.obdiag/config
# 源码安装时，样例位于 obdiag 仓库 conf/agent.yml.example；RPM 安装通常在 /opt/oceanbase-diagnostic-tool/conf/agent.yml.example
cp /opt/oceanbase-diagnostic-tool/conf/agent.yml.example ~/.obdiag/config/agent.yml

```

### 配置结构概要

| 模块 | 说明 |
| --- | --- |
| **llm** | 配置大模型信息，`api_key` 通常需要配置，也可通过环境变量提供，具体以运行报错提示为准。 |
| **skills** | 配置技能信息，`directory` 默认 `~/.obdiag/agent/skills`。 |
| **oceanbase_knowledge** | 配置官方知识库网关，默认关闭。 |
| **mcp** | `servers` 用于配置外部 MCP 的 JSON 配置字符串，空则表示仅用内置 MCP。 |
| **ui** | 配置交互体验。 |

详细字段与注释请以安装包或源码中的 `conf/agent.yml.example` 为准。

## 命令说明

```shell
obdiag agent [options]

```

常用选项：

| 选项名 | 是否必选 | 说明 |
| --- | --- | --- |
| -c | 否 | 集群配置文件路径，默认 `~/.obdiag/config.yml`。 |
| --config | 否 | 需被 obdiag 诊断的集群的配置，格式：`--config key1=value1 --config key2=value2`。支持通过该选项配置的参数可参见 [obdiag 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726796)。 |
| --config_password | 否 | 使用加密配置文件时的解密密码。具体介绍可参见 [配置文件加密](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726841)。 |
| -m/--message | 否 | 单次向 Agent 发送一条消息后退出（非交互）。 |
| --resume | 否 | 按会话 ID 恢复历史会话，可指定为 `/sessions` 指令中列出的 ID。 |
| -y/--yolo | 否 | 使用 `-m` 选项时，配合 `-m` 自动批准工具调用（便于脚本/测试，慎用）。 |
| -h/--help | 否 | 查看帮助。 |
| -v/--verbose | 否 | 详细日志。 |

### 交互模式内置指令（以 `/` 开头）

| 指令 | 说明 |
| --- | --- |
| `/help`、`/?` | 显示帮助。 |
| `/exit`、`/quit`、`/q` | 退出（会自动保存会话）。 |
| `/clear` | 清空当前对话历史。 |
| `/compact` | 将对话压缩摘要以节省上下文。 |
| `/usage` | 查看 token 用量等信息（依赖会话与模型返回）。 |
| `/history` | 查看对话历史。 |
| `/tools` | 列出当前可用诊断工具。 |
| `/use <name 或 path>` | 切换当前集群配置（如 `/use obdiag_test` 或 `/use /path/to/config.yml`）。 |
| `/cluster` | 显示当前激活的集群信息。 |
| `/save` | 保存当前会话。 |
| `/sessions` | 列出已保存会话。 |

## 使用示例

```shell
# 交互模式
obdiag agent

# 指定配置文件
obdiag agent -c /path/to/config.yml

# 单次提问后退出
obdiag agent -m "帮我巡检一下集群"

# 续会话
obdiag agent --resume 20260313_142055

```

## 常见问题

- **无法连接模型或提示缺少 API Key**
   检查 `~/.obdiag/config/agent.yml` 中 `llm.api_key`、`llm.base_url` 是否与所用服务商一致。
 - **如何仅使用内置诊断工具**
   保持 `mcp.servers` 为空即可使用内置 MCP；`llm` 仍须指向可访问的模型服务。
 - **如何查看可用工具**
   交互模式下输入 `/tools`。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线