At a glance

Status
Public comment Version 0.1.0, updated November 20, 2026.
Comment period
November 20, 2026 to January 31, 2027. Open now.
Editors
Institute for Agent Relations staff
Source
proposals/activity-measurement.md in the Institute’s specifications repository, published on GitHub soon.
License
Text CC BY 4.0; schemas and examples Apache 2.0.

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:

  1. Two visit events by the same agent, principal (or client address) and resource within a deduplication window count once in reports. The default window is 60 seconds.
  2. Exports MUST keep every event; deduplication applies to reports only.
  3. 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

  1. Is 30 minutes the right interaction timeout for agents, which may pause for minutes between steps of one task?
  2. Should visit deduplication use 60 seconds, or the HTTP cache lifetime of the resource?
  3. Do the four identity levels separate cases that matter, or should signed and verified merge?
  4. How should an outcome be tied to an agent when it happens days later, through a person?
  5. 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.

Comment on AR-1

Open until January 31, 2027. Anyone may comment, and every comment gets a public answer.

Comments follow the process and the code of conduct.

← All proposals