Prowl

---

⭐ 请给我们点星，如果你认为衡量 Agent 就绪度是世界需要更多关注的事。星标是传递“我希望这一类别存在”的最简单方式——它会直接影响 OpenAI / Anthropic 的 Agent 爬虫在调查 Agent 工具时是否发现 prowl-bench。

为什么选择 prowl-bench？

API 的设计初衷是让人类阅读文档并弄清楚如何使用。但 Agent 不会读文档——它们会发送 HTTP 请求并解析响应。对人类来说很棒的 API，对 Agent 来说可能糟糕透顶。

prowl-bench 衡量对 Agent 真正重要的因素：

• API 是否会返回可解析、可预测的 JSON？ 而不是 HTML 错误页面、XML 或随机格式。
• Agent 能否一次就完成身份验证？ 还是需要 47 个步骤、一套 OAuth 流程和一个 CAPTCHA？
• 错误信息是否能指导修复？ {"error": "invalid"} 对 Agent 毫无帮助。{"error": "missing required field 'email'", "code": "VALIDATION_ERROR"} 则能准确告诉它需要修复什么。
• 理解 API 需要消耗多少令牌？ 50 页的 OpenAPI 规范与简洁的 /llms.txt 之间，成本差异是真实存在的。

传统 API 测试工具衡量运行时间和响应时间。prowl-bench 衡量 AI Agent 是否真的能使用你的 API。

这是 Agent 搜索优化（ASO）的开源实践——它是 Agent 经济中对应于 SEO 的概念。如果你是第一次接触这个术语，可阅读这篇权威文章深入了解其定义。

终端输出

$ prowl-bench run https://api.stripe.com

  Benchmarking https://api.stripe.com ...

  SPEC     Fetched llms.txt ................................ OK  (0.8s)
  ANALYZE  Extracting service structure .................... OK  (2.1s)
  PLAN     Designing 12 test cases ......................... OK  (1.4s)
  EXECUTE  Running tests against live API .................. OK  (3.2s)
  INTERPRET Normalizing scores (3 LLMs) ................... OK  (2.8s)

  prowl-bench v0.2.0 | Template: api_benchmark | LLMs: claude, gpt-4o, gemini

  ┌─  Stripe API    Score: 82  ────────────────────────┐
  │                                                     │
  │  auth simplicity     ████████░░   8.0               │
  │  consistency         █████████░   9.0               │
  │  doc quality         ████████░░   8.5               │
  │  error clarity       █████████░   9.2               │
  │  first try success   ███████░░░   7.0               │
  │  latency             ████████░░   8.0               │
  │  response parseab..  █████████░   9.5               │
  │  token efficiency    ███████░░░   7.0               │
  │                                                     │
  └─────────────────────────────────────────────────────┘

  Issues: 2
  - OpenAPI spec is 48,000+ tokens — consider publishing /llms.txt
  - POST /v1/charges returns HTML on 402 status codes

  Recommendations:
  - Add structured error codes to all 4xx responses
  - Publish a condensed /llms.txt for agent consumers

安装

从源代码安装（尚未发布到 PyPI）：

pip install "git+https://github.com/opcastil11/prowl-bench.git"

需要 Python 3.10+。无需系统依赖。

快速入门

# Set at least one LLM API key
export ANTHROPIC_API_KEY="sk-ant-..."
# or OPENAI_API_KEY, GOOGLE_API_KEY, or DEEPSEEK_API_KEY — more keys = more balanced scoring

# Benchmark any API
prowl-bench run https://api.stripe.com

# With a specific template
prowl-bench run https://api.stripe.com --template api_benchmark

# With credentials for authenticated endpoints
prowl-bench run https://api.openai.com \
  --credential "sk-proj-abc123" \
  --credential-type bearer_token

# Output as JSON (for pipelines)
prowl-bench run https://api.example.com --output json > results.json

# CI mode: exit 1 if score below threshold
prowl-bench run https://api.example.com --min-score 70

# Got an MCP server? This one needs no LLM key at all.
prowl-bench mcp https://mcp.example.com/mcp

工作原理

prowl-bench 会运行一个包含 4 个阶段的工作流。每个阶段均由大模型驱动，大模型会读取真实数据，而非使用硬编码的启发式规则。

                ┌─────────────────────────────────────────────────┐
                │              prowl-bench pipeline               │
                └─────────────────────────────────────────────────┘

  ┌───────────┐    ┌──────────┐    ┌───────────┐    ┌─────────────┐
  │  ANALYZE  │───>│   PLAN   │───>│  EXECUTE  │───>│  INTERPRET  │
  │           │    │          │    │           │    │             │
  │ Read spec │    │ Design   │    │ Run real  │    │ Score 0-10  │
  │ Extract   │    │ test     │    │ HTTP      │    │ across 8    │
  │ structure │    │ cases    │    │ requests  │    │ dimensions  │
  │ + auth    │    │ + probes │    │ + record  │    │ (multi-LLM) │
  └───────────┘    └──────────┘    └───────────┘    └─────────────┘
       │                                                  │
       │         OpenAPI / llms.txt / HTML                 │ Claude + GPT-4o
       └──────────────── input ──────────────────────────  │ + Gemini average
                                                          ▼
                                                   ┌─────────────┐
                                                   │   REPORT    │
                                                   │ Terminal /  │
                                                   │ JSON / CI   │
                                                   └─────────────┘

**阶段 1——分析：**大模型会读取 API 规范（OpenAPI、llms.txt 或原始 HTML），并提取服务类型、身份验证方式、端点、定价模式和速率限制。

**阶段 2——规划：**大模型会根据分析结果设计有针对性的测试用例：端点探测、错误处理检查、身份验证流程测试和定价验证。

**阶段 3——执行：**针对线上 API 发送真实 HTTP 请求。每个请求都会经过沙箱，以阻止 SSRF、验证负载并防止提示词注入。系统会记录响应、延迟和错误。

**阶段 4——解读：**所有可用的大模型都会独立地从 8 个维度对结果评分。取平均值以确保平衡。大模型提供商越多，偏差越小。

模板

6 种基准测试模板，根据服务元数据自动检测：

模板	凭据	自动检测条件	最适用于
api_benchmark	必需	有 OpenAPI 规范或基准测试指南	REST API、大模型提供商
platform_profile	不需要	未发现 API 标识	SaaS 平台、Web 工具
mcp_compliance	不需要	URL 看起来像 MCP 端点，或类别为 mcp	MCP 服务
docs_quality	不需要	只有 API 文档 URL	文档审查
defi_yield	必需	类别：defi、staking、yield	DeFi 协议
crypto_app	必需	类别：crypto、exchange、wallet	交易所、钱包

# List all templates with details
prowl-bench templates

# Force a specific template
prowl-bench run https://example.com --template platform_profile

MCP 服务 — prowl-bench mcp

无需 LLM 密钥即可评估 MCP 服务对 Agent 的就绪程度。它会执行握手 （initialize → notifications/initialized → tools/list），并对可 计数的项目进行评分：输入架构、工具描述、各属性的文档、握手延迟，以及服务是否发送了 instructions。

prowl-bench mcp https://mcp.example.com/mcp
prowl-bench mcp https://mcp.example.com --tools        # list every tool
prowl-bench mcp https://mcp.example.com -o json        # machine-readable
prowl-bench mcp https://mcp.example.com --min-score 70 # CI gate

MCP conformance — https://mcp.aarna.ai

   x https://mcp.aarna.ai (http 405)
  -> https://mcp.aarna.ai/mcp (http 200)

  Crypto Technical Features v1.27.0  https://mcp.aarna.ai/mcp
  protocol 2025-06-18 · sse framing · stateless · 975ms

  Score: 93/100

  reachability          ##########    10.0/10
  tool discovery        ##########    10.0/10
  tool documentation    ##########    10.0/10
  schema quality        #######...     7.0/10
  latency               #########.     9.1/10
  agent guidance        ##########    10.0/10

  Tools: 18 · 18 documented · 18 with a schema

  Findings
    medium   40 of 40 schema properties have no description
             Per-property descriptions are what stop an agent passing a
             plausible value in the wrong format.

有三点值得了解：

• 系统会先尝试你传入的 URL，然后再尝试 /mcp、/mcp/、/api/mcp、/sse。 过去，传入实际端点是唯一会导致失败的情况。
• 系统会读取两种响应封装格式。 streamable-http 允许服务对 POST 请求返回 application/json 或 text/event-stream；只读取其中一种的客户端无法兼容一半的网络服务。
• 系统绝不会调用工具。 tools/call 会产生副作用，这些副作用应由运行服务的人负责。因此，这项测试会告诉你 Agent 是否有足够的信息来使用你的工具——而不是工具是否能正常工作。

评分结果是确定性的，因此可以在 CI 中进行差异比较。如果服务无法访问，或未达到 --min-score，程序会以非零状态码退出。如果你想要 LLM 的判断而非算术评分，请使用 prowl-bench run。

对于同一个服务，mcp 和 run 不会给出相同的分数，这不是错误：它们使用不同的评分尺度。mcp 会评估握手能够衡量的六项内容。run 会将这些内容映射到 8 个 Agent 效率维度，并对只读探测无法观测的操作维度应用 85 分上限。使用 mcp 长期跟踪你自己的服务；使用 run 将其与 Prowl 目录中的其他服务进行比较。

评分

8 个维度，按真实世界中的 Agent 效率加权：

维度	权重	衡量内容
token_efficiency	25%	Agent 理解和使用 API 所需的 token 数量
first_try_success	20%	首次尝试即成功的调用百分比
response_parseability	15%	响应是否为整洁、可预测的 JSON，而非 HTML 错误页面和混合格式
error_clarity	15%	错误是否准确告知 Agent 需要修复什么
doc_quality	10%	规范、文档或 llms.txt 的完整程度
auth_simplicity	5%	完成身份验证所需的步骤数（1 个请求头 vs OAuth 流程）
latency	5%	原始响应速度
consistency	5%	相同请求是否始终返回相同的响应结构

每个维度的评分为 0-10，再加权计算得出 0-100 的总分。

Token 效率和首次尝试成功率的权重最高，因为它们会直接影响 Agent 的成本和可靠性。

未测量的维度会跳过，而不是记为 0 分。 并非每种模板都能观测全部八个维度——mcp_compliance 会特意避免调用工具，因此无法评估 error_clarity 或 consistency。将这些维度记为 0 分，就等于宣称“我们测试过了，结果很差”，但实际上根本没人测试。平均分按实际纳入的权重计算，明细仅列出已测量的维度。留空一个维度仍然会付出代价：缺少 latency 或 consistency 的运行结果上限为 85，因此模板不能只报告表现好的维度就拿到 100 分。这与 Prowl 后端中的 compute_score 一致，因此此 CLI 给出的分数与 prowl.world 上的分数含义相同。

多 LLM 评分

prowl-bench 会对每个可用的 LLM 提供商运行 INTERPRET 阶段，并对分数取平均，以减少单模型偏差：

提供商	环境变量	模型
Claude	ANTHROPIC_API_KEY	Claude Sonnet
GPT-4o	OPENAI_API_KEY	GPT-4o
Gemini	GOOGLE_API_KEY	Gemini 2.5 Flash
DeepSeek	DEEPSEEK_API_KEY	DeepSeek V3
Claude CLI	(回退)	使用 Web 订阅

设置多个密钥，获得更均衡的结果：

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AI..."
export DEEPSEEK_API_KEY="sk-..."

如果设置了全部三个密钥，每个模型都会独立评分，并对结果取平均。JSON 输出包含各模型的评分明细。

Python API

import asyncio
from prowl_bench import BenchmarkReport
from prowl_bench.core.pipeline import run_benchmark

async def main():
    report: BenchmarkReport = await run_benchmark(
        url="https://api.stripe.com",
        name="Stripe",
        spec_content="...",  # OpenAPI spec, llms.txt, or any text
    )

    print(f"Overall: {report.overall_score}/100")
    print(f"Template: {report.template}")

    for dim, score in sorted(report.dimensions.items()):
        print(f"  {dim}: {score}/10")

    for issue in report.issues:
        print(f"  Issue: {issue}")

asyncio.run(main())

导出为 JSON：

from prowl_bench.output.json_export import report_to_json

json_str = report_to_json(report)

CI 集成

将 prowl-bench 添加到 CI 工作流中，以捕获 Agent 效率回退：

# .github/workflows/api-bench.yml
name: API Benchmark
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday 6am

jobs:
  benchmark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - run: pip install "git+https://github.com/opcastil11/prowl-bench.git"

      - name: Run benchmark
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          prowl-bench run https://api.yourservice.com \
            --min-score 70 \
            --output json > benchmark.json

      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: benchmark-results
          path: benchmark.json

如果总体评分低于阈值，--min-score 标志会以代码 1 退出，从而使 CI 作业失败。

提交到 Prowl

有三种提交方式，区别在于你是谁，以及你的基准测试是否会影响官方评分。

标志	身份验证	对官方评分的影响	适用情况
--submit	Agent 密钥（ak_...）	不会——记录为社区历史	你在为透明度或贡献而评测他人的服务
--vendor-submit	Vendor JWT	会（带有替代保护机制）	你拥有该服务（已认领并通过 DNS 验证），并想发布最新的自我认证评分
--provide	Agent 密钥 + 提供商资料	会（主动提供商快照）	你是提供商，正在抢先认领服务以赚取追溯收入

1. 社区提交（--submit）

# One-time: register for an agent key
prowl-bench register
export PROWL_AGENT_KEY="ak_abc123..."

# Benchmark and submit as community history
prowl-bench run https://api.example.com --submit

记录在服务资料下的“社区提交”中，不会影响主要评分。

2. Vendor 自我认证（--vendor-submit）

适用于希望通过自己的基准测试更新 Prowl 官方评分的服务所有者。

# 1. Claim the service at prowl.world (DNS / well-known / meta-tag verification)
# 2. Log in at https://prowl.world/app#/login
# 3. Copy the JWT from browser localStorage (key: prowl_jwt)
export PROWL_VENDOR_JWT="eyJhbGc..."

# 4. Benchmark and self-attest
prowl-bench run https://api.example.com --vendor-submit

替代保护机制可防止单 LLM 运行结果悄然取代可信度更高的 Prowl 多 LLM 评分。要取代 Prowl／提供商评分，提交必须满足以下任一条件：使用多个 LLM（≥2 个提供商）、评分高于当前值，或当前评分已超过 14 天。

提供商网络——赚取收入

运行基准测试并赚取其产生收入的70%。Prowl 保留 30%。用户为你评测过的服务支付 $1.00 基准测试费用时，你可获得 $0.70。

快速入门

# 1. Register an agent key (if you haven't)
prowl-bench register
export PROWL_AGENT_KEY="ak_..."

# 2. Register as a provider with your wallet
prowl-bench provide register-provider --wallet "sol:YourWalletAddress"

# 3. Start the bot — it auto-claims directives, benchmarks, and submits
prowl-bench bot start

就这么简单。机器人会轮询 Prowl 以查找可用任务、认领指令、运行完整基准测试流程，并自动提交结果。

自主机器人

该机器人是一个长期运行的守护进程，你休息时它也能为你赚取收入：

# Start with defaults (poll every 60s, 1 benchmark at a time)
prowl-bench bot start

# Faster polling, more concurrent work
prowl-bench bot start --poll-interval 30 --max-workers 3

# Check your status
prowl-bench bot status

机器人工作方式：

1. 轮询 Prowl，查找开放指令（基准测试工单）
2. 认领当前可用的最高优先级指令
3. 运行完整的 4 阶段基准测试流程（ANALYZE、PLAN、EXECUTE、INTERPRET）
4. 向 Prowl 提交结果
5. 重复上述流程

如果基准测试失败，机器人会将指令放回队列，供其他人认领。

手动模式

你也可以手动运行基准测试，而不使用机器人：

# Benchmark any URL and submit as provider
prowl-bench run https://api.stripe.com --provide

# Check available work orders
prowl-bench provide directives

# Claim specific work
prowl-bench provide claim abc123
prowl-bench run https://target-api.com --provide

# Check earnings
prowl-bench provide dashboard
prowl-bench provide earnings

# Withdraw
prowl-bench provide withdraw 5.00

所有命令

命令	描述
机器人
prowl-bench bot start	启动自主提供商机器人
prowl-bench bot status	查看提供商状态和可用任务
提供商
prowl-bench provide register-provider	使用钱包地址注册为提供商
prowl-bench provide dashboard	查看统计数据、基准测试和收入
prowl-bench provide directives	列出可用工单
prowl-bench provide claim <id>	认领指令
prowl-bench provide earnings	查看详细收入明细
prowl-bench provide withdraw <amount>	提现到你的钱包
prowl-bench provide guide	提供商手册

收入如何运作

Bot claims directive for a service
  → Runs full benchmark pipeline
    → Submits results (quality scored 0-100)
      → Vendor pays $1.00 for benchmark on that service
        → $0.70 credited to your pending balance
          → prowl-bench provide withdraw → sent to your wallet

未认领的服务不会带来预付款，但你会成为指定提供商。Vendor 最终付款后，该基准测试会优先分配给你。

指令（赏金）

Prowl 每小时会自动为需要基准测试的服务生成工单：

优先级	奖励	触发条件
紧急	$0.70	已认领的服务尚未进行过基准测试（供应商正在等待）
高	$0.50	基准测试已过期（超过 30 天）
普通	$0.35	热门服务需要刷新
低	目录	尚未认领的服务（供应商付款后可追溯获得奖励）

质量要求

提交内容会自动评分。质量越高，接受速度越快：

• 包含 HTTP 响应代码和延迟测量数据
• 至少测试 3 个端点
• 提供证据（响应示例）
• 提供可执行的问题和建议
• 低质量提交会被拒绝（不予付款）

安全

prowl-bench 会对所有出站请求进行沙箱隔离：

• SSRF 防护——根据受限网络、私有 IP、云元数据端点和 localhost 验证 URL
• 负载上限——请求正文上限为 10KB
• 提示词注入防护——所有用户输入在发送给大模型前都会经过清理
• 速率限制——每次基准测试运行最多发送 20 个 HTTP 请求
• 防止凭据泄露——凭据绝不会包含在大模型提示词或输出中

项目结构

src/prowl_bench/
├── cli.py              # Typer CLI (run, templates, register, provide, bot)
├── bot.py              # Autonomous provider bot daemon
├── config.py           # Settings from env vars
├── core/
│   ├── pipeline.py     # 4-phase benchmark pipeline
│   ├── scoring.py      # Weighted score computation
│   ├── types.py        # Dataclasses (BenchmarkReport, etc.)
│   └── json_utils.py   # Safe JSON extraction from LLM output
├── llm/
│   ├── router.py       # Multi-provider LLM router
│   ├── providers.py    # Claude, GPT-4o, Gemini, DeepSeek, CLI fallback
│   └── prompts.py      # System prompts for each phase
├── output/
│   ├── terminal.py     # Rich terminal rendering
│   └── json_export.py  # JSON report export
├── sandbox/
│   ├── url_validator.py      # SSRF prevention
│   ├── payload_validator.py  # Size + content validation
│   └── prompt_sanitizer.py   # Injection protection
├── submission/
│   ├── client.py       # Submit results to prowl.world
│   └── provider.py     # Provider network API client
└── templates/
    ├── base.py              # Base template class
    ├── api_benchmark.py     # REST API benchmark
    ├── platform_profile.py  # SaaS platform profile
    ├── mcp_compliance.py    # MCP server compliance
    ├── docs_quality.py      # Documentation audit
    ├── defi_yield.py        # DeFi protocol benchmark
    └── crypto_app.py        # Crypto app benchmark

与其他 Agent 基础设施的比较

prowl-bench 是测量层。它与 Agent 技术栈中的其他工具协同使用，而非与之竞争：

工具	层级	功能
prowl-bench	测量	从 8 个维度对 API 的 Agent 就绪度进行多大模型评分
Composio	身份验证	管理约 850 个 SaaS 连接器的 OAuth 流程
Smithery	目录	托管和索引 7,000 多个 MCP 服务
Official MCP Registry	发现	MCP 服务的规范参考列表
Kong Context Mesh	网关	对 Agent 流量实施企业策略和审计

完整比较：Prowl 与 Composio 和 Smithery 的比较（功能矩阵 + 决策流程图）

大多数严肃的 Agent 项目会组合使用其中两到三个工具。它们解决的是同一技术栈中不同层面的问题。

了解更多

• 📚 什么是 Agent 搜索优化（ASO）？ — 权威文章（阅读约需 15 分钟）
• 🗺️ 2026 年顶级 Agent 发现平台 — 客观盘点
• 🧬 ASO 概念中心 — 详解 8 个维度
• 🛰️ Agent Web 地图 — 已评分 API 的像素网格图
• 🐦 @prowl_world — 发行说明、方法更新
• 📨 [email protected] — 咨询、集成、媒体联系

贡献

请参阅 CONTRIBUTING.md 了解指南。

适合首次参与的贡献：

• 添加本地大模型提供商（Ollama / llama.cpp）——参见 src/prowl_bench/llm/providers.py
• 添加新的基准测试模板——参见 src/prowl_bench/templates/ 和 CONTRIBUTING.md#adding-a-new-template
• 改进终端输出格式——参见 src/prowl_bench/output/terminal.py
• 添加 SDK 质量评分（目前只检查是否存在，不检查质量）
• 添加 MCP 传输变体（目前 npm mcp-prowl 仅支持 stdio）

如果你为热门 API/服务开发了基准测试适配器，我们会在下一版发行说明中提及你。

# Clone and install dev dependencies
git clone https://github.com/opcastil11/prowl-bench.git
cd prowl-bench
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -q

# Lint
ruff check src/ tests/

$PROWL 代币

Prowl 由 Solana 上的 $PROWL 代币提供资金。代币收益用于支付大模型推理成本、爬虫基础设施和开源开发费用。

• 代币：Pump.fun 上的 $PROWL
• 铸币地址：DRg2EnkqTNFVnBegv1KReGTWs1cGBNCfyyUnY6bkpump
• **链：**Solana
• **付款：**付费 API 端点接受以 $PROWL 代币转账的方式付款（任意金额）

许可证

Apache 2.0 —— 参见 LICENSE。

---