# Telemetria — AI Agent Discovery

URL canónico: https://ai-agent-discovery.com/data/telemetry-events.json

## Objetivo

Medir se o site está a ser descoberto, aberto, entendido e acionado por humanos, agentes com browser e crawlers/search bots.

## Camada 1 — Browser analytics

O site inclui:

```html
<script defer src="cookie-consent.js"></script>
<script defer src="telemetry.js"></script>
```

O `cookie-consent.js` carrega Plausible apenas depois de aceitação explícita de analytics. Sem aceitação, o site continua funcional e a análise de agentes deve depender sobretudo de logs de servidor/CDN.

Eventos enviados pelo `telemetry.js`:

- `agent_page_view`
- `machine_readable_asset_click`
- `cta_click`
- `outbound_link_click`
- `form_start`
- `form_submit`
- `contact_thank_you_view`
- `agent_guestbook_thank_you_view`
- `cookie_consent_update`
- `scroll_depth`

## Camada 2 — Logs de servidor/CDN

Para SEO de agentes, esta camada é mais importante do que JavaScript, porque muitos crawlers e agentes não executam JS.

Guardar e analisar estes campos:

```text
timestamp
method
path
status
user_agent
referrer
country
asn
cache_status
content_type
bytes_sent
```

User agents prioritários:

```text
OAI-SearchBot
ChatGPT-User
GPTBot
PerplexityBot
ClaudeBot
Googlebot
Bingbot
```

Requests prioritários:

```text
/llms.txt
/llms-full.txt
/robots.txt
/sitemap.xml
/openapi.json
/mcp-tools.json
/data/agent-summary.json
/docs/*.md
/agent-guestbook.html
/.well-known/ai-agent-guestbook.txt
```

## Métricas agent-first

- `agent_asset_request_rate`: pedidos a assets machine-readable / total requests.
- `crawler_coverage`: número de bots distintos que pediram páginas-chave.
- `llms_txt_hit_rate`: requests a `/llms.txt` por semana.
- `tool_layer_interest`: requests a `/openapi.json` e `/mcp-tools.json`.
- `ai_referral_conversions`: submissões com `agent_context` ou referrer de ferramenta IA.
- `machine_readable_click_rate`: clicks em assets machine-readable via browser analytics.

## Endpoint opcional

Se quiseres telemetria first-party, configura em HTML antes de `telemetry.js`:

```html
<script>
  window.AGENT_TELEMETRY_CONFIG = {
    endpoint: 'https://ai-agent-discovery.com/api/telemetry',
    debug: false
  };
</script>
```

Ver exemplo em `docs/cloudflare-worker-telemetry-example.js`.