SujalXplores/Agent-K

每一个主张都有证据支撑。每一步操作都受代码门控。
不盲目信任模型。一切皆在遥测数据中证明。

Agent K 是一个**代码强制事件响应 Agent**，专为 FastAPI RAG 支持问答服务设计。当 SigNoz 告警触发时，Agent K 会通过 SigNoz MCP server 调查故障原因，仅发布有证据支撑的根本原因主张，仅在代码策略 允许时执行沙盒回滚，并将其自身的开销和行为记录为遥测数据，因此 每一个决策都可在 SigNoz 中审计。 为 **Agents of SigNoz 黑客松** (WeMakeDevs x SigNoz)， 赛道 01：AI 与 Agent 可观测性（2026年7月20日至26日）而构建。 ## 为什么选择 Agent K AI 应用的故障方式往往不同寻常：缓慢、昂贵、不准确，或者 陷入重试循环，但不会产生常规的服务端错误。工程师 通常需要仔细排查 trace、metrics、logs 和部署历史才能 了解到底发生了什么，而进行调查的 AI Agent 自身也可能会 做出毫无根据的猜测或采取不安全的操作。 Agent K 让每一次调查都变得**可追溯**，每一个结论都 **可验证**，每一步操作都**受代码控制**。 | 没有 Agent K 时的问题 | Agent K 如何应对 | | --- | --- | | Agent 对根本原因进行毫无根据的猜测 | 法则 1 会剥离任何没有可解析 SigNoz 证据链接的主张 | | Agent 推荐了模型自认为没问题的操作 | 法则 2 会在任何操作执行前运行基于代码的策略门控 | | Agent 静默运行，开销失控，无限循环 | 法则 3 会将每一次调用、token、查询和判定记录为一个 span | ## 三大法则（由软件强制执行，而非提示词） | 法则 | 规则 | 预防的问题 | | --- | --- | --- | | **法则 1** 无证据不主张 | 除非附带可解析的 SigNoz 证据链接（trace、log、metric 或部署记录），否则不得发布根本原因主张。报告渲染器会剥离任何证据列表为空的主张。 | 毫无根据的断言进入报告 | | **法则 2** 无预算不操作 | 在执行任何操作前，基于代码的策略会检查 SLO 和消耗率违规、允许列表成员资格、冷却时间、置信度阈值、是否与部署相关的原因以及沙盒范围。允许列表中仅包含一项操作：回滚到上一个版本。 | 模型仅凭自身建议执行运维操作 | | **法则 3** 无遥测不自身 | Agent K 对自身的观察与应用同等严格：每一次 LLM 调用、token 计数、开销、持续时间、MCP 查询、假设和策略判定都会成为一个 span。循环断路器会停止重复的 MCP 查询。开销监视器会停止超预算的调查。 | 静默的 Agent 行为和失控的开销 | ## 工作原理 ``` flowchart TD A[SigNoz alert fires] --> B[Agent K receives alert] B --> C[Collect traces, metrics, logs via SigNoz MCP] C --> D[Investigate with fixed query set] D --> E[Form root cause hypotheses] E --> F[Attach SigNoz evidence to each claim] F --> G{Law 2 policy gate} G -->|All checks pass| H[Execute sandboxed rollback] G -->|Any check fails| I[Evidence linked escalation to human] H --> J[Run verification query] J --> K[Produce auditable incident report] I --> K K --> L[Record own cost, queries, decisions as telemetry] L --> M[Investigation complete] classDef law fill:#1a1a2e,stroke:#e94560,color:#fff classDef safe fill:#0f3460,stroke:#00b894,color:#fff classDef deny fill:#2d0a0a,stroke:#e17055,color:#fff classDef done fill:#16213e,stroke:#0fbcf9,color:#fff class G law class H safe class I deny class M done ``` ## 仓库包含内容 | 路径 | 用途 | | --- | --- | | `app/` | FastAPI RAG 支持服务（被监控的应用） | | `app/main.py` | 路由及 OTel 装配 | | `app/rag.py` | 检索与基于事实的 prompt 构建 | | `app/llm.py` | 单个 OpenAI 兼容客户端 (Groq, Cerebras, Gemini) | | `app/embeddings.py` | 本地 sentence transformers embeddings | | `app/db.py` | 异步 SQLAlchemy 及 pgvector session 设置 | | `app/models.py` | 带有 pgvector embedding 列的文档模型 | | `app/schemas.py` | Pydantic 请求与响应模型 | | `app/telemetry.py` | OTel provider (traces, metrics, logs, OTLP HTTP) | | `app/observability.py` | 共享的 gen_ai span 属性辅助工具 | | `data/corpus/` | 72 份合成支持文档 (Flowdeck，虚构的 SaaS) | | `alembic/` | DB 迁移 (0001: documents 表及 vector 扩展) | | `scripts/seed_corpus.py` | 幂等语料库填充工具 | | `scripts/probe_ask_spans.py` | 针对生产环境 POST /ask 的 span 数量探针 | | `scripts/time-foundry-cast.sh` | Foundry 重建耗时记录器 (TELE 02) | | `tests/` | 离线单元测试及实时数据库集成测试 | | `casting.yaml` | SigNoz Foundry 部署清单 | | `casting.yaml.lock` | 可复现的 Foundry lockfile (评审交付物) | | `docker-compose.yaml` | rag postgres (pgvector/pgvector:pg16) 容器 | | `SIGNOZ-RUNBOOK.md` | 逐步搭建 SigNoz 及首次运行设置说明 | | `TELEMETRY-REBUILD-LOG.md` | 仅追加的 Foundry 重建耗时日志 | | `landing/` | 静态 Next.js 营销网站 (独立项目，部署至 Vercel) | ## 被监控的应用 一个 **FastAPI RAG 支持问答服务**，包含： | 层级 | 选型 | 原因 | | --- | --- | --- | | Datastore | PostgreSQL 16 及 pgvector | 单一数据存储用于文档和向量，无需独立的向量 DB | | Embeddings | sentence transformers `all-MiniLM-L6-v2` (384 维，本地) | 零预算，无需外部 embedding API | | LLM client | openai SDK，支持可替换的 `base_url` | 通过环境变量，一个客户端即可用于 Groq, Cerebras, Gemini Flash | | Observability | OpenTelemetry 1.44.0，通过 OTLP HTTP 发送至 SigNoz | Traces, metrics, logs，GenAI semconv 属性，免费的 DB span | ## 四大演示事件 每个事件都通过特性开关或配置更改进行刻意植入，并作为 受控测试故障予以披露。 | # | 事件 | 植入方式 | 预期判定 | | --- | --- | --- | --- | | 1 | Prompt 回退部署 | v2 中损坏的 prompt 模板 | 允许回滚 | | 2 | 重试风暴导致开销失控 | 降低超时时间导致重复 LLM 调用 | 允许回滚 (仅基于开销 SLO) | | 3 | 检索延迟注入 | 人为的 pgvector 延迟 | 拒绝回滚 (非部署引起) | | 4 | 数据库连接池耗尽 | DB 连接数过少 | 拒绝回滚 (不支持的故障类型) | ## 快速开始 ### 前置条件 | 要求 | 版本 | 备注 | | --- | --- | --- | | Python | 3.11 或 3.12 | 避免 3.13，部分 OTel contrib 包滞后 | | Docker | Desktop 或 Engine 及 Compose v2 | 需 6 至 8 GB 内存供 SigNoz 使用 | | LLM API key | Groq, Cerebras 或 Gemini (免费层) | 任选其一，默认为 Groq | ### 1. 通过 Foundry 启动 SigNoz ``` curl -fsSL https://signoz.io/foundry.sh | bash # install foundryctl (once) foundryctl gauge -f casting.yaml # validate prerequisites foundryctl forge -f casting.yaml -p ./pours # generate compose plus lockfile foundryctl cast -f casting.yaml # full pipeline: gauge + forge + up ``` 确认服务栈已启动，然后完成必需的首次运行设置。请参阅 [`SIGNOZ-RUNBOOK.md`](SIGNOZ-RUNBOOK.md) 获取详细步骤，包括 绑定 OTLP receiver 的首次运行组织和注册步骤。 ### 2. 启动 RAG 服务数据存储 ``` docker compose up -d # rag postgres (pgvector/pgvector:pg16) ``` ### 3. 配置环境 ``` cp .env.example .env # 填写 GROQ_API_KEY（和/或 CEREBRAS_API_KEY / GEMINI_API_KEY） ``` ### 4. 安装、迁移、填充、运行 ``` python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt alembic upgrade head # create documents table plus vector extension python -m scripts.seed_corpus # embed and upsert the 72 doc corpus uvicorn app.main:app --reload # http://localhost:8000 ``` 冒烟测试： ``` curl localhost:8000/healthz # {"status":"ok"} curl -X POST localhost:8000/ask \ -H "Content-Type: application/json" \ -d '{"question":"How do I rotate my API key?"}' ``` ## 测试 | 命令 | 作用 | | --- | --- | | `pytest` | 离线单元测试 (mock，无 DB，无网络) | | `pytest -m integration` | 实时数据库测试 (需要 rag postgres 容器) | | `python scripts/probe_ask_spans.py out.json` | 在全新进程中测量真实的 /ask span 集 | ## 使用的 SigNoz 功能 | 功能 | 体现位置 | | --- | --- | | OpenTelemetry traces | 每个 /ask 请求、检索、prompt 和 LLM 调用 | | OpenTelemetry metrics | 请求率、错误率、延迟、SLO、消耗率 | | 结构化日志 | 通过 LoggingInstrumentor 实现与 trace 关联的日志记录 | | GenAI 语义约定 | 每次模型调用上的 gen_ai.* 属性 | | SigNoz dashboards | 一个看板，四个部分 (服务、事件、Agent、审计) | | SigNoz alerts | 独立于看板单独配置 | | Query Builder | Agent K 用于执行调查查询 | | SigNoz MCP server | Agent K 用于收集所有证据的客户端 | | Trace 到 log 的关联 | 从故障到 Agent 推理过程的一键关联 | | Trace 与 span 链接 | 调查 span 指向回事件 trace | | 部署标记 | 标记每个版本，供法则 2 原因检查使用 | | Foundry 部署 | 提交了 `casting.yaml` 及 `casting.yaml.lock` | ## 技术栈 | 层级 | 选型 | 版本 | | --- | --- | --- | | Runtime | Python | 3.11 或 3.12 | | Web framework | FastAPI 及 Uvicorn | 0.139.2 / 0.51.0 | | Datastore | PostgreSQL 及 pgvector | 16 / 0.5.0 | | ORM 及驱动 | SQLAlchemy 及 asyncpg | 2.0.51 / 0.31.0 | | Migrations | Alembic | 1.18.5 | | Embeddings | sentence transformers | 5.6.0 | | LLM client | openai SDK | 2.46.0 | | Observability | OpenTelemetry | 1.44.0 | | OTLP 导出 | opentelemetry exporter otlp proto http | 1.44.0 | | SigNoz 安装 | Foundry | foundryctl cast | ## AI 辅助披露 本项目构建过程中使用了 AI 编码辅助工具（Claude Code, GitHub Copilot），根据黑客松规则在此披露。所有工作均由人工审查 和指导。所有产品声明均基于项目规划文档，演示结果均诚实地描述为在四个受控场景下取得了四分之四的成绩，而非普遍的生产环境准确率。 ## 许可证 MIT。有关全文，请参阅 [`LICENSE`](LICENSE)。 ## 贡献 有关如何设置、运行测试和提交更改的信息，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。

标签：API集成, AV绕过, FastAPI, RAG, SigNoz, 可观测性, 测试用例, 用户代理, 自动化应急响应, 请求拦截, 运维, 逆向工具