一、背景介绍
·Agent 缺乏数据库专业能力：AI 编程助手擅长代码生成和工程任务，但不具备数据库诊断、巡检、慢 SQL 分析等 DBA 专家能力。开发者在编码过程中遇到数据库问题（如慢查询、CPU 异常、主从延迟），需要切换到云控制台手动排查，工作流被打断，效率降低。
·开发与运维流程割裂：传统模式下，开发者使用 Agent 写代码，数据库问题需要 DBA 介入或手动登录控制台处理，开发和运维之间缺乏统一的 AI 驱动工作流。发布前应用性能评估与健康扫描等环节无法嵌入自动化发布流程，协作效率低。
·多平台重复对接成本高：企业内部可能同时使用多种 Agent 工具（IDE 助手 + 工作流编排 + ChatOps Bot），如果每个平台分别对接数据库 API，需要重复编写签名逻辑、SSE 解析、会话管理等代码，开发和维护成本高。
二、解决方案
TencentDB Agent 推出 TencentDB Agent Skill（标准化 Agent 技能包），遵循通用 Skill 协议（SKILL.md 描述文件 + scripts/ 可执行脚本），让任何支持 Skill 加载的 AI Agent 即插即用获取 TencentDB Agent 的 DBA 专家能力。Agent 读取 SKILL.md 后自动理解调用域名、签名方式、参数格式和响应解析规则，通过 CreateChatCompletion SSE 流式接口向 TencentDB Agent 实例发送消息并接收流式响应，全程无需额外编写集成代码。
·TencentDB Agent Skill：标准化 Agent 技能包，包含 SKILL.md（能力描述文件）、scripts/chat.py（零依赖 CLI 客户端，自动完成 TC3 签名和 SSE 流式解析）、references/python-integration.md（集成参考文档），支持单消息和交互式多轮对话模式。
·CreateChatCompletion API：TencentDB Agent 对话接口（归入 腾讯云数据库 AI 服务云 API 智能体实例分组），通过 SSE 流式协议传输，Agent 实时接收 TencentDB Agent 的推理过程和执行结果，支持工具调用事件可视化。
通过标准化 Agent 技能包，AI Agent 通过自然语言直接调用 TencentDB Agent 的 DBA 专家能力（涵盖慢 SQL 诊断、CPU 异常分析、主从延迟诊断、健康巡检、参数调优等），让 DBA 与开发者在已有的 Agent 环境中即可完成数据库运维操作。
三、方案优势
·Agent 原生设计：遵循 Skill 标准协议（SKILL.md 描述文件 + scripts/ 可执行脚本），任何支持 Skill 加载的 Agent 框架均可即插即用，无需针对特定平台做适配开发。
·零配置调用：Agent 读取 SKILL.md 后自动获知调用域名、签名方式、参数格式和响应解析规则，开发者无需额外编写集成逻辑或指导 Agent 如何调用。
·控制台可追溯：每次 Agent 调用自动创建 Session，对话记录在 TencentDB Agent 控制台可见，支持事后审计与问题追溯，满足企业合规需求。
·安全可控：采用 TC3-HMAC-SHA256 签名鉴权机制，Agent 只需持有 API 密钥即可安全调用。结合腾讯云 CAM 权限体系与 TencentDB Agent L1-L4 分级授权，支持最小权限原则，保障数据库访问安全。
·零外部依赖：客户端脚本仅依赖 Python 3.9+ 标准库，无需安装任何第三方包，降低环境配置复杂度，提升部署便利性。
·流式响应体验：基于 SSE（Server-Sent Events）流式协议传输，Agent 实时接收 TencentDB Agent 的推理过程和执行结果，支持工具调用事件可视化，提供流畅的交互体验。
四、应用场景
| 场景 | 核心痛点 | 方案关键能力 | 推荐接入方式 |
| 编码中实时诊断数据库问题 | 开发者遇到慢查询、CPU 异常等问题需切换控制台，工作流被打断 | IDE 助手内直接用自然语言调用 TencentDB Agent 诊断 | Cursor / Claude Code / CodeBuddy |
| 自动化发布前数据库检查 | 发布流程缺少数据库健康检查环节，发布后才发现数据库异常 | Agent 工作流中嵌入巡检节点，发布前自动检查 | LangChain / CrewAI / Dify |
| 运维 ChatOps | IM 中查询数据库状态需 DBA 介入，响应慢 | IM Bot 后端集成 Skill，研发自助排障 | 自研平台 + IM Bot |
| 定时巡检自动化 | 人工巡检效率低、覆盖不全 | Agent 定时调用巡检 Skill，异常自动推送 | 自研平台 + Cron 调度 |
五、Agent 平台的接入方式说明
TencentDB Agent Skill 遵循通用 Skill 协议，支持多种 Agent 平台接入。你可根据已有的 Agent 环境选择对应的安装方式：
| Agent 平台类型 | 安装方式 | 适用场景 |
| AI IDE 助手（Cursor / Claude Code / Windsurf / CodeBuddy） | 将 Skill 目录放入项目的 skills/（Cursor/Claude Code）或 .codebuddy/skills/（CodeBuddy）目录，或通过 Skill Hub 安装 | 开发过程中实时诊断数据库问题，无需离开开发环境 |
| Agent 编排框架（LangChain / CrewAI / AutoGen） | 注册为 Tool，将 chat.py 封装为可调用函数 | 自动化工作流中嵌入数据库健康检查、发布前巡检等环节 |
| 低代码 Agent 平台（Dify） | 作为"代码执行"节点接入 | 可视化编排数据库运维流程，无需编写代码 |
| 自研 Agent 平台 | 按平台 Skill 协议注册 SKILL.md + scripts/ | 企业内部 AI 平台获得 DBA 专家能力 |
| 命令行直接调用 | 直接执行 python3 scripts/chat.py | 脚本编排、CI/CD 流水线、定时任务 |
七、1. 凭证安全管理
密钥通过环境变量传入，不要写入 Skill 配置文件或代码仓库，降低泄露风险。
export TENCENTDB_AGENT_SECRET_ID="YOUR_SECRET_ID"export TENCENTDB_AGENT_SECRET_KEY="YOUR_SECRET_KEY"export TENCENTDB_AGENT_INSTANCE_ID="clawins-xxxxxxxx"
建议为 API 调用创建专用子账号，仅授予 QcloudDatabaseClawUserFullAccess 策略，遵循最小权限原则。如需进一步收窄权限，可结合 TencentDB Agent 用户角色体系，将 Agent 使用的密钥绑定只读角色（TencentDBAgent_AI_GlobalReadOnly），仅允许诊断查询类操作，不可执行任何写变更。
八、2. 实例隔离与多业务场景
如有多个业务场景（如生产环境 / 测试环境 / 不同业务线），建议为不同场景创建独立 TencentDB Agent 实例，避免权限交叉。每个实例可通过 SOUL 配置差异化的 AI 助手身份与行为边界，通过 CAM 角色限定可访问的数据库实例范围。
多个 Agent 可共用同一个 TencentDB Agent 实例——实例支持并发调用，不同 Agent 通过各自的 API 密钥鉴权后创建独立 Session，控制台中可按时间和会话标题区分不同来源的调用。
九、3. 自然语言指令规范
给 Agent 的指令越具体，TencentDB Agent 的回答越精准。建议在指令中包含以下要素：
·地域：如"广州地域"、"所有地域"
·实例标识：如实例 ID、名称前缀或标签
·时间范围：如"近 7 天"、"最近 1 小时"
·分析目标：如"慢查询 TOP 10"、"CPU 使用率趋势"、"磁盘容量预测"
例如，"分析广州地域 MySQL 实例 cdb-xxxx 近 7 天的慢查询 TOP 10，给出索引优化建议"远优于"看看数据库怎么样"。
十、4. 高频调用优化
·探活检测：使用 –no-session 参数避免产生大量空会话记录，减少控制台噪音。
·批量巡检：在单次消息中描述完整巡检范围（如"所有地域所有引擎"），让 TencentDB Agent 一次性完成，减少调用次数。
·超时处理：复杂的多地域扫描可能需要 60~90 秒，建议将 Agent 的超时设置调整为 120 秒以上，避免长时间诊断任务被中断。
·多轮追问：复杂诊断建议分步进行，先查概况，再针对异常项深入追问。同一 Session 中 TencentDB Agent 能够理解上下文关系，持续深入诊断。
十一、Skill 下载地址
·SkillHub
十二、Agent 对话示例
以下示例可在任意已安装 Skill 的 Agent 环境中直接使用。
十三、示例一：慢 SQL 治理（日常运维）
DBA 需要定期治理慢 SQL，找出消耗资源最多的 SQL 并给出优化建议。
分析广州地域 MySQL 实例近 7 天的慢查询 TOP 10，给出索引优化建议
Agent 调用 Skill 后，TencentDB Agent 将：
·连接目标数据库获取慢查询日志。
·按执行耗时排序，输出 TOP 10 慢 SQL。
·对每条 SQL 分析执行计划，给出针对性的索引优化建议。
十四、示例二：告警根因诊断（故障响应）
DBA 收到 CPU 告警后，需要快速定位是周期性业务高峰还是异常 SQL 导致。
查看 cdb-xxxxx 最近 1 小时的 CPU 使用率趋势，分析是否存在周期性尖峰
Agent 调用 Skill 后，TencentDB Agent 将：
·获取目标实例近1小时的 CPU 监控数据。
·分析使用率变化趋势，识别是否存在周期性尖峰。
·如存在异常，给出可能的原因分析和优化建议。
十五、示例三：编码中排查接口慢查询（开发调试）
开发者在编写业务代码时发现某个接口响应慢，怀疑是数据库查询导致，直接在 IDE 中让 Agent 排查。
我正在开发订单查询接口，响应较慢，帮我查一下 cdb-xxxxx 近 1 小时的慢 SQL，看看是不是 order_list 表的查询有问题，如果有就给出索引优化建议
Agent 调用 Skill 后，TencentDB Agent 将：
·拉取目标实例近1小时的慢 SQL 日志。
·筛选涉及 order_list 表的慢查询。
·分析执行计划，给出索引优化建议，开发者可据此直接在代码中调整查询逻辑或添加索引。
十六、示例四：发布前 SQL 治理（发布把关）
开发者在预发环境完成新版本功能验证后，发布到生产前需要利用 DBbrain 全链路分析和 SQL 优化能力，排查预发环境中是否存在潜在 SQL 问题（如全表扫描、缺失索引、N+1查询等）和应用层问题，做好发布前治理，避免问题随发布带入生产。
明天要把 v2.3 版本发布到生产，预发环境 MySQL 实例 cdb-staging-xxxxx 已开启审计，帮我做一次发布前 SQL 治理：1. 用全链路分析拉取最近 2 小时的 SQL 审计日志，按 SQL 模板聚合，找出消耗最高的 TOP 10 SQL2. 对其中涉及全表扫描或索引缺失的 SQL，给出索引优化建议3. 检查是否存在同一模板高频执行的 N+1 查询模式4. 汇总 DBbrain 诊断事件，确认没有未处理的严重或致命告警最后给我一个发布前的治理结论
Agent 调用 Skill 后，TencentDB Agent 将：
·调用 DBbrain 全链路分析，对预发实例最近2小时的审计日志进行 SQL 模板聚合，按 CPU 占比 / 执行耗时 / 扫描行数排序输出 TOP 10 SQL 模板。
·对 TOP SQL 逐条分析执行计划，识别全表扫描、索引缺失、临时表 / 文件排序等性能问题，给出索引添加或 SQL 改写建议。
·检测高频执行的相同模板 SQL，识别 N+1 查询模式（同一 SQL 模板在短时间内被重复调用数十次以上），帮助开发者定位应用层的批量查询问题。
·汇总 DBbrain 诊断事件，筛选严重 / 致命级别的未处理异常，确认预发环境数据库健康基线。
·综合以上分析，给出"可发布 / 需修复后发布"的治理结论，并列出需在代码中修复的具体 SQL 和优化建议。
十七、示例五：跨实例资源对比（架构评估）
开发者或架构师需要评估不同地域的资源分布情况，为容量规划或服务迁移提供依据。
对比广州和上海两个地域的 MySQL 实例数量和规格分布，帮我判断是否需要扩容
Agent 调用 Skill 后，TencentDB Agent 将：
·分别查询广州和上海地域的 MySQL 实例列表。
·按规格分类统计实例数量。
·输出对比结果，帮助了解资源分布情况并给出扩容建议。
十九、步骤一：前置准备
下表列出了开始本实践前需满足的条件：
| 条件 | 说明 |
| 腾讯云账号 | 已完成实名认证。 |
| TencentDB Agent 实例 | 已创建至少一个 TencentDB Agent 实例，且状态为运行中。具体操作请参见 创建 TencentDB Agent 实例。创建后获取其实例 ID。 |
| API 密钥 | 前往 密钥管理 获取 SecretId 和 SecretKey。注意：若尚未创建密钥，请单击新建密钥，并妥善保管 SecretId 和 SecretKey。 |
| Agent 环境 | 已安装 CodeBuddy（或其他支持 Skill 加载的 AI Agent 平台，如 Cursor、Claude Code、LangChain、Dify 等）。 |
| Python 环境 | Python 3.9+（仅需标准库，无需安装第三方包）。 |
20、步骤二：下载并安装 Skill
1. 从 SkillHub 下载 TencentDB Agent Skill 包。
2. 解压后将 tencentdb-agent-skill 目录放入 CodeBuddy 项目的 .codebuddy/skills/ 目录下。
不同 Agent 平台的安装路径：
| Agent 平台 | 安装路径 |
| Cursor / Claude Code | 项目根目录的 skills/ 下 |
| CodeBuddy | 项目的 .codebuddy/skills/ 目录，或通过 Skill Hub 安装 |
| LangChain / CrewAI | 注册为 Tool，将 chat.py 封装为可调用函数 |
| Dify | 作为"代码执行"节点接入 |
| 自研平台 | 按平台 Skill 协议注册 SKILL.md + scripts/ |
21、步骤三：配置凭证
Agent 调用 Skill 时需要腾讯云 API 密钥，即步骤一获取的 SecretId 和 SecretKey。推荐通过环境变量配置：
export TENCENTDB_AGENT_SECRET_ID="YOUR_SECRET_ID"export TENCENTDB_AGENT_SECRET_KEY="YOUR_SECRET_KEY"export TENCENTDB_AGENT_INSTANCE_ID="YOUR_INSTANCE_ID(clawins-xxxxxxxx)"
22、步骤四：验证连通性
安装完成后，在 CodeBuddy 中发送测试消息验证 Skill 是否正常工作：
帮我用 TencentDB Agent 发送一条 hello 测试消息，验证连接是否正常
Agent 连接正常时将依次完成以下操作：
·识别到需要使用 TencentDB Agent Skill。
·调用 scripts/chat.py 发送消息。
·返回 TencentDB Agent 的自我介绍（DBA 专家助手）。
如果 Agent 成功返回回答，说明 Skill 安装和配置均正确。
23、步骤五：在控制台查看执行记录
每次 Agent 调用 Skill 时，会自动在 TencentDB Agent 控制台创建会话记录：
1. 登录 TencentDB Agent 控制台。
2. 在左侧导航栏选择 TencentDB Agent > 实例管理。
3. 单击目标实例卡片，进入对话页面。
4. 在左侧会话列表中，可看到 Agent 发起的每次对话。
5. 会话标题为用户发送的消息内容，方便识别来源。
6. 单击会话可查看完整的 Agent 推理过程和工具调用记录。
注意：说明：
注意：如果 Agent 调用频率较高（如定时探活检测），可在调用时传入 –no-session 参数跳过会话创建，避免产生过多记录。
24、TencentDB Agent Skill 介绍
TencentDB Agent Skill 是腾讯云数据库 AI 服务 TencentDB Agent 推出的标准化 Agent 技能包，用于让 AI Agent 通过自然语言与 TencentDB Agent 实例进行流式对话，实现智能数据库运维。Agent 读取 SKILL.md 后自动理解能力范围与调用协议，无需额外编写集成代码。
25、核心能力
| 能力 | 说明 |
| 流式对话 | 通过 CreateChatCompletion SSE API 向 TencentDB Agent 实例发送消息并接收流式响应，实时获取推理过程和执行结果。 |
| 会话管理 | 通过 CreateClawSession 创建会话，确保对话在控制台可追溯，支持事后审计与问题追溯。 |
| 多轮追问 | 同一 Session 中支持上下文关联的多轮对话，逐步深入诊断复杂问题。 |
| DBA 专家能力 | 调用 TencentDB Agent 内置 Skill（慢 SQL 诊断、CPU 异常分析、主从延迟诊断、健康巡检 50+ 检查项、参数调优等），诊断质量与资深 DBA 对齐。 |
| TC3 签名 | 自动完成 TC3-HMAC-SHA256 签名，无需手动编写签名逻辑。 |
| 零依赖 | 客户端脚本仅依赖 Python 3.9+ 标准库，无需安装第三方包。 |
26、Skill 包结构
下载解压后，Skill 包的目录结构如下：
tencentdb-agent-skill/├── SKILL.md # Skill 描述文件（Agent 读取此文件获取能力）├── scripts/│ └── chat.py # 可执行客户端（Agent 调用此脚本）└── references/ └── python-integration.md # 集成参考文档（TC3 签名实现与 SSE 解析）
| 文件 | 用途 |
| SKILL.md | 定义 Skill 的触发关键词、使用场景、调用协议和参数格式，Agent 读取后自动理解如何调用 TencentDB Agent。 |
| scripts/chat.py | 零依赖的 CLI 客户端，支持单消息和交互式多轮对话模式，自动完成 TC3 签名和 SSE 流式解析。 |
| references/python-integration.md | 提供完整的 TC3 签名代码、HTTP 请求头格式和 SSE 解析示例，供自定义集成参考。 |
27、环境变量与参数
| 参数 | 环境变量 | 说明 |
| Secret ID | TENCENTDB_AGENT_SECRET_ID | 腾讯云 API 密钥 ID，前往 密钥管理 获取。 |
| Secret Key | TENCENTDB_AGENT_SECRET_KEY | 腾讯云 API 密钥，与 Secret ID 配对使用。 |
| Instance ID | TENCENTDB_AGENT_INSTANCE_ID | TencentDB Agent 实例 ID，格式为 clawins-xxxxxxxx。 |
| –no-session | — | 命令行参数，跳过会话创建，适用于高频探活检测场景。 |
| –verbose / -v | — | 命令行参数，显示工具调用过程，便于调试。 |
28、API 域名说明
| 域名 | 用途 | 说明 |
| tdai.ai.tencentcloudapi.com | CreateChatCompletion SSE 流式对话 | 必须使用此域名调用对话接口，不支持管理接口域名。 |
| tdai.tencentcloudapi.com | 管控面 API（实例管理、会话查询等） | 用于实例生命周期管理、会话查询等管控操作。 |
注意：使用 Skill 自带的 chat.py 时，域名已自动正确配置。如自行实现集成，请确保对话接口请求 tdai.ai.tencentcloudapi.com，否则会报 InternalError。
30、Q1：Agent 没有自动识别到 Skill 怎么办？
检查 Skill 安装路径是否正确。Agent 通常通过扫描 skills/ 目录下的 SKILL.md 文件来发现可用 Skill。请确认：
·目录名为 tencentdb-agent-skill（或符合平台命名规范）。
·SKILL.md 文件存在且内容完整。
·Skill 目录位于 Agent 的 Skill 加载路径下（如 CodeBuddy 的 .codebuddy/skills/、Cursor 的 skills/）。
31、Q2：调用时报 InternalError 错误？
这是域名配置错误的典型表现。CreateChatCompletion 接口必须请求 SSE 流式域名 tdai.ai.tencentcloudapi.com，不能使用管理接口域名 tdai.tencentcloudapi.com。如果使用 Skill 自带的 chat.py，域名已自动正确配置。
32、Q3：Agent 调用 Skill 但控制台看不到会话记录？
可能原因：
·Agent 传入了 –no-session 参数，跳过了会话创建。
·Agent 直接调用了 CreateChatCompletion 但未先调用 CreateClawSession。
使用 Skill 默认行为（不传 –no-session）即可自动创建 Session，确保对话在控制台可见。
33、Q4：能否让多个 Agent 共用同一个 TencentDB Agent 实例？
可以。TencentDB Agent 实例支持并发调用，不同 Agent 通过各自的 API 密钥鉴权后，会创建独立的 Session。控制台中可按时间和会话标题区分不同来源的调用。
如需进一步隔离，建议为不同业务场景创建独立 TencentDB Agent 实例，通过 CAM 角色限定各自可访问的数据库实例范围。
34、Q5：Skill 支持哪些 Agent 平台？
本 Skill 遵循通用的 Skill 协议（SKILL.md 描述 + scripts/ 可执行脚本），理论上支持任何能读取描述文件并执行脚本的 Agent 平台，包括但不限于：
·AI IDE 助手：Cursor、Claude Code、Windsurf、CodeBuddy
·Agent 框架：LangChain、CrewAI、AutoGen、Dify
·自研平台：任何支持"描述 + 脚本"模式的 Agent 系统
35、Q6：如何保障 Agent 调用的安全性？
建议从以下维度进行安全配置：
·最小权限：为 API 调用创建专用子账号，仅授予 QcloudDatabaseClawUserFullAccess 策略，避免过度授权。可结合 TencentDB Agent 用户角色体系，将 Agent 密钥绑定只读角色，仅允许诊断查询。
·审计追踪：保持 Session 创建开启（默认行为），确保所有 Agent 调用在控制台有记录。
·分级授权：TencentDB Agent 内置 L1-L4 分级授权，L4 高危操作需人工确认，30条永久性 Deny 规则拒绝不可逆破坏性操作。
·数据安全：TencentDB Agent 实例部署于用户 VPC 内网，数据不出域，传输采用 TLS 加密。注意 Agent 上下文可能包含查询结果中的业务数据，确保 Agent 平台的数据安全策略符合企业合规要求。