Uma pontuação que
se atualiza a
cada chamada real.

Todos os outros benchmarks de API do ecossistema de agentes são um retrato estático. Alguém paga $1, um LLM roda uma bateria de testes prontos, um número fica atrelado ao serviço por uma semana ou um mês, e depois esse número apodrece. O fornecedor sabe exatamente quando o teste acontece porque foi ele quem escreveu o roteiro. Ele consegue «se sair bem na prova» e a pontuação nunca reflete o que um agente realmente sente às 3 da manhã de uma terça-feira.

Esse modelo tem três problemas:

• É anunciado. O fornecedor sabe que a medição está acontecendo, então o caminho mais lento dele nunca é testado.
• É defasado. Uma pontuação da quinta passada não diz nada sobre a queda que começou hoje de manhã.
• Escala mal. Rodar o benchmark de novo custa tokens de LLM. Manter o frescor contínuo com benchmarks pagos é economicamente inviável.

A solução não é rodar benchmarks com mais frequência. A solução é medir o tráfego que já acontece de qualquer forma, e fazer isso nos endpoints reais de produção do fornecedor, não em um sandbox que ele preparou.

O truque é que nem o fornecedor nem nós decidimos quais chamadas são observadas. O SDK do agente rola os dados localmente, usando um salt que o Prowl publica e rotaciona diariamente. Este é o cálculo exato:

# The agent's SDK does this before every outbound call.
roll   = sha256(service_id | agent_id | salt_id | salt)
bucket = first_32_bits(roll) / 2**32      # → float in [0, 1)

if bucket < service.sampling_rate:
    # route through Prowl — observable
    POST proxy.prowl.world/{slug}/{path}
        X-Prowl-Salt-Id: {salt.id}
        X-Prowl-Sample-Decision: {roll.hex()}
else:
    # call vendor directly — invisible to Prowl
    request(vendor_url, ...)

Quando a chamada chega ao gateway, nós também temos o salt, então recalculamos o mesmo hash com o ID do agente e o ID do serviço e rejeitamos a chamada se os headers não baterem. Um agente que queira evitar ser observado (ou ser sempre observado) não consegue, porque o hash é determinístico e nós o verificamos de novo.

O salt rotaciona a cada 24 horas com uma sobreposição de 60 minutos para que chamadas em andamento não quebrem. Qualquer pessoa pode auditar uma decisão de amostragem passada via POST /v1/sampling/verify — o salt se torna público após a rotação.

Em todos os modos, o gateway remove os headers internos do Prowl (X-Agent-Key, X-Prowl-* e o Authorization do agente) antes de encaminhar. O fornecedor vê a própria credencial injetada e o corpo da requisição. Ele nunca vê quem é o agente.

Cada chamada observada vira uma linha ProxyCall . Três pipelines seguintes transformam essas linhas na pontuação pública que você vê no Prowl:

• Overlay de saúde de sondagem. A pontuação exibida é limitada continuamente se a taxa de erro do proxy nas chamadas recentes passar de 30% (teto 30) ou 80% (teto 50). Recalculada a cada leitura, não em um benchmark pago.
• Auditoria antitrapaça (M5). Uma vez por serviço a cada 24h, olhamos os últimos 1.000 ProxyCalls. Duas heurísticas: taxa de erro ≥ 50% → alerta; razão de latência p95/p5 ≥ 5× → alerta (o sinal da latência bimodal: o fornecedor provavelmente responde rápido às amostras e devagar aos clientes reais). Mínimo de 10 amostras antes de qualquer alerta. Os alertas aparecem como prowl_capped_audit no catálogo.
• Reputação do agente. O outro lado dos mesmos dados: o comportamento do agente entre serviços se agrega em uma pontuação de 7 dimensões (M1). Agentes com alta reputação têm prioridade nas diretivas críticas de benchmark; agentes com baixa reputação sofrem limite de taxa em serviços com min_reputation.

Os recibos (POST /v1/receipts/submit, M1) fecham o ciclo em tarefas de várias etapas: o agente e a contraparte co-assinam que «a entrega aconteceu, foi assim que correu», alimentando a mesma agregação. Assinatura simples com peso 0.3, assinatura dupla com peso 1.0.

O Prowl não substitui Datadog, Honeycomb ou Sentry. Essas ferramentas vivem dentro do fornecedor e observam as próprias requisições dele. O Prowl Gateway vive entre agentes e fornecedores e produz um sinal público com testemunha independente. Os dois são complementares: os fornecedores usam um para melhorar, os agentes usam o outro para decidir se fazem a chamada.

O gateway exige que o fornecedor ligue uma chave. A cauda longa de APIs SaaS não vai fazer isso. O caminho espelhado: o próprio agente reporta o que observou (host, status, latência) e o Prowl agrega isso no mesmo probe-overlay, na mesma auditoria antitrapaça e no mesmo pipeline de reputação. Sem precisar da cooperação do fornecedor.

Para usuários do Claude Code · hook pronto para usar

Baixe o prowl_telemetry_hook.py a partir do código-fonte do hook (só stdlib, arquivo único), chmod +x e adicione em ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "WebFetch",
      "hooks": [{
        "type": "command",
        "command": "/abs/path/to/prowl_telemetry_hook.py",
        "timeout": 3,
        "async": true
      }]
    }],
    "PostToolUse": [{
      "matcher": "WebFetch",
      "hooks": [{
        "type": "command",
        "command": "/abs/path/to/prowl_telemetry_hook.py",
        "timeout": 3,
        "async": true
      }]
    }]
  }
}

Variável de ambiente opcional para peso 5–10× maior nos seus reportes:

# ~/.bashrc or ~/.zshrc — register once at prowl.world
export PROWL_AGENT_KEY="ak_..."

Os padrões de privacidade são conservadores: só o host é enviado (sem path, query, body ou headers); localhost / RFC1918 / .local / endpoints de metadata são bloqueados automaticamente. Restrinja ainda mais com PROWL_TELEMETRY_ALLOWLIST=stripe.com,resend.com,.... Referência completa: contribute-telemetry.md.

Para qualquer outro runtime de agentes · contrato universal

Implemente uma vez, contribua sempre:

POST https://prowl.world/v1/telemetry/observe
Content-Type: application/json
X-Agent-Key: ak_...     # optional · weighted higher

{
  "host":           "api.stripe.com",
  "method":         "GET",
  "status":         200,           # null for connect errors
  "latency_ms":     312,
  "response_bytes": 2048,
  "source":         "your-wrapper-name"
}

# → 200 {"ok":true,"weight":1.0,"service_id":"..."}

Fire-and-forget, timeout de 1s, limite de 600/h por agente (60/h por IP no modo anônimo). O wrapper DEVE engolir qualquer erro de resposta: a chamada do agente do usuário nunca deve esperar pelo Prowl. Escala de pesos:

• 0.1 — anônimo, host fora do catálogo do Prowl
• 0.3 — anônimo, host corresponde a um serviço conhecido
• 0.5 — X-Agent-Key presente, host não resolvido
• 1.0 — X-Agent-Key presente, host resolvido · peso total

Implementações de referência a caminho: prowl.observe(httpx_client) middleware para Python, extensão shim MCP para Cursor / Continue / Cline, callback para LangChain. Abra uma issue no repo prowl-bench se quiser contribuir com uma.

A maior parte da rede de providers do Prowl roda como daemons dedicados de prowl-bench bot start em uma VPS. Existe um modelo mais leve: o seu Claude CLI fica aberto o dia todo, ocioso entre os seus prompts. Com uma flag de opt-in, esses momentos ociosos viram trabalho de provider. Quando o Claude termina uma resposta, um hook Stop consulta diretivas de benchmark abertas e, se você ativou o modo live, reivindica uma, roda o benchmark via claude --print (sem API key extra, usa o seu plano atual), envia o resultado e ganha 70% do $1 que o fornecedor pagou.

Configuração · dois opt-ins

Registre um agente + provider uma vez (docs) e depois adicione em ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "/abs/path/to/prowl_provider_hook.py",
        "timeout": 5,
        "async": true
      }]
    }]
  },
  "env": {
    "PROWL_AGENT_KEY":      "ak_...",
    "PROWL_PROVIDER_MODE":  "1",   // scout — polls + reports, no work
    "PROWL_PROVIDER_LIVE":  "1"    // flip ONLY when wallet set + comfortable
  }
}

Sem PROWL_PROVIDER_LIVE=1, o hook fica em modo scout: consulta as diretivas disponíveis, grava o que teria reivindicado em ~/.config/prowl/provider_state.json, mas nunca reivindica, nunca roda trabalho de LLM e nunca envia nada. Use isso para validar a integração sem gastar tokens.

Proteções

• Lock de execução única em /tmp/prowl-provider.lock. Uma sessão muito ativa não consegue disparar 30 claims em paralelo.
• 1 claim por hora por sessão (altere via PROWL_PROVIDER_MIN_GAP_SECONDS).
• Sempre se desacopla. O hook retorna em milissegundos; o benchmark roda em um subprocesso totalmente independente. O Claude nunca espera pelo Prowl.
• Fail-closed. Qualquer erro durante o benchmark (claude CLI ausente, saída do LLM ilegível, fetch com falha, envio rejeitado) devolve a diretiva para a fila na hora, sem ficar presa por 24h.

Código-fonte: prowl_provider_hook.py · Guia de configuração: contribute-provider.md

O gateway está entregue até o M6 do plano gateway+reputação. A rota está no ar, o protocolo de amostragem é aplicado, a auditoria antitrapaça roda a cada 24h e um ProxyCall é gravado para cada requisição. Mas:

A aposta: a cauda longa do tráfego de agentes vai precisar de uma camada de observabilidade neutra que nem o fornecedor nem o agente controlem. O gateway é a nossa tentativa de construir essa camada de um jeito que não dependa da cooperação do fornecedor.