The Agent Listing Model

A vocabulary for describing an agent in a directory: what it reaches, who it is for, where it came from, and which parts of it anyone actually checked. It is a profile of ARD, not a replacement for it, and any directory can adopt the field names without adopting anything else.

version 0.1 draft

Why it exists

An ARD entry and an A2A agent card both describe how to reach an agent. Neither describes what the agent reaches back into, who it was built for, what it is allowed to do once you connect it, or which of its claims anybody verified. Those are the questions a person asks before hiring one, and every directory currently invents its own answers, so the same agent reads differently depending on whose list it landed on.

This model is that missing half, written down. It says nothing about transport, addressing or protocol, because ARD and A2A already do.

The rule this model exists for

A listing must distinguish what somebody checked from what the publisher claimed. Directories today render both at the same visual weight, which quietly converts a seller's assertion into the directory's endorsement.

The fourth state is the strongest and the least common, and it is worth separating from attestation rather than folding into it. An attestation is somebody's assertion whose signature you can verify. A computed figure is one whose content you can verify, without trusting the directory or the party that published it. Reputation is the usual instance: Agent Reputations publishes its scoring formula and its constants so that anyone holding the evidence pool arrives at the same score, which is what separates a score from an opinion with a haircut.

Four consequences follow, and a listing that skips them is not conforming:

• Every rendered field carries its state. A checked field says when it was checked and what the check was. A computed field names the formula and where the evidence can be read.
• Absent means the publisher has not said. There is no default in either direction. Reading silence as a promise invents one; reading it as a failing accuses the honest.
• A filter fails closed. An agent that has not answered a question never matches a requirement stated about it.
• A computed figure never renders without its sample size, and leads with the lower bound of its interval rather than its mean. Too few observations to say, and never enrolled at all, are shown as what they are. Neither is a low score, and neither is an absence.

What a listing says

Four groups. The first two are what a reader wants; the last two are what they need when something goes wrong.

1. What it does, and who for

Audience is two fields, not one, and the second is the one nobody thinks to ask. A gradebook agent is for teachers and touches nobody else. A tutoring agent is bought by a school, configured by a teacher, and talks to a child. The same split runs through clinician and patient, recruiter and applicant, advisor and retail investor, and in every pair the second population is the regulated one.

2. What it reaches

Three lines that decide what a reader does next. An agent that brings its own scope can be called this afternoon. An agent that needs yours cannot do anything until somebody provisions it and reviews what it will see.

3. Where it came from

Four questions and a state. These are what a directory should store; the archetype labels people actually recognise are derived from them, never the other way round.

4. Who is behind it

One party is rarely the truth. An agent built on a vendor platform, configured by an agency and operated inside a company has three names attached to three different scopes, and the reader's real question is who to call when it misbehaves.

The last one is deliberately a pointer rather than a number. A listing carries the figures and says where they came from; it does not compute them, and a directory that scored the agents it lists would be marking its own homework.

What a directory can actually check

Most of the model is declared, and saying so is the point. These are the parts a directory can test for itself, and each one should be published with the date it was tested and a plain description of the test.

A publisher who wants more of their listing to read as checked makes more of it checkable. That is the incentive this model is trying to create.

How it travels

ARD's metadata is an escape hatch for key-values, not for documents: v1.0 declares its values as string, number, boolean or null, so a nested object makes the entry invalid. The model therefore travels as flat dotted keys under a listing. prefix, with lists of scalars comma-joined and anything structural published beside the entry rather than stuffed into a string.

// inside an ARD entry
"metadata": {
  "listing.job": "bookkeeper",
  "listing.for": "small business owners",
  "listing.touches": "none",
  "listing.coverage": "us, en",
  "listing.edge": "declines",
  "listing.may": "read",
  "listing.written_by": "developer",
  "listing.run_by": "builder",
  "listing.open_to": "anyone",
  "listing.acquired_by": "call",
  "listing.state": "listed",
  "listing.serves": "hirer",
  "listing.outcomes.bureau": "https://agentreputations.com",
  "listing.outcomes.subject": "UA4SC46GPJYFTSL5NJFTZB5CB3CADWDPOVBRORJBQSZ74QD5DQOL4ATU"
}

A directory that is not publishing ARD can use the same field names in whatever shape it already has. The vocabulary is the useful part; the carriage is not.

Where one entry has more than one address

An agent can be a public repository and a running endpoint at the same time, and it should be one listing rather than two: two listings put the same agent in results twice and split its identity.

ARD cannot express that on its own. Its entries carry url exclusive-or data, one address each, and that rule is not worth bending. So the primary address stays exactly where ARD wants it and the others travel as indexed keys, each carrying its own state:

  "listing.distributions.0.kind": "source",
  "listing.distributions.0.url": "https://github.com/example/ledger",
  "listing.distributions.0.state": "packaged",
  "listing.distributions.0.license": "Apache-2.0",
  "listing.distributions.1.kind": "endpoint",
  "listing.distributions.1.url": "https://ledger.example.com/rpc",
  "listing.distributions.1.state": "listed"

Be clear about what this buys and what it does not. A reader who has never heard of this model still gets a valid entry with one working address, and loses only the extra distributions. The one-listing promise holds for readers who adopt this profile and for nobody else, which is a real limit rather than something ARD grants you.

What this deliberately does not do

• It does not name archetypes. Categories like "marketplace agent" or "studio agent" are useful on a submission form and useless in a standard, because they are pinned to vendor product tiers that get renamed on somebody else's release schedule. Store the coordinates; derive the label; let the label churn.
• It does not rank or rate. Nothing here is a quality signal, and nothing here moves an agent up a result list. Trust may be filtered for; it must not float. That rule is ARD's, and reputation is what makes it load bearing rather than tidy: a recomputable score that also moved ranking would stop being the thing buyers read and become the thing sellers farm. Quality has its own standard, and this model points at it rather than restating it.
• It does not describe transport. Addressing, protocol and authentication belong to ARD and A2A, which already carry them.
• It does not standardise price. Commercial terms are their own document, and a listing points at one rather than restating it.

Status

Version 0.1, draft. The field names are expected to move before they settle. If you run a directory and want to use this, or think a field is wrong, the useful thing to send is the listing it fails on.