AgentOps Copilot

English

AgentOps Copilot 是一个面向微服务故障诊断的多 Agent RCA 系统。它从指标、 日志、链路和知识库中收集证据，生成根因报告，并保存完整的 Agent 与工具调用 审计记录。

系统组成

flowchart LR
    U[Incident] --> API
    API --> N[NATS JetStream]
    N --> W[Worker]
    W --> O[Orchestrator]
    O --> A[Agent fleet]
    A --> E[Evidence Board]
    E --> D[Diagnosis Scheduler / Planner]
    D -. optional focused verification .-> A
    D --> S[Synthesizer]
    S --> R[Root Cause Report]
    O --> P[(PostgreSQL audit)]
    O --> SSE[SSE events]

架构演示

Agent 编排与通信动画演示 用一次 incident 的完整流程模拟了 Orchestrator 如何并行调度 specialist、证据如何经 EvidenceBoard 交换、Scheduler 状态机如何做有界交叉求证与最终综合。 本地运行 make presentation 后访问 http://127.0.0.1:4174/architecture.html，或直接打开该文件 （单文件、无外部依赖）。

数据源边界

生产诊断和 benchmark 复用同一套 Agent 与 Orchestrator，但数据面、持久化 查询和前端入口相互隔离。

运行模式由顶层装配显式选择。benchmark 的期望服务、注入信息、标签和评分结果 不会进入 Agent prompt 或工具。API 默认不允许启动新的 benchmark Collection； 需要时必须显式设置 BENCHMARK_EXECUTION_ENABLED=true。

完整的分层、依赖方向和扩展位置见 架构与代码导航。

快速开始

前置条件

• Go 1.26.4+
• Docker Compose
• OpenAI-compatible LLM endpoint
• Node.js 20+、pnpm 和 jq（运行前端时需要）

图片或 PDF 文档入库还需要独立部署的 OvisOCR2 endpoint；纯文本来源不需要 OCR。详见 RAG 数据源接入。

1. 配置

cp .env.example .env

填写 LLM_API_KEY，并按需调整 endpoint 与模型：

LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your-api-key
LLM_MODEL=gpt-4o-mini
RAG_BACKEND=milvus # milvus | openviking | disabled

.env 不应提交到 Git。

2. 启动依赖

make docker-up

等待 docker compose ps 中的依赖就绪，再初始化存储：

make migrate-pg
make graph-load-schema
make prepare-embedding
make knowledge-ingest REDCART_ROOT=/path/to/redcart

RAG_BACKEND=milvus 是兼容默认值；OpenViking 服务端固定兼容版本为 v0.3.16，其独立启动、鉴权和切换步骤见 RAG 数据源接入。

默认端口：

3. 启动 API 和 Worker

在两个终端中分别运行：

make run

make worker

验证进程和依赖：

curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/readyz
curl -fsS http://127.0.0.1:9092/readyz

/healthz 只表示进程存活；/readyz 会检查运行所需依赖。

4. 启动前端

API_TOKEN="$(curl -fsS -X POST http://127.0.0.1:8080/api/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"subject":"web-dev"}' | jq -r .token)"

cd web
pnpm install --frozen-lockfile
VITE_API_TOKEN="$API_TOKEN" pnpm dev

前端默认只访问真实 /api。mock 仅在构建或启动时显式设置 VITE_USE_MOCK=1 后可用，并会显示可见标识。

容器化 API/Worker、鉴权和端到端 smoke 流程见 部署与验收。

Benchmark

项目使用固定 revision 的 anon-ops/ops-lite 数据集。Observed telemetry 可进入 Agent；injection.json、 causal_graph.json、result.json 和标签仅用于导入、评分与人工复核。

python3 -m pip install 'huggingface_hub>=1,<2'
make fetch-openrca
make migrate-openrca
make benchmark-import
GIT_COMMIT_SHA="$(git rev-parse HEAD)" make benchmark-run

评测结果会关联数据集、模型、prompt revision、commit 和 incident 审计记录。 单个 case 或未完成 Collection 不代表完整套件表现。历史结果与口径见 OpenRCA benchmark 演进。

目录

开发时先记三个入口：

• 每个专家实例、工具 schema 和 handler 同目录放在 internal/agent/experts/{metrics,logs,traces,experience}/； internal/agent/einobridge/ 只负责 Eino 协议适配。评测 case 专用工具隔离在 benchmark/tools/。
• internal/agent/flow/workflow.go 只定义 policy graph；角色名、激活条件和工具 白名单由各专家目录自持。首轮后的路由和可选交叉求证由 scheduler.go / scheduler_state.go 中央控制。
• 进程启动和关闭在 internal/process/，具体依赖选择与组装在 internal/composition/；两者不混放。

cmd/             API、Worker 与生产运维 CLI
benchmark/       独立评测 CLI、case 分析、工具、执行、评分与存储
internal/process/  API、Worker 生命周期
internal/composition/
                  模型、Agent、工具和运行时依赖组装
internal/agent/   experts、einobridge、flow、audit、memory 与 modelcall
internal/transport/
                  HTTP API、SSE 与 NATS task queue
internal/persistence/
                  持久化 record、PostgreSQL/Redis 客户端与 repository
internal/knowledge/
                  检索契约、Milvus、OpenViking、GraphRAG 与文档加载
internal/telemetry/
                  故障指标、日志与链路读取协议
internal/observability/
                  应用自身日志与运行指标
web/             React 运维看板
presentation/    独立项目讲解页
migrations/      PostgreSQL 与 Neo4j schema
openspec/        当前规格与变更归档
docs/            架构、部署、评测和项目说明

根目录中的产品源码只有 cmd/、internal/、benchmark/、web/ 和 presentation/。deploy/、migrations/、scripts/、docs/、 openspec/ 是工程支撑；.codegraph/、.runtime/、.giter/ 以及各类 .codex/、.claude/、.kimi/ 等隐藏目录是对应工具按仓库根目录发现的 本地状态或索引，不属于业务分层，且已通过 ignore 规则与产物隔离。

验证

make check

该命令检查 Go 格式、module 漂移、vet、测试、全包构建和单文件 400 行限制。

前端修改还需运行：

cd web
pnpm lint
VITE_USE_MOCK=0 pnpm verify:production

文档

• 文档索引
• 架构与代码导航
• 部署与验收
• RAG 数据源接入
• 已知问题
• 项目讲解
• 架构演示

工程约束

• 默认使用真实 API 和真实数据源，不静默回退到 mock。
• Production 与 benchmark 数据源不得混用。
• 不通过修改测试、健康检查或评分条件掩盖缺陷。
• 不提交密钥、日志、二进制、完整数据集或本地 Agent 元数据。
• 行为变更需要聚焦测试；运行链路变更需要真实 smoke 证据。

贡献

欢迎提交 Issue 和 Pull Request。提交前请运行上述后端与前端验证命令。

License

项目代码采用 MIT License。第三方组件与数据集遵循各自许可证； OPS-Lite 数据集采用 Apache-2.0。