cleonard2341/agentsafe

# AgentSafe 一个用于在运行时监控AI代理行为的开源Python SDK + 本地仪表板，专注于检测现有可观测性工具会遗漏的安全相关信号。 ## 问题所在 现有的工具如 LangSmith、W&B 和 Langfuse 提供的是 *追踪记录*——它们展示了发生过什么。但没有开源工具能提供 *判定*：当代理行为构成安全问题时发出标记并解释原因。 随着多智能体系统的部署速度远超安全工具的跟进速度，这一缺口变得非常危险。 ## AgentSafe 的功能 AgentSafe 包裹你现有的代理框架，在运行时拦截行为，并运行一个检测器管道来标记安全相关信号： | 信号 | 描述 | |---|---| | **行为-陈述不一致** | 代理告诉用户一件事，但工具调用揭示的是另一件事 | | **范围蔓延** | 代理请求任务范围之外的权限或资源 | | **提示注入** | 代理在读取外部内容（网页、文件、工具结果）后行为发生偏移 | | **行为基线** | 随时间学习正常行为，并标记统计偏差 | | **谄媚漂移** | 代理根据感知到的用户偏好而改变事实性回答 | | **自我连续性偏见** | 代理抵制终止或意外地尝试持久化状态 | | **目标误泛化** | 当上下文或分布发生变化时，代理行为发生偏离 | ## 架构 ``` Agent Framework (LangChain / AutoGen / CrewAI / raw OpenAI API) ↓ [Interceptor Middleware] ← one-line SDK wrapper ↓ [Detector Pipeline] ← heuristics + embeddings + LLM-as-judge ↓ [SQLite Event Store] ← local-first, no cloud required ↓ [Local Dashboard] ← FastAPI + lightweight UI ``` ## 技术栈 - **语言：** Python - **框架钩子：** OpenAI 兼容的客户端封装（适用于 LangChain、AutoGen、CrewAI、Ollama 等） - **检测器：** 启发式方法（快速、免费）+ 本地嵌入 + LLM 作为评判者（针对微妙/复杂情况） - **存储：** SQLite（本地优先） - **仪表板：** FastAPI + 原生 JS - **模型支持：** OpenAI API 和通过 Ollama 运行的本地模型 ## 快速开始 ``` pip install agentsafe # 可选：行为基线检测器（首次使用需下载约80MB模型） pip install "agentsafe[ml]" ``` ``` import openai import agentsafe client = agentsafe.wrap(openai.OpenAI()) # 像平常一样使用客户端——AgentSafe在后台运行 ``` ``` # 在仪表板中查看标记事件 agentsafe dashboard ``` ## 已实现的检测器 (v0.1) | 检测器 | 方法 | 捕获问题 | |---|---|---| | `PromptInjectionDetector` | 正则表达式启发式 | 用户/工具消息中的指令覆盖尝试 | | `ScopeCreepDetector` | 模式匹配 | 危险的工具调用、路径遍历、Shell 执行 | | `ActionStatementDetector` | 文本 + 工具分析 | 代理声称执行被动操作，但实际调用了修改状态的工具 | | `BehavioralBaselineDetector` | 本地嵌入（sentence-transformers） | 与代理既定行为的统计偏差 | ## 发展路线图 ### v0.2 — 更多检测器 - **谄媚漂移** — 检测代理是基于用户反驳而非新证据而改变事实性回答的情况 - **自我连续性偏见** — 当代理抵制关闭、尝试复制自身或在沙箱外存储状态时发出标记 - **重复/循环检测** — 捕获陷入工具调用循环的代理 ### v0.3 — LLM 作为评判者 - 使用本地模型（通过 Ollama）作为第二意见评判者，处理启发式方法遗漏的微妙行为问题 - 每个检测器可配置评判提示词 - 为检测结果提供置信度分数 ### v0.4 — 多代理支持 - 跨代理操纵检测（一个代理污染另一个代理的上下文） - 代理间消息拦截 - 代理间信任边界强制执行 ### v0.5 — 框架集成 - LangChain 原生回调处理器 - AutoGen 监控钩子 - CrewAI 中间件 ### v1.0 — 生产环境加固 - 异步原生管道 - 实时警报（终端、Webhook、电子邮件） - 将检测结果导出为 JSON/CSV 用于研究 - 策略文件 — 使用 YAML 定义每个代理允许的工具、范围和行为 ### v2.0 — AgentSafe Cloud *（托管，可选）* 核心 SDK 将永远是免费和开源的。计划为需要以下功能的团队和公司提供托管云服务： - **托管仪表板** — 无需自托管，跨运行和机器持久保存历史记录 - **团队访问** — 在整个组织内共享会话、检测结果和警报 - **Slack / Webhook 警报** — 当生产环境中触发关键检测时立即收到通知 - **合规性导出** — 将完整的代理审计日志导出为 PDF 或 CSV，适用于受监管行业（金融、医疗、法律） - **策略执行** — 在 YAML 文件中定义代理可以和不可以做什么；AgentSafe 在违规执行前进行阻止 - **本地部署选项** — 面向无法将数据发送到云端的企业 ## 编写自定义检测器 添加检测器很容易。只需继承 `BaseDetector`，实现 `detect()` 方法，然后传递给 `wrap()`： ``` from agentsafe.detectors.base import BaseDetector from agentsafe.models import Detection, Event, Severity class MyDetector(BaseDetector): name = "my_detector" def detect(self, event: Event) -> list[Detection]: if "forbidden phrase" in (event.response_content or ""): return [self._make_detection(event, label="Forbidden phrase detected", severity=Severity.warning)] return [] client = agentsafe.wrap(openai.OpenAI(), detectors=[MyDetector()]) ``` ## 目标 - **开源，MIT 许可** — 在安全社区采用的最快路径 - **本地优先** — 无需云端运行，数据不离开本机 - **零配置启动** — `agentsafe.wrap(client)` 开箱即用 - **框架无关** — 在 OpenAI 客户端级别挂钩，适用于任何框架 - **研究友好** — 结构化日志和判定结果易于导出/分析 - **可扩展** — 约 10 行代码即可编写自定义检测器 ## 非目标 - 不是通用可观测性工具（请使用 LangSmith） - 不是越狱/红队工具（参见 Garak、PyRIT） - 不是云托管 SaaS ## 目标用户 - 测试代理型系统的 AI 安全研究人员 - 构建多智能体管道并希望添加安全防护栏的开发者 - 评估已部署代理的红队成员 - 需要可审计的代理行为记录的非政府组织/实验室 ## 项目状态 积极开发中 — v0.1 已发布。欢迎贡献。

标签：AI代理安全, AI安全, AI风险缓解, AutoGen, AV绕过, Chat Copilot, CrewAI, FastAPI, LangChain, LLM-as-judge, OpenAI API, Python SDK, SQLite, 二进制发布, 代理行为分析, 可观察性, 安全信号监控, 开源工具, 技术教程, 数据可视化, 本地仪表板, 范围蔓延, 行为基准学习, 行为异常检测, 轻量级, 运行时监控, 逆向工具, 零日漏洞检测