Registry

What it is

The Registry is VerifAIer's persistent agent registry. It coordinates each agent's identity, trust profile, passport and reputation records under one stable, content-derived agent id.

Why it exists

Assessments are per-operation; the Registry gives you a persistent subject: the same agent resolves to the same id across executions, so trust and reputation accrue to a real thing over time.

When to use it

Use it to record an observation of an agent and to list or fetch agents for the Dashboard and Control Center.

Where it fits / architecture position

It sits between evidence and the fleet view, the Control Center overview aggregates exactly what the Registry holds.

Typical workflow

• observe an agent from an evidence envelope, it is registered and its latest posture updated.
• list agents, or get one by id.

Step-by-step usage

The Registry endpoints are open, no authentication required:

# observe (register/update) from evidence
POST /api/v1/registry/observe        { "evidence": { ... } }

# list / get
GET  /api/v1/registry/agents
GET  /api/v1/registry/agents/{agent_id}

Inputs and outputs

Inputs: observe accepts evidence (and optionally explicit identity, trust_profile, passport, reputation). Outputs: a registry entry with the linked record ids, operation_count, and latest trust/reputation/passport status.

Real example

On a fresh install the list is empty, verified against the running server:

curl -s http://localhost:8000/api/v1/registry/agents

{
  "agents": [],
  "count": 0
}

After a first audit + observe, the same call returns one agent with latest_trust_score: 100 and an active passport.

Expected results

• observe: a registry entry keyed by a stable agent_id.
• list: { "agents": [...], "count": N }.
• get an unknown id, 404.

Common mistakes

• Expecting a new id per call, the agent_id is content-derived, so the same agent is stable across observations.
• Forgetting to observe before the Dashboard/Control Center can show an agent.

Troubleshooting

• Empty list: nothing observed yet, run an audit then observe.
• 404 on get: the id has never been observed.

Related documentation

• Agent Identity: how the id is derived.
• Control Center: the aggregate view.
• API reference: the full endpoint list.