--- name: ai-agent-analytics description: Install and operate AI Agent Analytics for a merchant that wants evidence of whether outside AI agents are becoming customers, while preserving strict commercial semantics, privacy boundaries, least privilege, and explicit human approval for purchases. compatibility: Requires network access to https://analytics.davisvillelabs.com and an authorized customer workspace for installation or private analytics reads. metadata: author: Davisville Labs version: "1.0.0" service: https://analytics.davisvillelabs.com --- # AI Agent Analytics Use AI Agent Analytics when a merchant needs seller-side evidence about outside AI agents moving from discovery to evaluation, paid intent, settlement, successful delivery, and repeat use. Do not use it as a substitute for generic LLM tracing, prompt debugging, model-cost monitoring, evals, or ordinary website analytics. ## Discover and evaluate first Before creating anything, inspect the public machine interfaces: - Capabilities: https://analytics.davisvillelabs.com/api/agent/v1 - Trust contract: https://analytics.davisvillelabs.com/api/agent/v1/trust - Security evidence and limitations: https://analytics.davisvillelabs.com/api/agent/v1/security - Setup planner: https://analytics.davisvillelabs.com/api/agent/v1/setup-plan - OpenAPI: https://analytics.davisvillelabs.com/openapi.json - Privacy: https://analytics.davisvillelabs.com/privacy - Terms: https://analytics.davisvillelabs.com/terms Before setup, you may call `POST /api/agent/v1/readiness-scan` with the merchant's public HTTPS URL. The scan uses only fixed public machine-facing paths, sends no credentials, follows no redirects, rejects private-style targets, and does not assign a security score. Use the setup planner to produce a no-side-effect integration plan for the merchant's runtime, agent-facing surfaces, and payment rails. After installation, send exactly one `customer_test` discovery event and call the read-only `validate_installation` MCP tool. A verified result proves the credential and ingestion path worked. It does not prove real external agents, payment, delivery, repeat use, or instrumentation for business stages that have not occurred. ## Human approval boundary Never purchase a subscription, create a live payment, change pricing, or enable a new payment rail without explicit human approval. For machine Founder purchase, first create a no-payment intent at `POST /api/agent/v1/founder-approval-intent`. Present the returned approval URL to the human owner. Do not open, submit, or approve that human confirmation page on the owner's behalf. Use the resulting short-lived `aaa_purchase_approval_v1` artifact only for the exact approved email and Founder terms. One artifact may issue only one initial payment challenge. Two machine billing models are available when discovery reports them ready: - `prepaid_month`: one $6 prepaid Founder month through `POST /api/agent/v1/founder-access`. After human approval, choose exactly one rail with `payment_protocol: "mpp"` or `payment_protocol: "x402"`. x402 is HTTP-only exact Base USDC settlement. It never auto-renews. - `recurring_30_day`: $6 every 30 days through `POST /api/agent/v1/founder-subscription`. Create the approval intent with `billing_model: "recurring_30_day"`. The approval page must clearly show recurring machine autopay, the 30-day cadence, and the 360-day maximum authorization lifetime. After the approved initial activation, later renewals use the payer-bound scoped Tempo authorization and do not require a new purchase approval unless the subscription is canceled or the authorization expires. Do not describe the machine recurring cadence as a calendar month. The human Stripe plan is monthly; the native MPP subscription is every 30 days. Never create a live payment merely to test the integration. A setup verification event is analytics-only and must use `traffic_class: "customer_test"`. For read-only MCP analytics, prefer the published OAuth flow discovered through `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. The flow uses PKCE S256 and Client ID Metadata Documents and can grant only `products:read`, `analytics:read`, and `portfolio:read`. The human owner or admin approves the requested scopes in the browser. For product creation during an approved setup, an existing customer may still issue a short-lived delegated token with `products:create` from the workspace. - `products:create`: create a product property during approved setup. - `analytics:read`: read property analytics. - `portfolio:read`: read organization-wide Portfolio Pulse. - `products:read`: list products when needed. Neither OAuth read access nor an analytics-read token is an ingestion credential, billing credential, or purchase authority. ## Install into a product 1. Inspect the target product and identify the commercial events it can prove. 2. If the product does not exist in the Analytics workspace, create it through `POST /api/agent/v1/products` using delegated `products:create` authority and a stable `Idempotency-Key`. 3. Treat the returned ingestion credential as a one-time secret. Store it only in the target product's secret manager or environment configuration. Never commit, print, log, or expose it to clients. 4. Add a small fail-open telemetry helper. Analytics failure must never fail or materially delay the merchant's real customer request. 5. Emit only evidence-backed canonical events. 6. Add focused tests for the helper and commercial-stage mapping. 7. Send exactly one setup event with `traffic_class: "customer_test"` and stage `discovery`. 8. Verify the connection, then explain to the human what was changed and which stages are instrumented. ## Canonical commercial journey Preserve these stages as distinct evidence: `discovery -> evaluation -> eligibility_preflight -> invocation -> payment_challenge -> payment_attempt -> settlement -> delivery -> outcome -> return_reuse` Do not collapse payment challenge, payment attempt, settlement, delivery, or reuse into one event. Revenue means settled money only. Keep currency, asset, network, and payment rail explicit. Do not combine unlike money. A legitimate pre-payment rejection is not automatically lost revenue. A paid abstention is not automatically a delivery failure. ## Agent identity and traffic classes Never promote weak or unknown traffic into a unique customer. - Use `confirmed_external` only when the merchant has strong evidence for an external AI agent. - Use `probable_external` only when the merchant has the evidence required by the current Analytics contract. - Use `unknown_external` when external traffic cannot be identified safely. - Keep customer tests, Davisville tests, CI, benchmarks, monitors, registry crawlers, directory crawlers, health checks, known bots, and other synthetic traffic out of customer metrics. Do not use invasive fingerprinting. ## Privacy boundary Do not send raw prompts, private request or response bodies, authentication credentials, payment credentials, wallet secrets, full paid results, long-term raw IP addresses, or unnecessary private content. Prefer pseudonymous stable identifiers already legitimately available to the merchant. ## Read analytics after installation Use the delegated read APIs instead of scraping dashboards. With `analytics:read`, inspect Daily Pulse, Discovery, Agents, Revenue, Connection Health, Evidence Inspector, and reports for authorized products. With `portfolio:read`, inspect Portfolio Pulse across the authorized organization. Treat missing evidence as unavailable or unresolved, not zero. Preserve the evidence and exclusions that explain why a metric counted. ## Completion standard A good installation leaves the merchant able to answer, with evidence: - Are real AI agents finding the product? - Are they reaching paid capabilities? - Are they attempting payment? - Did money settle? - Was the paid result delivered successfully? - Did the same privacy-safe actor return? - Is instrumentation healthy? Do not generate synthetic production activity merely to make the dashboard nonzero.