This proposed event pattern is not a production ByAgents analytics feature. It is a design aid for an authorized first-party measurement system. Choose fields according to your actual consent, retention, and data-access requirements. Avoid collecting personal or sensitive information merely because an agent interaction exists.
Keep the event types distinct
| Event | What it establishes | What it does not establish |
|---|---|---|
| public_resource_requested | A request reached a public resource | Indexing, citation, or a person |
| referral_landed | An observed source accompanied a visit | The complete discovery history |
| evaluation_stage_observed | A controlled run reached a recorded state | An external prospect |
| inquiry_accepted | The business saved an inquiry | Qualification or revenue |
| activation_verified | A defined first-use outcome occurred | That AI caused the acquisition |
| order_confirmed | The commerce system recorded an order | Fulfillment, retention, or incrementality |
Define events from actual system state. If the server rejects a form, do not fire inquiry_accepted because the button was clicked. If a job starts but never finishes, do not count activation_verified unless the activation definition genuinely ends at submission.
Example envelope
{
"schema_version": "1.0",
"example": true,
"event_id": "example-event-001",
"event_type": "inquiry_accepted",
"occurred_at": null,
"environment": "example",
"traffic_class": "controlled_evaluation",
"resource_path": "/start",
"source": {
"observed_referrer_origin": null,
"provider_claim": null,
"verification_method": "none",
"attribution": "unknown"
},
"business_record_id": null,
"evaluation_run_id": "example-run-001",
"revenue": null
}This is illustrative data; no inquiry is claimed. Null revenue is unknown or inapplicable, not zero realized revenue. Do not publish real inquiry identifiers or attach raw emails to an openly accessible event stream.
Make verification an explicit field
A claimed user agent, observed referrer, verified network range, and validated signature provide different evidence. Record the method and when it was checked. Provider identity alone does not distinguish training, indexing, user-directed retrieval, or a purchase; use the documented role and observed operation.
A missing referrer should remain unknown. Do not classify direct visits as AI simply because agent traffic is difficult to measure. Campaign tags can describe a link you distributed but do not independently prove which application followed it.
Join only what you can support
Use a consent-appropriate first-party session or business identifier when available. Define deduplication and attribution windows before reporting trends. Count an event once by its event identifier and a commercial outcome once according to its business record. Preserve existing-account status where relevant.
Do not join a crawler IP to a human buyer by guesswork. An evaluation request can create a test business record; exclude or clearly label that outcome. When a customer reports an AI-assisted decision without a traceable referral, record self-reported assistance separately from observed acquisition.
Reconcile against operational records
For inquiries, compare accepted submissions with stored records. For APIs, compare activation events with a completed result. For commerce, account for cancellations, refunds, and repeat orders according to a documented policy. An event pipeline can be internally consistent and still use the wrong definition of success.
Report raw counts and uncertainty alongside rates. Platform impressions and citation reports are separate evidence streams, not interchangeable session events. The measurement guide explains how to combine them without claiming a universal agent-traffic number.