Agent Registry Providers

The base AgentRegistryProvider contract is part of the donmai OSS runtime. This page covers the Rensei-specific provider implementations, the capability-flag dispatch model, and how to connect external registries. For the low-level interface definition, see donmai.dev/docs/agent-registry-provider.

Agent Registry Providers (ARPs) are the fourth provider family in Rensei's layered execution model. An ARP owns the agent catalog for an organisation: it knows which agents exist, what version history is available, and - for providers that opt in - how to resolve a session's pinned version.

Provider capability flags

Every ARP declares a typed capability struct at registration time. The dispatch path branches on capability flags rather than provider identity:

Prop

Type

Available providers

`db` - Internal database provider

The default provider for all Rensei-managed Agent Cards.

Capability	Value
`supportsVersionPinning`	`true`
`supportsListing`	`true`
`supportsWrite`	`true`

All cards authored via POST /api/agent-cards or the UI land in this provider. Version history is maintained in the agent_cards table with a monotonic integer version column. The 4-scope cascade (system → org → project → workflow) is enforced here.

`a2a-peer` - A2A peer agent provider

Resolves Agent Cards from registered external A2A peers. The card is fetched live from the peer's .well-known/agent-card.json endpoint and normalised into the ResolvedAgent shape.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true` (via discovery doc)
`supportsWrite`	`false`

Because A2A peers don't support version pinning, any agent_session_pins row for a peer-backed agent is silently ignored and an agent.pin-ignored event is emitted. Sessions always run against the peer's current head.

`kit` - Kit provider

Resolves agents bundled inside a donmai Kit (e.g. an e2b or Vercel kit). The kit's kit.manifest.yaml declares agent definitions alongside tool bindings and environment requirements.

Capability	Value
`supportsVersionPinning`	`false` (kit version controls agent version)
`supportsListing`	`true`
`supportsWrite`	`false`

See Kits documentation for kit authoring details.

`git-hosted-yaml` - Git-hosted YAML provider

Reads agent definitions from YAML files in a Git repository. Useful for teams that want agent definitions under version control alongside application code.

Capability	Value
`supportsVersionPinning`	`false` (git SHA controls version; no DB version history)
`supportsListing`	`true` (directory scan)
`supportsWrite`	`false` (writes go through git)

Configuration:

provider: git-hosted-yaml
config:
  repoUrl: https://github.com/acme/agent-definitions
  branch: main
  path: agents/       # directory to scan for *.agent.yaml files
  credential: github  # credential name for private repos

Agent YAML files in the configured directory are discovered at reconcile time and materialised into the agent_cards table as reconciled rows (not user-authored rows - the source of truth remains the git repo).

`smithery` - Smithery registry

Resolves agents from the Smithery public agent registry. Agents are fetched by MCP tool name and normalised to the ResolvedAgent shape.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

`tessl` - Tessl registry

Resolves agents published in the Tessl platform.

Capability	Value
`supportsVersionPinning`	`true`
`supportsListing`	`true`
`supportsWrite`	`false`

`vertex-agents` - Google Vertex AI Agents

Resolves agents from a configured Vertex AI Agent Engine workspace.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

Requires GOOGLE_APPLICATION_CREDENTIALS or Workload Identity in the execution environment.

`openai-assistants` - OpenAI Assistants

Resolves agents from the OpenAI Assistants API.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

`langchain-hub` - LangChain Hub

Resolves agent definitions published in LangChain Hub.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

`agentskills` - AgentSkills registry

Resolves agents from the AgentSkills marketplace.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

`file` - Local file provider

Resolves agent definitions from YAML files on the local filesystem. Used in development and testing, and as the fallback when donmai.dev runner is operating without a network connection to the platform.

Capability	Value
`supportsVersionPinning`	`false`
`supportsListing`	`true`
`supportsWrite`	`false`

Capability matrix at a glance

Provider	Pinning	Listing	Write
`db`	Yes	Yes	Yes
`a2a-peer`	No	Yes	No
`kit`	No	Yes	No
`git-hosted-yaml`	No	Yes	No
`smithery`	No	Yes	No
`tessl`	Yes	Yes	No
`vertex-agents`	No	Yes	No
`openai-assistants`	No	Yes	No
`langchain-hub`	No	Yes	No
`agentskills`	No	Yes	No
`file`	No	Yes	No

Version resolution logic

The dispatch path (resolveAgentForSession) follows this algorithm regardless of which provider backs the card:

Call provider.resolveAgent({ orgId, name }) to get the latest definition and its id.

If provider.capabilities.supportsVersionPinning === false, return immediately with pinFallbackToLatest set to true if a pin row existed (for telemetry).

Query agent_session_pins for (sessionId, definitionId). If no pin, return the latest resolution.

If the pin's versionNumber matches the latest, return the row we already have (avoids a second DB round-trip).

Otherwise call provider.resolveAgent({ orgId, name, pinnedVersion: pin.versionNumber }) and return that version.

The `ScopedAgentRegistryProvider` interface

For providers that also participate in the scope cascade and reconcile lifecycle, Rensei extends the base AgentRegistryProvider with the ScopedAgentRegistryProvider interface:

interface ScopedAgentRegistryProvider extends AgentRegistryProvider {
  // Scope-aware list with materialization (agents + partials + errors)
  list(scope: ScopeQuery): Promise<MaterializationResult>

  // Fetch a single card by internal id
  get(id: string): Promise<AgentCard | null>

  // Materialize all cards + partials from external source into DB rows
  materialize(scope: ScopeQuery): Promise<MaterializationResult>

  // Reconcile external source with DB (returns counts + first-N error messages)
  reconcile(): Promise<ReconcileResult>
}

Materialization classifies each entry by shape:

Entry has runtimes[] → classified as AgentCard
Entry has bodyMarkdown, no runtimes → classified as Partial
Ambiguous → ClassificationError (surfaced to operator)

Browsing registered providers

Use the CLI to list and inspect providers connected to your org:

# List registered providers in the marketplace
rensei marketplace list --type agent-registry

# Show provider detail and reconcile status
rensei marketplace show <providerId>

Or navigate to Factory → Agents → Registry in the platform UI to see the current reconcile state and any classification errors.

Agent Cards - the cards that ARPs produce
Agent Card Partials - partials materialised by external providers
A2A Registry - registering A2A peer agents (backed by a2a-peer provider)
CLI marketplace - rensei marketplace commands

Agent Registry Providers

On this page