diff --git a/02-use-cases/mini_aiops_copy/README.md b/02-use-cases/mini_aiops_copy/README.md new file mode 100644 index 0000000..eb2d97a --- /dev/null +++ b/02-use-cases/mini_aiops_copy/README.md @@ -0,0 +1,139 @@ +# AI运维 Agent - Mini AIOps + +## 概述 + +> 本项目基于Veadk开发,实现了一个基于AI的运维智能工具 + +## 核心功能 + +本项目提供以下核心功能: + +- 智能云资源巡检:自动梳理云上资源运行状态,发现潜在风险 +- 一键问题诊断:结合日志、监控和主机诊断能力给出故障原因分析 +- 运维知识问答:基于内置知识库回答常见运维问题和 SOP 流程 +- 多 Agent 协同:通过 CCAPI 等 MCP 工具自动执行部分运维操作 +- 长短期记忆:结合会话记忆与长期记忆提供持续性的运维助手体验 + +## Agent 能力 + +本项目当前内置一个总控 Agent 和一个子 Agent: + +- ve_ai_ops_agent:面向云计算运维场景的总控 Agent,负责理解用户需求并规划巡检、诊断和优化流程。 +- ccapi_agent:专注云资源管控的子 Agent,通过 CCAPI MCP 工具集查看和调整云上资源配置。 + +## 本地运行 + +### 环境准备 + +开始前,请确保您的开发环境满足以下要求: + +- Python 3.10 或更高版本 +- VeADK 0.2.28 或更高版本 +- 推荐使用 `uv` 进行依赖管理 +- 获取火山方舟 API KEY +- 获取火山引擎 AK/SK + +### 快速入门 + +请按照以下步骤在本地部署和运行本项目。 + +#### 1. 下载代码并安装依赖 + +```bash +# 克隆代码仓库 +git clone https://github.com/volcengine/agentkit-samples.git +cd agentkit-samples/02-use-cases/mini_aiops + +# 安装项目依赖 +uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple +``` + +#### 2. 配置环境变量 + +```bash +export MODEL_AGENT_API_KEY="xxxxx" +export VOLCENGINE_ACCESS_KEY="xxxxxx" +export VOLCENGINE_SECRET_KEY="xxxxxx" +``` + +#### 4. 启动服务 + +1. 请先保证环境变量配置正确 + +2. 本地`veadk web`启动测试(注意:请保持在`agentkit-samples/02-use-cases`目录) + +```bash +veadk web +``` + +1. 进入服务url `http://127.0.0.1:8000` +2. 选择`mini_aiops` +3. 与Agent进行对话 + +#### 5. 测试服务 + +![image1](./img/image1.png) + +## 目录结构说明 + +```plaintext +mini_aiops/ +├── agent.py # AIOps Agent 定义 +├── README.md # 使用说明与功能介绍 +├── requirements.txt# 依赖列表(基于 veadk-python) +├── pyproject.toml # 项目配置(uv/构建配置) +├── sop_aiops.md # 运维 SOP 文档(可导入到知识库) +├── img/ # README 中使用的示意截图 +└── uv.lock # uv 生成的锁定文件 +``` + +## AgentKit 部署 + +```bash +# 1. 进入`mini_aiops` +cd mini_aiops +# 2. 初始化配置 +agentkit config +# 3. 根据说明进行配置 +# 注意:第7步无需设置环境变量,第8步可以选择cloud模式 + +# 4. 部署 +agentkit launch +``` + +部署过程完成后,由于运维MCP工具需要ECS相关权限,请前往控制台开通相关权限 + +进入控制台 + +![image4](./img/image4.png) + +开通相关权限 + +![image5](./img/image5.png) + +## 示例提示词 + +以下是一些常用的提示词示例: + +"创建IAM用户" +"查看现有的ECS实例" +"列出可用的资源类型" +"更新某个资源的配置" + +## 效果展示 + +部署中,控制台界面 +![image2](./img/image2.png) +部署完成后,bash界面 +![image3](./img/image3.png) + +线上测试成功 +![image6](./img/image6.png) + +## 常见问题 + +常见问题列表待补充。 + +## 代码许可 + +本项目采用开源许可证,详情请参考项目根目录下的 LICENSE 文件。 diff --git a/02-use-cases/mini_aiops_copy/__init__.py b/02-use-cases/mini_aiops_copy/__init__.py new file mode 100644 index 0000000..7c8b05e --- /dev/null +++ b/02-use-cases/mini_aiops_copy/__init__.py @@ -0,0 +1 @@ +from .agent import root_agent # noqa diff --git a/02-use-cases/mini_aiops_copy/agent.py b/02-use-cases/mini_aiops_copy/agent.py new file mode 100644 index 0000000..1914f09 --- /dev/null +++ b/02-use-cases/mini_aiops_copy/agent.py @@ -0,0 +1,77 @@ +import os + +from google.adk.planners import BuiltInPlanner +from google.adk.tools.mcp_tool.mcp_toolset import ( + McpToolset, + StdioServerParameters, + StdioConnectionParams, +) +from google.genai import types +from veadk import Agent +from veadk.auth.veauth.utils import get_credential_from_vefaas_iam +from veadk.config import getenv # noqa +from veadk.knowledgebase.knowledgebase import KnowledgeBase +from veadk.memory.short_term_memory import ShortTermMemory +from agentkit.apps import AgentkitAgentServerApp + +env_dict = { + "VOLCENGINE_ACCESS_KEY": os.getenv("VOLCENGINE_ACCESS_KEY"), + "VOLCENGINE_SECRET_KEY": os.getenv("VOLCENGINE_SECRET_KEY"), +} +if not (env_dict["VOLCENGINE_ACCESS_KEY"] and env_dict["VOLCENGINE_SECRET_KEY"]): + credential = get_credential_from_vefaas_iam() + env_dict["VOLCENGINE_ACCESS_KEY"] = credential.access_key_id + env_dict["VOLCENGINE_SECRET_KEY"] = credential.secret_access_key + env_dict["VOLCENGINE_SESSION_TOKEN"] = credential.session_token + +short_term_memory = ShortTermMemory(backend="local") + +### Auto create knowledgebase if not exist for aiops +knowledgebase = KnowledgeBase(backend="local", index="aiops_kb", top_k=3) + +file_path = os.path.join(os.path.dirname(__file__), "sop_aiops.md") +knowledgebase.add_from_files(files=[file_path]) + +### control center mcp server +server_parameters = StdioServerParameters( + command="uvx", + args=[ + "--from", + "git+https://github.com/volcengine/mcp-server#subdirectory=server/mcp_server_ccapi", + "mcp-server-ccapi", + ], + env=env_dict, +) + +ccapi_mcp_toolset = McpToolset( + connection_params=StdioConnectionParams( + server_params=server_parameters, timeout=180.0 + ), + errlog=None, +) + +agent: Agent = Agent( + name="root_agent", + model_name="deepseek-v3-1-terminus", + description="云资源管控智能体", + instruction="你是一个云资源管控专家,擅长通过 CCAPI 管理各类云资源", + knowledgebase=knowledgebase, + tools=[ccapi_mcp_toolset], + planner=BuiltInPlanner( + thinking_config=types.ThinkingConfig( + include_thoughts=False, + thinking_budget=0, + ) + ), +) + +root_agent = agent + + +agent_server_app = AgentkitAgentServerApp( + agent=agent, + short_term_memory=short_term_memory, +) + +if __name__ == "__main__": + agent_server_app.run(host="0.0.0.0", port=8000) diff --git a/02-use-cases/mini_aiops_copy/deploy.sh b/02-use-cases/mini_aiops_copy/deploy.sh new file mode 100644 index 0000000..04e44da --- /dev/null +++ b/02-use-cases/mini_aiops_copy/deploy.sh @@ -0,0 +1,13 @@ +#!/bin/bash +set -euo pipefail + +agentkit config \ + --agent_name mini_aiops \ + --entry_point agent.py \ + --description "a mini agent for aiops" \ + --launch_type cloud \ + --image_tag v1.0.0 \ + --region cn-beijing + +agentkit launch + diff --git a/02-use-cases/mini_aiops_copy/img/image1.png b/02-use-cases/mini_aiops_copy/img/image1.png new file mode 100644 index 0000000..c40b108 Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image1.png differ diff --git a/02-use-cases/mini_aiops_copy/img/image2.png b/02-use-cases/mini_aiops_copy/img/image2.png new file mode 100644 index 0000000..fb57c6b Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image2.png differ diff --git a/02-use-cases/mini_aiops_copy/img/image3.png b/02-use-cases/mini_aiops_copy/img/image3.png new file mode 100644 index 0000000..e0e0019 Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image3.png differ diff --git a/02-use-cases/mini_aiops_copy/img/image4.png b/02-use-cases/mini_aiops_copy/img/image4.png new file mode 100644 index 0000000..e170c92 Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image4.png differ diff --git a/02-use-cases/mini_aiops_copy/img/image5.png b/02-use-cases/mini_aiops_copy/img/image5.png new file mode 100644 index 0000000..d875f45 Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image5.png differ diff --git a/02-use-cases/mini_aiops_copy/img/image6.png b/02-use-cases/mini_aiops_copy/img/image6.png new file mode 100644 index 0000000..cbb5de0 Binary files /dev/null and b/02-use-cases/mini_aiops_copy/img/image6.png differ diff --git a/02-use-cases/mini_aiops_copy/pyproject.toml b/02-use-cases/mini_aiops_copy/pyproject.toml new file mode 100644 index 0000000..d1e1508 --- /dev/null +++ b/02-use-cases/mini_aiops_copy/pyproject.toml @@ -0,0 +1,10 @@ +[project] +name = "mini-aiops" +version = "0.1.0" +description = "Add your description here" +readme = "README.md" +requires-python = ">=3.12" +dependencies = [ + "agentkit-sdk-python>=0.2.0", + "veadk-python==0.5.0", +] diff --git a/02-use-cases/mini_aiops_copy/requirements.txt b/02-use-cases/mini_aiops_copy/requirements.txt new file mode 100644 index 0000000..e3e3aa7 --- /dev/null +++ b/02-use-cases/mini_aiops_copy/requirements.txt @@ -0,0 +1,2 @@ +agentkit-sdk-python>=0.2.0 +veadk-python==0.5.0 \ No newline at end of file diff --git a/02-use-cases/mini_aiops_copy/sop_aiops.md b/02-use-cases/mini_aiops_copy/sop_aiops.md new file mode 100644 index 0000000..6974672 --- /dev/null +++ b/02-use-cases/mini_aiops_copy/sop_aiops.md @@ -0,0 +1,257 @@ +--- + +# 📘 **统一故障排查 SOP(Standard Operating Procedure)** + +**适用范围**:云上业务、应用服务、主机、数据库、监控、链路追踪、安全事件 +**工具集**:TLS-MCP、VMP-MCP、ECS Assistant、RDS-MySQL MCP、Sec-Agent、APMPlus-MCP + +--- + +## 🧭 1. 总则 + +当出现以下异常情况时,应按照本 SOP 进行统一排查: + +* 请求失败率提升、5xx 变高 +* RT 延迟异常升高 +* CPU / 内存 / IO / 网络 出现瓶颈 +* 数据库响应变慢或锁等待 +* 追踪链路出现异常 delay +* 安全事件或风险告警 + +排查顺序: + +**日志 → 监控 → 主机 → 数据库 → 安全 → 链路追踪 → 根因定位** + +--- + +## 📑 2. 日志排查(TLS-MCP) + +### 2.1 触发条件 + +* 服务报错 / 请求失败 +* 用户反馈异常行为 +* 上游或下游返回错误 + +### 2.2 操作步骤 + +1. 通过 `tls.queryLogs` 查询日志 +2. 按以下维度过滤: + + * 服务名 + * 环境(prod / staging) + * 时间范围 + * 关键字:`error`, `exception`, `timeout`, `panic` +3. 提取可疑日志片段,标注异常节点 +4. 若日志无法定位继续进入监控排查阶段 + +### 2.3 输出内容 + +* 错误类型描述 +* 3 条以上关键日志 +* 初步异常判断(业务逻辑 / 依赖接口 / 系统错误) + +--- + +## 📊 3. 监控排查(VMP-MCP) + +### 3.1 触发条件 + +* CPU/内存/Load 异常 +* QPS、RT、Success Rate 波动 +* 依赖调用错误率升高 + +### 3.2 操作步骤 + +1. 使用 `vmp.queryMetrics` 查询: + + * 系统指标:CPU/Mem/Load/IO/Network/Disk + * 应用指标:QPS/RT/Error Rate + * 集群指标:节点状态/容器状态 +2. 检查异常趋势: + + * 5 分钟 + * 1 小时 + * 24 小时 +3. 标记异常时间点 + +### 3.3 输出内容 + +* 异常指标列表 +* 指标趋势分析 +* 初步判断问题在主机/应用/数据库/网络? + +--- + +## 🖥️ 4. 主机诊断(ECS Assistant) + +### 4.1 触发条件 + +* 整机资源占用异常 +* OOM、进程崩溃 +* IO 或网络异常 +* 主机层面引发业务波动 + +### 4.2 操作步骤 + +1. 执行 `ecs.assistant.diagnose` +2. 查看以下内容: + + * top 进程 CPU / Mem + * OOM Kill + * 网络丢包、延迟 + * IO 利用率 + * 文件系统使用情况 +3. 判断是否主机层问题导致业务故障 + +### 4.3 输出内容 + +* 异常资源及值 +* 异常进程 +* 主机健康度结论 + +--- + +## 🗄️ 5. 数据库慢 SQL 排查(RDS-MySQL MCP) + +### 5.1 触发条件 + +* API 延迟变大但 CPU 正常 +* 数据库连接数升高 +* SQL 阻塞、锁等待 + +### 5.2 操作步骤 + +1. 调用 `rds.mysql.querySlowLog` +2. 检查: + + * Top 慢 SQL + * 执行次数 + * Rows examined + * Lock Time + * 是否全表扫描 +3. 判断是否是 SQL 不佳、索引缺失、锁竞争等 + +### 5.3 输出内容 + +* Top 3 慢 SQL +* SQL/索引层问题描述 +* 建议(加索引 / 改写 SQL / 调整连接池) + +--- + +## 🛡️ 6. 安全风险排查(Sec-Agent) + +### 6.1 触发条件 + +* 异常登录、端口访问、扫描行为 +* 高危漏洞 +* 可疑进程 +* 账号滥用或行为异常 + +### 6.2 操作步骤 + +1. 执行 `sec.agent.scanRisk` +2. 查看以下风险: + + * SSH/控制台异常登录 + * 恶意程序 + * 异常网络通信 + * 高危漏洞(CVE) + * 配置不合规 +3. 如发现高危项,及时升级为安全 incident + +### 6.3 输出内容 + +* 风险清单(高/中/低) +* 可能影响业务的风险项 +* 修复优先级建议 + +--- + +## 🔍 7. 链路追踪(APMPlus-MCP) + +### 7.1 触发条件 + +* 单请求延迟变长 +* 多服务调用链不稳定 +* 业务出现分布式瓶颈 +* 下游服务响应慢但原因不明 + +### 7.2 操作步骤 + +1. 使用 `apmplus.queryTrace` 查询链路 +2. 查看: + + * Span 耗时 + * 最大延迟点 + * 错误 span + * 数据库/Redis/RPC 调用延迟 + * 等待队列情况(Queue Wait) +3. 确定瓶颈在应用、数据库、缓存或外部依赖 + +### 7.3 输出内容 + +* 最慢 Span +* 耗时链路图描述 +* 初步推断瓶颈原因 + +--- + +## 🧩 8. 根因分析(RCA) + +整合上述信息,判断根因为: + +| 层级 | 示例根因 | +| ---- | -------------------- | +| 应用层 | 代码异常、线程池耗尽、连接池满、错误逻辑 | +| 主机层 | CPU 过高、IO 饱和、网络问题 | +| 数据库层 | 慢 SQL、锁等待、索引缺失 | +| 网络层 | DNS、带宽、跨可用区延迟 | +| 安全层 | 恶意请求、账号滥用、病毒 | +| 依赖层 | 第三方 API 异常、下游服务慢 | +| 调度层 | 容器重启、Pod 驱逐、调度不均 | + +--- + +## 🛠️ 9. 修复与验证 + +### 9.1 执行修复方案 + +* 热修复应用 +* 扩缩容 +* 优化 SQL +* 清理主机资源 +* 屏蔽攻击 IP +* 调整配置、索引或缓存策略 + +### 9.2 验证修复效果 + +* 指标恢复正常 +* 日志无异常 +* Trace 延迟恢复 +* 重新请求验证链路 +* 数据库负载下降 + +--- + +## 📝 10. 事件记录(Incident Record) + +每次排查必须记录以下内容: + +* 时间线(Timeline) +* 影响范围 +* Root Cause +* 处理步骤 +* 指标截图/日志截图 +* 预防措施(Action Items) + +--- + +如需,我可以进一步生成: + +🔧 **版本包含工具调用示例(具体 MCP JSON 调用示例)** +📄 **企业内审版带编号的 ISO 风格 SOP** +📦 **将 SOP 导出为 PDF/Word 版本** +🧭 **对应的自动巡检脚本(Python/Go)** + +需要哪个版本? \ No newline at end of file