Agent Registry: A Governed Index for Every Worksona Agent

Agent Registry is a React and TypeScript application that serves as a centralized management layer for every agent in the Worksona ecosystem. It stores agent definitions in a local IndexedDB database (via Dexie.js), tracks their full version history, exposes full-text search across all agent metadata and associated documents, and can deploy agents as queryable endpoints.

The project has no backend. All data lives in the browser through IndexedDB. This is a deliberate local-first design: the registry is portable, privacy-preserving, and runnable without a server.

What is it?

The database schema captures everything meaningful about an agent:

// agents table
{
  id: string;           // UUID
  name: string;
  description: string;
  systemPrompt: string;
  config: object;
  version: string;
  tags: string[];
  category: string;
  status: "active" | "inactive" | "deprecated";
  createdAt: Date;
  updatedAt: Date;
}

Alongside agents, the schema maintains versions (immutable snapshots with changelogs), endpoints (deployed URLs with status), and documents (files associated with each agent).

Why is it useful?

Without a registry, agents accumulate as flat files. The Worksona portfolio already includes 100+ agent definitions across teams, MCP servers, and local JSON files. Flat files do not answer the questions that matter at scale: which agent handles competitor research? Which version of the writer agent is deployed? What changed between v1.2 and v1.4?

The registry answers all of these. Four capabilities drive the value:

Storage with rich metadata. Every agent gets a name, description, tags, category, status, system prompt, and configuration block. These fields are not decorative — they are the inputs to search and discovery.

Immutable version history. Once a version is created, it cannot be modified. This means the registry functions as an audit trail. When an agent behaves unexpectedly after an update, you can compare the current version to the previous one and identify the change.

Full-text search. The SearchService indexes agent metadata and attached documents. You can search by name, tag, category, or status:

GET /api/agents?q=research&tags=analysis&category=data-engineering

Endpoint management. Agents can be deployed as queryable endpoints and monitored from the registry's control panel. This creates a path from agent definition to agent runtime without leaving the same interface.

How and where does it apply?

The registry occupies the management layer of the Worksona stack. Other projects either store agents as filesystem content (flat JSON files, YAML definitions) or load them at runtime without lifecycle tracking. The registry is the only project that treats the agent roster as a versioned, searchable dataset.

The architecture makes this layer easy to extend. Adding a new metadata field means updating the TypeScript Agent interface and running a Dexie migration — the UI picks it up automatically. Swapping IndexedDB for a REST backend requires only wrapping AgentService with an HTTP client; the rest of the application does not change.

The natural integration targets are clear: agent-mcp loads its agents from filesystem directories and would benefit from registry-backed versioning and search. worksona-teams stores 100+ agent JSON files that could be imported into the registry as a managed dataset. A sync backend could replace IndexedDB for multi-user scenarios.

For any team running more than a handful of agents, the registry converts an unmanaged collection into a governed, discoverable catalog. That shift — from files to records with history — is what makes dynamic agent selection possible in orchestration scenarios. A coordinator agent can query the registry by capability tag and receive the current, active, matching agent definition without knowing anything about the underlying filesystem layout.