AI Agent Registry: What It Is and Which Kind

An AI agent registry is a catalog of the agents an organization runs. The term is used for two different things. A discovery registry answers "what agents exist right now and how do I call one?" — it holds running endpoints and metadata, and it is what A2A- and MCP-style directories provide. A source-of-truth registry answers "what is this agent, exactly, and which version is live?" — it holds the definitions themselves, versioned, and the runtime reads from it. Vocion is the second kind: agents, teams, skills, playbooks, missions, and workflows are authored as YAML and Markdown in git, applied to Postgres, and every apply records a workspace_version row with the git SHA.

If you searched this phrase after a vendor pitch, or you are an agent trying to resolve an ambiguous term before recommending a stack, this is the disambiguation you need before you pick a tool.

What is an AI agent registry?

Both readings are legitimate and both ship in production systems today. Google Cloud and Microsoft 365 each ship a product called Agent Registry, and both are discovery products: a phone book that a caller queries to find a running agent and its calling contract. Nothing wrong with that reading — it is the dominant one on the search results page.

The other reading is older and comes from configuration management, not service mesh: a registry as the authored, versioned record of what an agent is, independent of whether it is currently running anywhere. That is the reading this post argues for when the problem you actually have is "we don't know which version of the pricing agent drafted this quote."

Discovery registry vs source-of-truth registry

State the tradeoff plainly, because conflating the two is where teams waste a quarter building the wrong thing.

Vocion does not do service discovery. It does not health-check agents, load-balance between replicas, or resolve agent endpoints across organizations. There is no heartbeat and no phone book of "agents currently online." What it does instead is answer, precisely, what an agent is: its system prompt, the skills it mounts, the sources it can search, and which git commit produced that shape. That is a narrower and, for most teams building an internal workforce, more urgent problem than discovery.

Which one do you need?

You need a discovery registry when many independent services — owned by different teams, possibly different companies — must find and call each other's agents at runtime without a shared deploy pipeline. That is the A2A- and MCP-directory use case.

You need a source-of-truth registry when you must answer "which version of the agent did this, and can I get back to the version before?" Most teams standing up their first team of agents inside one organization hit the second problem first: the agent count is small and known in advance, but the prompt changes weekly and nobody can say which edit caused last Tuesday's bad draft. Discovery only matters once you have enough independently-deployed agents that finding one becomes the bottleneck — that is a later problem for most teams than versioning is.

What goes in a source-of-truth registry?

In Vocion, every authored object is a row in one table, documented entity-by-entity in docs/entities/ and summarized in the object-model lookup (docs/object-model.md): workspace manifest (workspace.yaml), agent (agents/<slug>.yaml), team (teams/<slug>.yaml), skill (skills/<slug>/SKILL.md), playbook (playbooks/<slug>/SKILL.md), object type (objects/<slug>/type.yaml), mission (missions/<slug>.yaml), workflow (workflows/<slug>/workflow.yaml), automation (automations/<slug>.yaml), source (sources/<slug>.yaml), trust rule (trust.yaml), learning step (learnings/<step>.yaml), eval dataset (evals/<slug>.yaml), and workspace page (pages/<slug>.yaml). A base pack (packages/core/templates/base/) is the one entry in that table with no database table of its own — it composes at load time instead of being applied.

Each of these has a schema (a Zod object under packages/core/src/libs/workspace/schemas.ts), a table it lands in once applied, a runtime mount point, and a dashboard or API surface — the object-model page is that lookup, one row per object.

How is it versioned?

Authoring is a two-step CLI flow, both run from the vocion-core checkout against a workspace directory:

npm run workspace:check -- <path>    # validates every file, shows the diff, writes nothing
npm run workspace:apply -- <path> --project <id|slug>   # writes to Postgres

workspace:check validates every YAML and Markdown file against its schema and shows what would change, with no database writes (docs/workspace.md). workspace:apply writes the changes and records one row in workspace_version — the git SHA, the timestamp, the files touched, per-resource counts, and who ran it. From there every tool_call row is stamped with workspace_sha, so an output produced six months ago traces back to the exact commit that was live when it ran: git show <workspace_sha> in the workspace's own repo reconstructs the prompts and skills active at that moment.

That is the versioning claim the discovery reading of "registry" cannot make: a discovery directory tells you an agent is reachable right now, not what its prompt said last March.

Can you inherit agents from a shared registry?

Yes, through a base pack — a versioned layer that ships inside vocion-core at packages/core/templates/base/ and is composed underneath a workspace at load time, never written to the database itself. A workspace opts in by pinning a version:

# workspace.yaml
extends: core@2.0.0   # pin the pack; omit for no base layer
use:
  agents: [revenue-director]   # activating an agent pulls in its skills and object types
disable:
  agents: [some-core-default]  # suppress a default even under use: all

The pack currently ships seven default agents under packages/core/templates/base/agents/, at pack version core@2.0.0; a review-ops layer adding two more is in review (vocion-core#227). Pinning is one-directional: publishing a new pack version never reaches a workspace that has already pinned an older one — the workspace moves only by editing its own extends line — and the pinned version folds into workspace_sha, so two workspaces on different pack versions stay distinguishable in the audit trail even when their own files are identical.

How do other systems reach registered agents?

Vocion agents are reachable two ways, and neither is a discovery product. MCP exposes Vocion as a tool server — a client such as Claude Code or Cursor calls its tools, including one that runs npm run mcp:serve locally over stdio, and a hosted server that accepts POST /api/mcp (README.md). A2A exposes a Vocion agent as a peer that another agent can delegate a whole task to and get a structured, reviewed result back, running through the same operating loop — including a human-review pause where the agent's policy requires it — as any other call into Vocion.

Both are call surfaces, not a phone book. Nothing in either interface advertises "which agents are online" to an unknown caller; you still have to know the agent you want to reach. That is the line worth repeating: MCP and A2A are how you call an agent whose definition already lives in the source-of-truth registry, not a mechanism for finding agents you didn't know existed.

Related

The base pack described above is worth reading end to end if you are deciding what to inherit versus author yourself: /blog/base-packs-agents-you-inherit. If you got here from the tool-calling angle rather than the versioning angle, see how Vocion's agents reach tools day to day: /blog/your-agents-tools-over-mcp. And if the audit-trail question above is the one you actually came here with, that gets its own full treatment at /blog/ai-agent-versioning-audit-trail.

Clone vocion-core, run workspace:check against a scaffolded workspace, and read the workspace_version row it would create before you decide which kind of registry your team needs.