Abstract
This specification defines how an organization records the activity of outside AI agents (the pages they fetch, the questions they ask, the actions they attempt) and the outcomes that follow, and how it exports those records so that two tools count the same week the same way. It defines four entities, six event types, a field for how sure the recorder is about an agent's identity, rules for counting repeats, and a JSON Lines export format.
Status of this document
Version 0.1.0 is a first draft, open for public comment until 2027-01-31. Definitions, window lengths and the export format may all change. Comment on GitHub or through the form on the proposal's page.
1. The problem
Every analytics tool, content delivery network and "AI visibility" vendor counts agent activity its own way. One organization can see three numbers for the same week: one counts every request, one counts sessions, one counts only agents it can name. Nobody can say which is right, because nobody defined what is being counted.
Cloud spending had the same problem until the FinOps Foundation's FOCUS specification gave every provider one way to describe a bill. This specification aims to do for agent activity what FOCUS did for cloud bills: one shared description of the data, so numbers can be compared and trusted.
2. Scope
In scope: activity by software agents that act for a person or an organization (a principal) and reach the recording organization over the web, an API, an MCP server, an A2A endpoint or a similar interface.
Out of scope: activity by people using a browser themselves; search-engine indexing that serves no agent; the organization's own agents acting inside its systems; how an organization detects agents (the specification records what was concluded and how sure the recorder is, not the detection method).
3. Terms
- Recorder: the system that writes the records (a web server, a CDN, an analytics tool, an MCP server).
- Report: any total computed from the records.
- Resource: anything an agent can fetch or call: a page, a file, an API endpoint, an MCP tool, an A2A skill.
4. Entities
4.1 Agent
The software that visited or acted.
| Field | Required | Meaning |
|---|---|---|
agent.name |
MUST | The agent's name as identified, for example ClaudeBot or ChatGPT-User. unknown when not identified. |
agent.operator |
SHOULD | The organization that runs the agent, for example Anthropic. |
agent.kind |
SHOULD | One of crawler (collects content for later use), fetcher (fetches for a person, now), assistant (converses and acts for a person), autonomous (acts for a principal without a person present). |
agent.identity |
MUST | How sure the recorder is about the name: see section 6. |
4.2 Principal
The person or organization the agent acts for, when known. A recorder MUST NOT export a principal's personal data (name, email, phone, address, IP address). It MAY export a pseudonymous principal.id that is stable within one export and MUST NOT be reversible by the receiver.
| Field | Required | Meaning |
|---|---|---|
principal.id |
MAY | A pseudonymous identifier. |
principal.type |
MAY | person, organization or unknown. |
4.3 Organization
The party being visited: the site, brand or business that records the activity. One export describes one organization.
| Field | Required | Meaning |
|---|---|---|
organization.id |
MUST | The organization's primary domain, for example example.com. |
4.4 Interaction
One continuous exchange between an agent and the organization. It groups events. An interaction begins with the agent's first event and ends after 30 minutes without an event from the same agent and principal (or the same agent and client address when there is no principal). A recorder that uses a different timeout MUST state it in the export header.
5. Events
Every event has these fields:
| Field | Required | Meaning |
|---|---|---|
id |
MUST | Unique within the export. |
type |
MUST | One of the six types below. |
time |
MUST | When it happened, RFC 3339 in UTC, for example 2026-11-20T09:15:02Z. |
interaction_id |
MUST | The interaction it belongs to (section 4.4). |
agent |
MUST | The agent object (section 4.1). |
principal |
MAY | The principal object (section 4.2). |
channel |
MUST | web, api, mcp, a2a, feed or other. |
resource |
SHOULD | The URL path, endpoint, tool or skill involved. |
The six types, and the fields each adds:
| Type | Records | Adds |
|---|---|---|
visit |
An agent fetched a page, file or endpoint. | status (the response status). |
question |
An agent asked something, in words or through a tool call. | topic (MAY, a short label; never the question's text when it may contain personal data). |
answer |
The organization replied. | question_id; result: answered, partial, refused or error. |
action |
An agent attempted to apply, book, quote, buy, join or the like. | action (a verb from AR-2 Invitations to Act where one fits); result: completed, handed_to_person or failed. |
failed_task |
A question or action could not be completed. | related_id; reason: not_found, not_supported, auth_required, blocked, error, limit or other. |
outcome |
A result that followed: a hire, a booking, a sale, a signup. | outcome (a label); related_id (the action, when known); value and currency (MAY). |
A recorder MAY add fields of its own under the prefix x_. A receiver MUST ignore fields it does not know.
6. Identity confidence
agent.identity says how the recorder knows who the agent is:
| Value | Meaning |
|---|---|
inferred |
Concluded from behavior or patterns, with nothing the agent stated. |
claimed |
The agent stated its name (for example in its user agent) and nothing confirmed it. |
signed |
The request carried a valid signature that ties it to the operator, for example under Web Bot Auth. |
verified |
Confirmed by an authenticated relationship: OAuth, an API key, a client ID metadata document or an equivalent. |
Reports SHOULD break totals down by identity confidence, or state which levels they include.
7. Counting repeats
Agents retry and fetch the same thing many times. To count the same way:
- Two
visitevents by the same agent, principal (or client address) and resource within a deduplication window count once in reports. The default window is 60 seconds. - Exports MUST keep every event; deduplication applies to reports only.
- Every report MUST state the window it used, so two reports can be compared.
8. Standard reports
A conforming tool SHOULD offer these, for a stated period:
| Report | Definition |
|---|---|
| Agent visits | Deduplicated visit events. |
| Agent interactions | Distinct interaction_id values. |
| Answer rate | answer events with result answered, divided by question events. |
| Task success rate | action events with result completed, divided by all action events. |
| Outcomes | outcome events, by label, with total value where recorded. |
Each report states its period, deduplication window, interaction timeout and the identity levels included.
9. Export format
An export is a file of JSON Lines: UTF-8, one JSON object per line. The first line is a header; every other line is an event.
The header:
{"spec": "agent-activity-measurement", "version": "0.1.0", "organization": {"id": "example.com"}, "period": {"start": "2026-11-01T00:00:00Z", "end": "2026-11-08T00:00:00Z"}, "interaction_timeout_seconds": 1800, "recorder": "example-analytics 4.2"}
An event:
{"id": "e-102", "type": "action", "time": "2026-11-03T14:02:11Z", "interaction_id": "i-17", "agent": {"name": "ChatGPT-User", "operator": "OpenAI", "kind": "fetcher", "identity": "signed"}, "channel": "web", "resource": "/book", "action": "book", "result": "completed"}
The JSON Schema for the header and events is in schemas/activity-measurement/0.1/, and a sample export in examples/activity-measurement/.
10. Conformance
A conforming recorder writes every MUST field, uses the values defined here, states any non-default timeout and exports valid JSON Lines. A conforming report follows section 8's definitions and states its parameters. A product may say it implements this specification at a stated version.
11. Privacy
Agent activity often involves people. A recorder MUST NOT put personal data in an export (section 4.2), SHOULD drop client addresses after grouping interactions, and MUST NOT record the text of questions or answers in an export unless the principal agreed. Exports between organizations are subject to the law where the principal lives.
12. Open questions
- Is 30 minutes the right interaction timeout for agents, which may pause for minutes between steps of one task?
- Should
visitdeduplication use 60 seconds, or the HTTP cache lifetime of the resource? - Do the four identity levels separate cases that matter, or should
signedandverifiedmerge? - How should an
outcomebe tied to an agent when it happens days later, through a person? - Should the export also define a streaming form (for example over OpenTelemetry), not only files?
Changes
0.1.0 (2026-11-20)
First public draft. Opened for comment until 2027-01-31.