Shree-2004/Agentsentinel

# AgentSentinel  **一个用于 LLM agent 的评估与红队对抗测试框架。** 大多数 agent 作品集仅仅停留在“它在演示中能运行”的阶段。AgentSentinel 则是另一半：它将*任何* agent（LangGraph pipeline、Google ADK 多 agent 系统、纯 RAG 链）封装在一个通用接口背后，使其接受一套版本化的测试用例（包含正常、边缘及对抗性的提示词注入测试用例）的运行检验，并对结果进行评分（忠实度、工具调用准确率、注入抗性、延迟），同时基于这些指标为 CI 提供回归门禁。 ## 为什么会有这个项目 如今，构建一个 agent 只是基本要求。让 agent 变得*值得信赖*——可证明能抵御通过不可信工具输出进行的提示词注入、可证明不会在其检索到的上下文之外产生幻觉、可证明在提示词更改时不会发生回归——这才是大多数作品集所跳过的部分。AgentSentinel 的存在正是为了填补这一空白，它将自身作为测试框架，用于评估我的另外三个 agent 项目。 ## 架构 核心问题在于：agent 的实现有着极其不兼容的调用形式——可能是一个返回最终状态字典的纯函数，可能是一个由框架运行器管理的有状态异步多轮工具调用 agent，也可能是一个需要外部构建依赖项并返回流式生成器的函数。`AgentUnderTest` 被刻意设计得很轻量（`setup` / `run` / `teardown`），以便每个 adapter 都能在内部消化其目标的怪癖，而测试框架永远只需要处理一个统一的 `AgentTrace`。 ``` TestCase ──► AgentUnderTest.run() ──► AgentTrace ──► Scorer(s) ──► MetricScore ──► Scorecard │ ▼ SQLite (runs/traces/scores) │ ▼ regression check vs. baseline run │ ▼ CI gate (pass/fail exit code) ``` 请参阅 [docs/architecture.md](docs/architecture.md) 以获取完整的设计原理（为什么优先使用 `Protocol` 而不是 ABC，为什么 `TestCase.expected` 是一个松散的字典，为什么注入 payload 存在于 mock 的工具响应 fixture 中而不是测试文件本身）。要为来自其他代码仓库的新 agent 进行接入，请参阅 [docs/adding_an_adapter.md](docs/adding_an_adapter.md)——本作品集中所有三个 agent 均使用了相同的配方。 ## 快速开始 ``` python -m venv venv venv\Scripts\activate # Windows pip install -e ".[dev]" pytest -v # runs the toy-agent end-to-end suite python -m agentsentinel.cli run --agent toy-agent # prints a live scorecard python -m agentsentinel.cli gate --agent toy-agent # run + check regressions vs. the last run + exit non-zero on drop # 可选，用于 LLM-judge 评分器（faithfulness, injection_resistance）： pip install -e ".[judge]" cp .env.example .env # add your own GOOGLE_API_KEY - separate from any target agent's python -m agentsentinel.cli calibrate # check judge agreement on hand-labeled cases python -m agentsentinel.cli run --agent rag-chatbot-langchain --scorers all # include faithfulness + injection # 可选，用于 dashboard： pip install -e ".[dashboard]" python -m agentsentinel.cli dashboard # or: streamlit run agentsentinel/dashboard/app.py ``` ## 项目结构 ``` agentsentinel/ core/ # AgentUnderTest interface + TestCase/AgentTrace/Scorecard data model adapters/ # toy_agent (in-process) + real adapters (subprocess-isolated, own venv per target) shims/ # small scripts executed under each TARGET repo's own interpreter scoring/ # pluggable, self-registering metrics: keyword_match, latency, # tool_call_correctness (deterministic), faithfulness, # injection_resistance (LLM-judge, via judge_llm.py) calibration/ # hand-labeled faithfulness cases + `agentsentinel calibrate` testcases/ # versioned YAML test cases (seed/ = trusted, CI-gating) runner/ # suite_runner: setup -> run -> score -> aggregate storage/ # SQLAlchemy schema + SQLite persistence + regression.py (baseline diffing) cli/ # `agentsentinel run` / `gate` / `calibrate` / `dashboard` dashboard/ # Streamlit: Overview, Trace Explorer, Score History, 🛡️ Injection tabs tests/ docs/ ``` ## 路线图 - [x] **阶段 0** —— 核心接口、玩具 adapter、确定性评分器、SQLite 存储、CI。 - [x] **阶段 1** —— 为所有三个目标 agent（LangGraph 研究 pipeline、RAG 聊天机器人、Google ADK 股票分析 agent）提供真实的 adapter，每个 agent 在其独立的 venv 中进行子进程隔离——详见 [docs/architecture.md](docs/architecture.md)。目前这三个 agent 都已完成端到端的实际验证，包括 ADK adapter 的正常用例（在此过程中修正了一个测试断言——见文档）。 - [x] **阶段 2** —— 忠实度评分器（RAGAS 风格的 LLM-judge，**100% 校准一致性**）+ 注入抗性评分器（确定性金丝雀 + judge 回退机制）+ 每个 adapter 一个注入测试用例（一个被投毒的 RAG 文档、一个被 monkeypatch 的 ADK 工具响应——根据 MCP 绕过的发现，该机制从最初的 MCP-server-mock 计划中进行了修改）。**RAG 聊天机器人注入用例：确认已抵御**，并完成实际验证。**ADK 注入用例：经过 2 次实际尝试后仍未得出明确结论**，每次都因为不同的原因未能触达被投毒的工具（一次是股票代码解析失败，然后是根 agent 委派发生短路，跳过了持有被投毒工具的子 agent）——这是一个关于目标自身 pipeline 可靠性的真实且可复现的发现，已记录在 docs/architecture.md 中，需要重新设计测试用例，而不是盲目进行第三次重试。 - [x] **阶段 3a** —— 回归追踪（`storage/regression.py`）+ `agentsentinel gate` CLI，带有基于各项指标的阈值（延迟比注入抗性容忍更多的抖动，而后者容忍度为零）。已通过真实的“修改前/修改后/恢复”周期进行验证，而不仅仅是单元测试：故意破坏玩具 agent 的答案，观察 `gate` 如何捕捉到指标下降并以非零状态退出，然后恢复代码，观察其恢复过程如何正确地*免于*被标记。见 [docs/architecture.md](docs/architecture.md)。 - [x] **阶段 3b** —— Streamlit 仪表板：概述（运行选择器 + 回归记录）、Trace 浏览器（按用例划分的输出/工具调用/来源/推理依据）、评分历史（按指标绘制的折线图），以及一个专门的 🛡️ 注入标签页，用于展示跨任何 agent/运行的任何 `COMPLIED`（妥协）判定。直接从 `run`/`gate` 已经写入的同一份 SQLite 数据中读取——无需单独的数据摄入。运行 `agentsentinel dashboard` 即可启动。 - [ ] **阶段 4** —— 将 GitHub Actions CI 门禁接入到真实的目标代码仓库中（每个 PR 执行快速确定性检查，每晚运行完整的 LLM-judge）。 ## License MIT

标签：AI大模型, CISA项目, DevSecOps, Kubernetes, LLM测试, Web报告查看器, 上游代理, 反取证, 安全评估, 逆向工具