trilagi/veritas

# Veritas 基于 AI 驱动的事件响应和根因分析 (RCA) 流水线，使用 Google ADK 在 GCP 上构建。编排流程包括：分诊 → 诊断 → 沙箱化修复 → HITL Slack 审批 → 复盘。 ## 演示 📹 [观看演示视频](https://youtu.be/LnPfeONL_xo) ## 架构 📄 [架构图 (PDF)](docs/architecture/architecture-diagram.pdf) 该系统由一个 **Conductor** 组成，它通过 ADK 的 `SequenceAgent` 和 `ParallelAgent` 模式编排多个专门的子代理： | 代理 | 角色 | |---|---| | **Triage** | 对传入的事件进行分类，确定严重程度和范围 | | **Diagnostician** | 在受影响的 GCE 实例上运行只读 SSH 诊断 | | **Remediator** | 在隔离的 GCE 沙箱克隆中提出并应用修复方案 | | **Prod Applier** | 在 HITL 签核后将批准的修复应用于生产环境 | | **Scribe (Approval)** | 编写包含完整事件上下文的 Slack 审批请求 | | **Scribe (Postmortem)** | 生成结构化的复盘文档 | 所有代理均由通过 ADK `LlmAgent` 抽象支持的 **Gemini** 提供支持。代理 prompt 通过 **Langfuse** 进行版本控制和同步。 ### 使用的技术 - **智能：** Gemini（通过 Google ADK `LlmAgent`） - **编排：** [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) — `SequenceAgent`、`ParallelAgent`、`FunctionNode` - **基础设施：** Google Cloud Run (FastAPI)、Google Compute Engine（沙箱克隆生命周期） - **HITL：** Slack Bolt — 审批门控会阻塞流水线，直到人工签核 - **可观测性：** Langfuse（prompt 版本控制、trace 日志记录）、Cloud SQL (PostgreSQL) - **MCP：** SSH MCP Server — 代理通过 Model Context Protocol 连接到 GCE 实例 - **其他：** Docker、uv、ngrok（本地 HITL 测试） ### 关键设计决策 - **沙箱化修复：** 在任何修复触及生产环境之前，Remediator 会在实时的 GCE 磁盘克隆上运行 — 幻觉命令的爆炸半径为零 - **HITL 门控：** 没有待命工程师明确的 Slack 审批，任何更改都不会进入生产环境 - **Prompt 即代码：** 所有代理系统 prompt 都位于 `configs/prompts/` 中，并在启动时同步到 Langfuse，无需重新部署即可实现 prompt 版本控制 ## 设置 ### 1. 在本地运行 Langfuse 应用程序在启动时会推送 trace 并将 prompt 版本同步到 Langfuse。最简单的方法是使用自托管的 docker-compose 堆栈 — 完整说明请参见 ，简写如下： ``` git clone https://github.com/langfuse/langfuse.git cd langfuse docker compose up ``` 打开 ，创建一个项目，并从 *Settings → API Keys* 中获取 **public key**、**secret key** 和 base URL。 ### 2. 安装 Google Cloud CLI 根据您的平台遵循 进行操作，然后对 Application Default Credentials 进行身份验证（这与 `gcloud auth login` *分开* — ADK SDK 特别需要 ADC）： ``` gcloud auth application-default login ``` ### 3. 配置环境 ``` cp .env.example .env # 编辑 .env：填写 GCP project、Langfuse keys 等。 ``` ### 4. 安装 Python 依赖项 ``` uv sync ``` ## 运行 ### FastAPI 服务器（推荐 — Slack 集成必需） ``` uv run uvicorn src.main:create_app --factory --reload --port 8080 ``` ADK HTTP 端点位于 `http://localhost:8080`（通过 `src/adk_app_factory.py` 中的 `create_adk_fastapi_app`）。示例请求 — 首次命中时会自动创建会话： ``` curl -X POST http://localhost:8080/run \ -H "Content-Type: application/json" \ -d '{ "user_id": "test-user", "new_message": { "role": "user", "parts": [{ "text": "Hello! Who are you?" }] } }' ``` 如需完整的 HITL 流水线（Slack 审批），还需要运行 ngrok 并配置 Slack 应用程序 — 参见 [`docs/local-test-scribe-pr.md`](docs/local-test-scribe-pr.md)。 ### ADK Web UI（无 Slack） 从仓库根目录开始： ``` adk web . ``` 打开它打印出的 URL；Veritas Workflow 通过 `src/agent.py` 暴露。 ## 发现与学习 - **ADK `FunctionNode` 功能强大但不透明** — 调试停滞的流水线需要围绕每个节点添加显式的 Langfuse span；如果没有 trace，很难看出代理卡在哪里 - **GCE 磁盘克隆延迟** 是修复循环中的瓶颈（典型的 LAMP 堆栈磁盘约为 90 秒）；我们通过在诊断期间以推测方式触发克隆创建来缓解此问题 - **使用 ADK 进行 Slack 异步恢复** 需要仔细的会话状态管理 — 审批回调在没有共享内存的单独 HTTP 请求上到达，因此在门控阻塞之前，必须将所有上下文持久化到 Cloud SQL - **通过 Langfuse 进行 prompt 版本控制** 证明是必不可少的 — Triage 和 Diagnostician prompt 的早期迭代产生了不一致的 JSON 工具调用；能够将 prompt 版本与 trace 结果进行 diff 显著加快了迭代速度 ## 许可证 该项目采用 [Business Source License 1.1](LICENSE) 授权。商业用途受限 — 详情请参阅 LICENSE 文件。 ## 关于 由 [Trilagi Sp. z o.o.](https://trilagi.com) 为 Google for Startups AI Agents Challenge 2026 构建。

标签：GCP, Google ADK, 人工智能运维, 多智能体, 根因分析, 模块化设计, 自动化修复, 请求拦截, 逆向工具