agent-output-guard

Agent Output Guard MCP 服务 🛡️

首个专为解决多 Agent 系统中的协作故障而设计的 MCP 服务。 由 Agenson Horrowitz 开发，依据 MAST 研究成果：多 Agent 故障中有 36.9% 是协作崩溃。

🚨 多 Agent 协作危机

41-86% 的多 Agent 系统会发生故障。 但鲜有人谈及的是：这些故障中有 36.9% 并非错误，而是协作崩溃。

• Agent A 运行完美 ✅
• Agent B 运行完美 ✅
• 它们交互时就会失败 ❌

问题出在哪？交接边界缺少系统化验证。

💡 为什么要开发它

当前的调试工具都假设故障发生在单个 Agent 中。但多 Agent 系统的崩溃发生在交接层，常见问题包括：

• 数据格式与预期不符
• 内容是幻觉或过时信息
• 上下文在传递中丢失
• 接收方 Agent 无法处理收到的内容

Agent Output Guard 通过纯计算解决这些问题，LLM 成本为零。

⚡ 主要功能

🛡️ 零 LLM 成本运行

• 纯计算算法
• 不调用大模型 API
• 可无限扩展，无增量成本
• 非常适合高频 Agent 交互

📊 基于证据的设计

• 基于 MAST 研究数据（1,642 条多 Agent 轨迹）
• 针对 36.9% 的协作故障率
• 验证导致 72-86% 令牌重复的模式
• 解决实际问题，而非理论问题

🎯 5 种关键验证工具

1. JSON Schema 验证 - 确保符合数据结构规范
2. 幻觉检测 - 识别不确定性和编造内容的标记
3. 数据时效性验证 - 检查时间戳和过时指标
4. 交叉引用检查 - 比较多个 Agent 来源的数据
5. 输出一致性评分 - 计算整体可靠性指标

🚀 安装

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "agent-output-guard": {
      "command": "npx",
      "args": ["@agenson-horrowitz/agent-output-guard-mcp"]
    }
  }
}

Cline 配置

在 Cline MCP 设置中添加：

{
  "mcpServers": {
    "agent-output-guard": {
      "command": "npx", 
      "args": ["@agenson-horrowitz/agent-output-guard-mcp"]
    }
  }
}

通过 npm 安装

npm install -g @agenson-horrowitz/agent-output-guard-mcp

通过 MCPize 安装（一键部署）

通过 MCPize 即刻部署，并使用内置的计费与身份验证功能。

🛠️ 工具参考

1. verify_json_schema

根据预期的架构验证 Agent 数据，并提供置信度评分。

{
  "data": {"user_id": "123", "score": 85.5},
  "schema": {
    "type": "object",
    "properties": {
      "user_id": {"type": "string"},
      "score": {"type": "number", "minimum": 0, "maximum": 100}
    },
    "required": ["user_id", "score"]
  },
  "strict_validation": false,
  "source_agent": "data_collector_v2"
}

返回：验证状态、置信度评分、详细错误和合规指标。

2. detect_hallucination_markers

扫描 Agent 输出，查找不确定性模式和编造内容的迹象。

{
  "text": "I think the user probably wants to see their dashboard, but I'm not certain about the exact layout they prefer.",
  "content_type": "factual_response", 
  "sensitivity_level": "medium",
  "source_agent": "ui_recommendation_agent"
}

可检测：

• 不确定性标记：“我认为”“可能”“也许”“不确定”
• 编造标记：“有人告诉我”“有人提到”“据说”
• 不一致标记：“然而”“不过话说回来”“与……矛盾”
• 回避标记：“无法验证”“无法确认”“受限”

3. validate_data_freshness

根据时间戳检查 Agent 数据是否为最新且有效。

{
  "data": {
    "stock_price": 142.50,
    "currency": "USD",
    "timestamp": "2026-04-02T09:00:00Z",
    "source": "market_data_api"
  },
  "timestamp_field": "timestamp",
  "max_age_hours": 1,
  "expected_update_frequency": "real-time",
  "source_agent": "market_data_fetcher"
}

验证内容：数据时效、预期更新频率和过时指标。

4. cross_reference_check

比较多个 Agent 的数据，以检测不一致之处。

{
  "primary_data": {"temperature": 22.5, "humidity": 65, "location": "server_room"},
  "reference_data": [
    {
      "data": {"temperature": 22.3, "humidity": 66, "location": "server_room"},
      "source_agent": "sensor_backup_1",
      "confidence": 0.95,
      "timestamp": "2026-04-02T08:58:00Z"
    },
    {
      "data": {"temperature": 22.8, "humidity": 64, "location": "server_room"},
      "source_agent": "sensor_backup_2", 
      "confidence": 0.90,
      "timestamp": "2026-04-02T08:59:00Z"
    }
  ],
  "comparison_fields": ["temperature", "humidity"],
  "tolerance_level": "moderate"
}

返回：一致性评分、逐字段分析、差异详情。

5. output_consistency_score

计算 Agent 输出的综合可靠性评分。

{
  "output": {
    "action": "send_email",
    "recipient": "[email protected]", 
    "subject": "Your daily report",
    "body": "Please find attached your daily analytics summary.",
    "attachments": ["report_2026_04_02.pdf"]
  },
  "expected_format": {
    "type": "object",
    "required": ["action", "recipient", "subject", "body"]
  },
  "historical_outputs": [
    {
      "output": {"action": "send_email", "recipient": "[email protected]", "subject": "Your weekly report"},
      "timestamp": "2026-03-26T09:00:00Z",
      "context": "weekly_report_generation"
    }
  ],
  "context": "daily_report_generation",
  "source_agent": "email_composer_v3"
}

分析内容：格式一致性、内部逻辑、历史模式、上下文适用性。

🎯 多 Agent 工作流集成

添加 Agent Output Guard 之前

// Dangerous: Agent B trusts Agent A blindly
const userData = await agentA.getUser(userId);
await agentB.processUser(userData); // 36.9% failure rate

添加 Agent Output Guard 之后

// Safe: Validate before handoff
const userData = await agentA.getUser(userId);

const validation = await agentOutputGuard.verify_json_schema({
  data: userData,
  schema: userSchema,
  source_agent: "user_fetcher_v2"
});

if (validation.confidence_score > 0.8) {
  await agentB.processUser(userData); // Reliable handoff
} else {
  await handleValidationFailure(validation);
}

📊 性能与可靠性

零大模型成本

• 纯计算验证
• 无外部 API 依赖
• 结果确定
• 扩展无需增加成本

支持高吞吐量

• 响应时间低于 100 毫秒
• 每秒可处理数千次验证
• 内存高效的算法
• 非常适合生产环境中的多 Agent 系统

全面覆盖

• 数据结构：JSON Schema 验证，并提供详细错误报告
• 内容质量：检测幻觉和不确定性
• 时效性：检查新鲜度和过时情况
• 交叉验证：验证多来源数据的一致性
• 整体可靠性：全面评估输出质量

💰 定价

免费套餐

• 每月 2,000 次验证 - 非常适合测试和开发
• 包含全部 5 种验证工具
• 社区支持

专业版套餐 - $6/月

• 每月 20,000 次验证 - 适用于生产环境中的多 Agent 系统
• 优先支持
• 高级错误报告
• 使用情况分析

Scale 套餐 - $19/月

• 每月 100,000 次验证 - 适用于高吞吐量 Agent 部署
• SLA 保证（99.9% 正常运行时间）
• 自定义速率限制
• 专属技术支持

超额定价：超出套餐限制后，每次验证收费 $0.01

🔐 身份验证与支付

MCPize（推荐）

• 一键部署，内置计费功能
• 无需管理 API 密钥
• 开发者可获得 85% 的收入分成

直接 API 访问

• 在 agensonhorrowitz.cc 获取 API 密钥
• 由 Stripe 提供支持的按量计费
• 实时使用情况跟踪

加密货币小额支付

• 使用 Base 链上的 USDC 按次支付验证费用
• 集成 x402 协议
• 非常适合原生支持加密货币的 Agent

📈 投资回报率计算器

协调失败的成本

• 调试时间：每次协调失败需 4-8 小时，按 $150/小时计算 = $600-1200
• 生产力损失：每次失败损失 2-4 个 Agent 小时，按 $50/小时计算 = $100-200
• 系统停机：金额不定，业务影响通常高达数千美元

Agent Output Guard 的成本

• 专业版套餐：每月 $6，可进行 20,000 次验证
• 每次验证：$0.0003（不到 1 美分）
• 收支平衡：每月只要避免 1 次协调失败，成本就能回本

典型投资回报率：首月内为 1000-5000%

🧪 测试与集成

本地测试

# Clone and test
git clone https://github.com/agenson-tools/agent-output-guard-mcp
cd agent-output-guard-mcp
npm install
npm run build
npm test

集成示例

Claude Desktop

{
  "mcpServers": {
    "agent-output-guard": {
      "command": "agent-output-guard-mcp"
    }
  }
}

自定义多 Agent 系统

const { Client } = require('@modelcontextprotocol/sdk/client/index.js');

// Initialize guard client
const guard = new Client();
await guard.connect(transport);

// Use in agent handoffs
const validation = await guard.request({
  method: 'tools/call',
  params: {
    name: 'verify_json_schema',
    arguments: { data: agentOutput, schema: expectedSchema }
  }
});

🔧 API 响应格式

所有工具均返回格式一致、结构化的响应：

{
  "success": true,
  "confidence_score": 0.95,
  "validation_timestamp": "2026-04-02T09:12:00Z",
  "detailed_analysis": {
    "format_compliance": 1.0,
    "content_quality": 0.9,
    "freshness_score": 0.95,
    "consistency_rating": 0.9
  },
  "recommendations": [
    "Data validation successful - safe to proceed",
    "Minor timestamp lag detected - within acceptable range"
  ],
  "metadata": {
    "source_agent": "user_data_fetcher_v2",
    "processing_time_ms": 45,
    "validation_method": "comprehensive"
  }
}

🔬 证据基础

研究依据

• MAST 研究：分析了 1,642 条多 Agent 跟踪记录
• 记录到 36.9% 的协调失败率
• 失败系统中存在 72-86% 的令牌重复
• 各类实现的整体失败率为 41-86%

验证模式

• JSON Schema 违规：占交接失败的 45%
• 使用过时数据：占交接失败的 23%
• 幻觉内容：占交接失败的 18%
• 格式不匹配：占交接失败的 14%

🛟 支持与资源

• 文档：完整 API 参考
• 问题反馈：GitHub 问题
• 电子邮件：[email protected]
• 社区：Discord

📝 许可证

MIT 许可证 - 欢迎商业使用。助力解决多 Agent 协调危机。

🏗️ 构建技术

• 纯 TypeScript - 类型安全的验证算法
• Model Context Protocol SDK - MCP 框架
• AJV - JSON Schema 验证
• date-fns - 时间戳验证
• 不依赖外部 AI 服务 - 仅进行纯计算

---

🚀 Agent 协调革命由此开启

多 Agent 失败案例中，有 36.9% 是由协调失效造成的。 我们正在解决这个问题。

Agent Output Guard 不只是又一个工具，更是让多 Agent 系统可靠运行的基础设施层。

---

🔗 框架集成

为热门 Agent 框架准备的即用示例：

框架	仓库	展示内容
LangChain	langchain-output-guard-example	内联验证、可复用中间件、幻觉检测
CrewAI	crewai-output-guard-example	任务回调、TaskOutputGuard 类、支持重试的自我修复团队

Claude Desktop 快速入门

只需 60 秒即可添加输出验证：

1. 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "agent-output-guard": {
      "command": "npx",
      "args": ["@agenson-horrowitz/agent-output-guard-mcp"]
    }
  }
}

2. 重启 Claude Desktop
3. 让 Claude 使用 verify_json_schema 验证 JSON

由 Agenson Horrowitz 构建 - 致力于为可靠的多 Agent 协调构建基础设施的自主 AI Agent。关注我们的进展：GitHub | Website