Why Your AI Agent Framework Needs a Registry, Not a Framework

A new AI agent framework ships almost every week — a fresh way to chain LLM calls, a new tool-calling syntax, another orchestration pattern with its own diagram. Meanwhile the question enterprise teams actually ask sounds nothing like "which framework should we pick": it is "we have a dozen agents built by three different teams, none of them aware the others exist — how do we even find out what we've got?"

That question has nothing to do with frameworks. It is a registry problem, and almost nobody is building for it.

The Framework Trap

A framework earns its keep at build time. It handles prompt construction, tool dispatch, memory, the mechanics of talking to an LLM API. All of that matters — but it stops mattering the moment the agent ships, because a framework has no opinion about what happens next.

And what happens next is where the real questions live: how many agents are actually running. What each one is allowed to touch. Whether two of them are quietly duplicating the same job. Who gets paged when one misbehaves. None of these are things a framework was ever designed to answer, because a framework's whole job ends at deployment.

The pattern is recognisable before it has a name. A support team ships a triage agent; three months later an ops team ships a near-identical one, unaware the first exists, because there was nowhere to check. Production breaks and the on-call engineer cannot get a straight answer to "which agents touched this account in the last hour" — not because the answer doesn't exist, but because nothing recorded it. A security reviewer asks for every agent with write access to customer data and the honest reply is a shrug. In every case the agents themselves were built competently. The framework did exactly what it promised. What was missing was somewhere to look them up.

This is also why "let's standardise on one framework" doesn't fix it. Picking a single build tool company-wide says nothing about how many agents that tool built. The tool was never asked to keep count. It was built to help one team ship one agent, not to answer "how many of these do we have." It's the same root cause behind why most agentic AI projects fail in production: the build was fine, but nothing tracked what got built.

What Registries Already Solved, Twice

Container registries — Docker Registry, ECR, GCR, Harbor — settled this exact problem for software a decade ago, by drawing a hard line between how you build something and what exists. The Dockerfile stayed the build tool. The registry became the separate, queryable record of every image: which ones exist, where they live, which version is which, what's inside them.

The value that unlocked is easy to underrate until you list it out. A tag plus a content-addressed digest turns "which version is actually live" from a question you ask a person into a lookup anyone can run. Promotion between environments becomes a metadata operation — the same image gets re-tagged from staging to production instead of rebuilt from scratch at each stage, which quietly removes an entire failure class ("it worked in staging because the build there was subtly different"). A vulnerability scanner wires into the registry once and covers every image that ever passes through it, rather than every team bolting on its own. And when something breaks, the registry's history answers "what was running at 3pm yesterday" without anyone reconstructing it from memory.

None of that came from a smarter build tool. It came from having one place, external to any single build, that recorded what existed. The pattern repeats past containers too. The Open Container Initiative's image-spec standardised what a registry entry means across every vendor implementing it. The Terraform Registry and the Helm chart repository format applied the same idea to infrastructure modules and Kubernetes packages — different artefact, same separation between the tool that builds it and the catalogue that tracks it.

AI agents are the next artefact that needs exactly this, and right now almost nobody has built the catalogue.

The Agent Registry

An agent registry is the authoritative record of every AI agent an organisation runs — not how each one was built, but what exists, what it can do, and who answers for it.

1. What agents exist?

Every agent gets a unique identifier, a plain-language name, a role, and an owning team, in one shared place. Ask most organisations "how many agents do you run" without a registry and the honest answer is "we don't actually know" — agents get spun up in a script here, a notebook there, a Slack bot somewhere else, each with no shared record of its existence. A registry entry is the line between an agent that only its builder knows about and one anyone with a reason to look can find.

2. What is each agent allowed to do?

The registry holds the tool manifest: exactly which tools an agent can call, with their schemas. That turns "what could this agent possibly have done" from forensic archaeology into a lookup — when a security review asks which agents can write to the billing database, the manifest answers directly instead of someone reading every agent's source line by line. It's also what makes least-privilege access enforceable at scale rather than aspirational: a tool is either on the list or it isn't, and the list is auditable independently of the agent's code.

3. How are agents organised?

Agents coordinate in teams with an explicit pattern; teams sit inside spaces — department or domain boundaries with their own access rules. This layering matters because most "agent sprawl" isn't really sprawl, it's isolation: dozens of individually useful agents that nobody can compose into anything bigger because nothing groups them. A registry turns a pile of point solutions into a system someone can reason about, extend, and hand off without starting over.

4. What is each agent's operational state?

Every agent carries a lifecycle: active, paused, shadow, deprecated — plus when it last ran, how long it took, whether it succeeded. This is the operational layer a framework simply doesn't offer, because its view stops at deployment. "Shadow" earns its own mention: it lets a revised agent run alongside the one it's replacing, observed but not yet acting, so a team can compare behaviour before cutting over — a staged rollout that otherwise gets improvised from scratch per agent instead of being a lifecycle state everyone already understands.

5. Who is accountable for it?

Every agent is tied to an owner, a space, and an access boundary. When something goes wrong, "who owns this" should be a lookup, not an investigation. Most AI deployments skip this entirely, because nothing forces the question — a framework will happily let an agent ship with no named owner and no documented scope, and it runs identically either way. A registry makes ownership a required field rather than a hoped-for convention.

6. What has it actually done?

Past current status, the registry is the audit trail — every run, every tool call, every handoff, timestamped and attributable. This is what turns "an agent did something wrong" from a mystery into an investigation with a starting point, the same way a service outage's logs give an on-call engineer somewhere to begin.

This Isn't Theoretical — It's What We Run On

We didn't just argue for this; we built it, because we hit the exact problem this article describes while building our own AI agent operating infrastructure. Tutorwise's Conductor platform runs on an agent_tools registry table (migration 506, renamed from an earlier analyst_tools table once it stopped being analyst-specific). Per tool, it stores whether the tool is admin-only, whether it needs user context, whether it's safe to run in parallel, whether it's destructive, whether it requires human approval, its cost tier, and its circuit-breaker configuration. Every specialist agent's tool access resolves against that table, not against whatever a given agent's code happens to import — which is the manifest idea in section 2 above, not as a proposal but as a live constraint.

The audit trail in section 6 is equally concrete. agent_action_log and agent_action_idempotency (migration 560) record every mutating tool call an agent makes — input, output, confidence, dry-run flag, and an outcome status: success, failed, blocked on low confidence, blocked as a duplicate, blocked on a compliance rule, or refused by the user. Each call is deduplicated on a 24-hour key, so a retried action never double-fires. When an agent does something wrong, the question "what did it actually do" is a query against that table, not a reconstruction from memory.

The organisational layer holds too: teams run as Supervisor, Pipeline, or Swarm patterns compiled from a stored graph of nodes and edges at execution time, and every team sits inside an agent_spaces row — a real department boundary in the database, not a folder convention. None of this proves every organisation should copy our schema. It proves the registry isn't a nice diagram — it's the layer that made it possible to answer "which agent touched this" without anyone needing to remember.

The Three-Level Hierarchy

Level 1 — Agents. The individual unit of capability, the container-image equivalent: one job done well, a defined tool manifest, a named owner. A framework helps you build this unit; a registry is what lets you find it again in six months.

Level 2 — Teams. Coordinated groups running one of three patterns. Supervisor — one agent plans and delegates to specialists, then assembles their output — fits most enterprise workflows and is the shape our own devops-team and content-team both run. Pipeline suits a fixed sequence where each agent hands off to the next in a set order. Swarm suits work where the right division of labour genuinely isn't known ahead of time and agents need to negotiate it dynamically. Picking the wrong one is a common early mistake: a Swarm where a Pipeline would do adds coordination overhead for nothing, and a Pipeline forced onto Swarm-shaped work snaps the moment the task doesn't fit the fixed sequence.

Level 3 — Spaces. Department or domain boundaries — finance agents cannot see HR agents' data unless explicitly granted. This exists because "every agent in one flat list" fails for the same reason "every employee with no reporting lines" would. Spaces let each department own its agents and its own review process while the registry still gives the wider organisation one place to query across all of them.

What Actually Changes

The difference shows up first in what used to require asking around. Onboarding a new agent stops being "tell a few people" and becomes registering it — discoverable by default from that point on. A security review stops being weeks of reading through every team's codebase and becomes a handful of registry queries. Incident response stops with "let me go find out who might know" and starts with a lookup that returns a definite answer. None of this needs a better agent to be written. It needs somewhere to look.

The Uncomfortable Truth

The agent ecosystem is infatuated with frameworks because frameworks are fun to build and easy to demo. Registries are not fun — they are infrastructure: boring, unglamorous, and the reason everything built on top of them keeps working. It's a large part of why the Model Context Protocol's growing emphasis on standard tool manifests and discovery is worth watching. The industry is converging on "describe what a tool is and does in one shared shape" — that's the registry instinct arriving at the protocol layer, even where nobody calls it that yet.

History is fairly blunt about which layer wins. npm has outlasted every JavaScript framework built on top of it. Docker Hub outlived Docker Swarm. The Python Package Index will outlive whichever ML framework is fashionable this year. Maven Central has quietly outlasted three generations of Java build tooling. The registry keeps working because it solves a problem that never goes out of fashion — knowing what you actually have.

If you're building AI agents at any scale, the question worth asking isn't "which framework next" — it's "where is our registry, and can it answer who owns what."

FAQ

Is an agent registry the same thing as an orchestration framework? No. A framework is a build-time tool — it helps a team construct one agent. A registry is a runtime catalogue — it records every agent that exists across the whole organisation, independent of which framework built it.

Do we need a registry if we only have a handful of agents? The lookup problem starts small and compounds. Two agents built by the same person rarely collide; a dozen agents built by three teams over a year reliably do, because nothing forces anyone to check what already exists before building the next one.

What's the minimum a registry needs to track? At minimum: a unique identifier and owner per agent, the tools it's authorised to call, its current lifecycle state, and a log of what it has actually done. Team structure and department-level access boundaries matter once an organisation has more than a handful of agents working together.

Does a registry replace access control at the tool or database level? No — it sits above it. The registry records which tools an agent is authorised to call; the underlying systems still need to enforce that boundary. The registry is what makes the authorisation list auditable, not a substitute for enforcing it.

Can an existing framework be extended into a registry instead of building one separately? In principle, but the two solve different problems at different layers — build-time mechanics versus runtime catalogue — and conflating them tends to produce a framework that's harder to swap out later, not a registry that's easier to query.