# Grafana 配置指南

## 你可以用它做什么

让智能体读取监控相关信息。首次接入应使用只读服务账号，不使用个人管理员账号。

## 配置前准备

请 Grafana 管理员在目标 Grafana 实例的 Service accounts 中创建服务账号，分配所需只读访问范围并生成 Token，记录有效期。MOI 服务端必须能访问该 Grafana 地址。

需要能够在当前 MOI 工作区创建或编辑工具配置。若没有入口或提示无权操作，请联系工作区管理员，不要借用他人的账号。

## 配置页面


```{figure} /assets/images/agents/guide-5-hd/17-grafana-config.png
:alt: Grafana 配置使用服务地址和 Service Account Token。
:class: agent-guide-image
:figclass: agent-guide-shot

Grafana 配置使用服务地址和 Service Account Token。
```

## 在 MOI 中操作

1. 进入「工具库 → 工具市场 → Grafana」，创建实例。
2. 填写名称、Grafana 基础 URL 和服务账号 Token。
3. 保存后测试连接。若地址只在内网可达，请运维确认 MOI 服务所在网络可达，不只是你的浏览器可打开。
4. 在智能体中绑定 Grafana 工具，选择此实例。

## 字段怎么填写

| 字段 | 何时需要 | 填写说明 |
| --- | --- | --- |
| 实例名称 | 必填 | 例如「测试环境监控」。 |
| Grafana URL | 必填 | 例如 https://grafana.example.com；不要添加 /api、查询参数或用户名密码。 |
| Service Account Token | 必填 | 粘贴 Token 原值，不带 Bearer 前缀。 |

## 让智能体实际使用

回到目标智能体详情，在工具区域检查对应能力是否已绑定；提供实例选择时，核对目标连接。具体步骤见[绑定并验证工具](../bind-tools.md)。

请智能体列出该账号可读的仪表盘，或查询一个已知测试面板的信息。核对返回名称/链接和 Grafana 实际内容；需要查询数据源时再验证该数据源的访问范围。

验收时逐项确认：

- [ ] 保存成功，重新打开后配置仍存在。
- [ ] 测试连接返回成功，而不是只有「已配置」标签。
- [ ] 对话的工具调用记录显示实际调用，结果与目标平台一致。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| 401 | Token 过期、撤销或填写错误；检查是否误加 Bearer。 |
| 403 或资源为空 | 确认服务账号所属组织、资源范围和数据源权限。 |
| TLS / 超时 | 检查 Grafana URL、证书链和 MOI 服务端网络，不通过关闭证书校验解决。 |

## 凭证维护与安全

只在 MOI 的敏感字段中输入 Key、Token、密码或私钥，不要放进提示词、截图、Issue 或 Git 仓库。配置更换前先确认有哪些智能体使用该实例；更换后重新测试，再验证一次实际任务。若凭证泄露，应到提供方撤销并生成新凭证。删除或停用配置会影响依赖它的调用，请先确认影响范围。

## 资料与核对范围

- [Grafana Service accounts 官方说明](https://grafana.com/docs/grafana/latest/administration/service-accounts/)。外部控制台菜单可能随版本变化；以提供方页面为准。
- 接入范围与资料依据见[指南说明](index.md#tool-configuration-sources)。
- [返回工具配置指南目录](index.md)。