Xata Agent，您的 PostgreSQL 领域 AI 专家

Xata Agent 是一款开源代理工具，可监控您的数据库、查找问题根源，并提出修复与优化建议。它就像为您的团队新聘请了一位经验丰富的 PostgreSQL SRE 专家。

让代理自我介绍：

请雇佣我作为您的 PostgreSQL AI 专家。我可以：

• 监控日志和指标，及时发现潜在问题。
• 主动为您推荐数据库实例的配置调优方案。
• 排查性能问题并提供索引优化建议。
• 解决常见问题，如 CPU 使用率过高、内存占用过大、连接数过多等。
• 帮助您执行 VACUUM 操作（针对您的 Postgres 数据库，而非您的房间）。

关于我的更多信息：

• 我是开源且可扩展的。
• 可通过 Cloudwatch 监控 RDS 和 Aurora 的日志与指标。
• 我仅使用预设的 SQL 命令，绝不会对您的数据库执行任何破坏性（甚至潜在破坏性）操作。
• 我采用一系列工具和 playbook 来指导自身行动，避免产生幻觉。
• 我可以运行诊断语句，例如查询 pg_stat_statements、pg_locks 等，以定位问题根源。
• 如果出现异常情况，我会通过 Slack 向您发送通知。
• 我支持 OpenAI、Anthropic 和 Deepseek 提供的多种模型。

过往经验：

• 我一直协助 Xata 团队监控和运维大量活跃的 Postgres 数据库。

演示

以下是一个不到 4 分钟的代理实际运行演示：

https://github.com/user-attachments/assets/78f58598-c1c4-4a50-b9c5-402e912c1d8a

该演示的 YouTube 版本也可在此观看：点击这里。

安装 / 自托管

我们提供了代理本身的 Docker 镜像。其唯一依赖项是一个 Postgres 数据库，代理将在此存储其配置、状态和历史记录。

我们还提供了一个 docker-compose 文件，用于同时启动代理和 Postgres 数据库。

编辑项目根目录下的 .env.production 文件。您需要设置 PUBLIC_URL 以及至少一个 OpenAI 的 API 密钥。

通过 docker compose 启动本地实例：

docker compose up

打开应用页面 http://localhost:8080（或您在 .env.production 文件中设置的公共 URL），按照引导步骤完成初始化。

我们还提供了一份更详细的 指南，介绍如何通过 docker-compose 在 EC2 实例上部署。

对于身份验证，您可以使用自己的 OAuth 提供商。

开发

进入 apps/dbagent 目录，并按照 README 中的说明进行操作。

扩展性

代理可通过以下机制进行扩展：

• 工具：这些是代理可用于获取数据库相关信息的函数。它们使用 TypeScript 编写，具体描述请参见此 文件。
• Playbook：这些是代理为解决问题而遵循的一系列步骤。它们以英文简单编写。预定义的 playbook 位于 此处。
• 集成：例如 AWS 和 Slack 集成。它们包含配置和 UI 组件。

当前状态 / 路线图

尽管目前仍处于早期阶段，但我们已在 Xata 的日常运维工作中使用该代理。

• Playbook：
  • [√] 通用监控
  • [√] 调优设置
  • [√] 调查慢查询
  • [√] 调查高 CPU 使用情况
  • [√] 调查高内存使用情况
  • [√] 调查高连接数
  • 调查锁问题
  • 调查 VACUUM 操作
  • [√] 支持自定义 playbook
  • 其他 playbook（欢迎提供建议）
• MCP 集成：
  • 作为其他代理的 MCP 服务器
  • 通过 MCP 网络调用工具
• 更多云服务商支持：
  • [√] AWS RDS
  • [√] AWS Aurora
  • [√] Google Cloud SQL
  • Azure Database for PostgreSQL
  • Digital Ocean Managed Databases
  • 其他（欢迎提供建议）
• 通知与集成：
  • [√] 简单的 Slack 集成
  • 作为 AI 代理的 Slack 集成（https://github.com/xataio/agent/pull/29）
  • Discord 集成
  • 其他（欢迎提供建议）
• 评估与测试：
  • [√] 增加针对与 LLM 交互的评估测试
• 审批流程：
  • 为代理添加审批流程，以控制其执行潜在危险语句
  • 允许根据不同的监控计划配置可用工具

虽然该代理本质上是一款您可自行托管的开源项目，但我们也正在开发云端版本。云端版本的优势在于部分集成更为便捷。如果您对云端版本感兴趣，请在此 加入候补名单。

Xata Agent 快速上手指南

Xata Agent 是一款开源的 AI PostgreSQL 专家助手，能够监控数据库日志与指标，主动发现性能瓶颈（如高 CPU、高内存、慢查询），并提供配置调优和索引建议。它像一位经验丰富的 SRE 工程师，7x24 小时守护你的数据库。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需安装 Docker Desktop)
• 核心依赖：
  • Docker 及 Docker Compose
  • Git
• API 密钥：至少需要一个 LLM 提供商的 API Key（支持 OpenAI, Anthropic, Deepseek 等）。
• 数据库：无需额外准备，启动脚本会自动创建一个本地 PostgreSQL 用于存储 Agent 的状态和历史记录。
• 网络提示：由于需要拉取 Docker 镜像和连接大模型 API，国内用户建议配置好 Docker 镜像加速器，并确保能正常访问所选 LLM 的服务接口。

安装步骤

本项目推荐使用 Docker Compose 进行一键部署。

1. 克隆项目代码

   git clone https://github.com/xataio/agent.git
   cd agent
   

2. 配置环境变量 复制生产环境配置文件模板，并编辑关键参数：

   cp .env.production.example .env.production
   # 使用你喜欢的编辑器打开 .env.production
   

   在 .env.production 文件中，务必修改以下两项：

   • PUBLIC_URL: 设置为你访问服务的地址（本地测试可设为 http://localhost:8080）。
   • OPENAI_API_KEY (或其他模型 Key): 填入你的大模型 API 密钥。

3. 启动服务 运行以下命令启动 Agent 及其依赖的数据库：

   docker compose up
   

   首次运行时，Docker 会自动下载相关镜像并初始化数据库，可能需要几分钟时间。

基本使用

服务启动成功后，即可通过浏览器访问并进行初始化配置。

1. 访问界面 打开浏览器访问：

   http://localhost:8080
   

   (如果你在 .env.production 中配置了其他 PUBLIC_URL，请访问该地址)

2. 完成引导 (Onboarding) 跟随网页上的引导步骤，连接你需要监控的目标 PostgreSQL 数据库。

   • 支持连接 AWS RDS, AWS Aurora, Google Cloud SQL 以及自建的 PostgreSQL 实例。
   • 配置完成后，Agent 将开始自动监控日志和指标。

3. 开始诊断 你可以在界面中查看 Agent 发现的潜在问题，或手动触发排查任务。例如：

   • 监控告警：当检测到高 CPU 或高连接数时，Agent 会自动分析原因。
   • 性能调优：询问 Agent 关于慢查询的建议，它会检查 pg_stat_statements 并提供索引优化方案。
   • 日常维护：让 Agent 协助分析 Vacuum 状态或锁等待情况。

   安全提示：Xata Agent 默认仅执行预设的安全 SQL 命令进行诊断，绝不会对你的数据库执行破坏性操作。