智能诊断 Agent（obdiag agent）

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

自 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。

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 为准。

命令说明

obdiag agent [options]

常用选项：

选项名	是否必选	说明
-c	否	集群配置文件路径，默认 `~/.obdiag/config.yml`。
--config	否	需被 obdiag 诊断的集群的配置，格式：`--config key1=value1 --config key2=value2`。支持通过该选项配置的参数可参见 obdiag 配置。
--config_password	否	使用加密配置文件时的解密密码。具体介绍可参见配置文件加密。
-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`	列出已保存会话。

使用示例

# 交互模式
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。