Agent Registry

Layer 5 of 12·Slice: Orchestration core·Platform: No dedicated platform

Scope of this page. Reference material for the Agent Registry layer: what it owns, what it must not own, and how Synedrix OS implements it today. It is descriptive, not normative — where this page and the Layer Taxonomy Table disagree, the taxonomy table wins.

What this layer is link

The Agent Registry Layer defines discoverable capabilities and boundaries. It is the shared discovery, versioning, and lifecycle surface for every agent running on Synedrix OS — the layer that answers what agents exist, what they are permitted to do, and whether a given agent is currently eligible to be invoked, as distinct from the Agent Runtime Layer, which actually executes an invocation once the registry has said it may proceed.

Without a formal registry, a multi-agent system accumulates implicit assumptions about agent roles and permissions that are difficult to audit or evolve safely. This layer exists so that orchestration can discover capable agents by capability tag, domain, or role class; so that governance can enforce that only registered, policy-compliant agents participate in governed workflows; and so that operators and domain packs can enable or disable agents per business instance without forking core agent definitions.

flowchart LR
  n1([Agent Registry]):::term
  subgraph What it owns
    n2[Agent metadata]:::agent
    n3[Permissions]:::agent
    n4[Contract references]:::agent
    n5[Lifecycle status]:::agent
    n6[Versioning]:::agent
  end
  n1 --> n2
  subgraph What it must not own
    n7[Domain workflows]:::warn
    n8[Domain Pack Layer]:::term
    n7 --> n8
    n9[Runtime execution itself]:::warn
    n10[Agent Runtime Layer]:::term
    n9 --> n10
    n11[Workflow contracts or execution sequencing]:::warn
    n12[Orchestration Layer]:::term
    n11 --> n12
    n13[Evaluation outcomes or quality metrics]:::warn
    n14[Agent Evaluation Spec]:::term
    n13 --> n14
  end
  n1 --> n7
  subgraph Interfaces with
    n15[Orchestration]:::check
    n16[Governance]:::check
    n17[Runtime]:::check
  end
  n1 --> n15

What it owns link

Per the Layer Taxonomy Table, Agent Registry owns the following:

• Agent metadata — identity, mission, family, owner, and capability tags.
• Permissions — tool, systems, and memory scope declarations that gate what a registered agent may do.
• Contract references — pointers to the full agent definition (input/output contracts, authority, task surface) that the registry entry summarizes.
• Lifecycle status — draft, active, deprecated, retired, disabled, suspended, and the orchestration behavior each state implies.
• Versioning — the SemVer lineage of an agent’s definition, separate from its stable agent_id.

What it must not own link

The registry describes and gates agents; it neither runs them nor decides how a specific business domain should use them.

Interfaces with link

The registry is a lookup and gate that every invocation passes through, not an actor in the invocation itself.

• Orchestration — the Orchestrator Agent (os-agt-001) never hand-codes which agent handles a capability; it asks the Registry & Capability Agent (os-agt-003) to resolve required_capabilities[] against live registry state, so availability, versioning, and deprecation are resolved once rather than duplicated per workflow.
• Governance — an agent’s lifecycle state, compliance labels, and risk tier are what governance checks before allowing a production invocation; a retired, disabled, or suspended agent must be rejected regardless of what a workflow contract requests.
• Runtime — the registry is what the runtime is invoked as: an agent’s registered agent_id, tool permissions, and memory scope are the boundary the runtime enforces during execution, not something the runtime is free to reinterpret.

How Synedrix OS implements it link

The Agent Registry Spec defines the schema every registered agent — OS-owned or domain-contributed — must populate: a stable agent_id, an archetype (control | execution | intelligence | interface | interop | audit), domain_scope, current_version and changelog, a status drawn from the six-state lifecycle, governed capability_tags across role:, domain:, and class: namespaces, dependency declarations (required_tool_ids, required_policy_pack_ids, required_memory_layers, required_workflow_ids), compliance labels and risk tier, and an observability_profile. The spec draws a sharp identity/version distinction: agent_id never encodes a version, and every change to an agent’s definition is a new SemVer entry in its changelog rather than a new identifier — a new agent_id is reserved for a genuinely new agent identity.

The lifecycle state machine is the mechanism that makes the registry a real gate rather than a passive catalog. An agent in draft must not be invoked in production; active is the default eligible state; deprecated may still be invoked but emits warnings; retired and disabled (the latter, instance-scoped) must be rejected by orchestration; and suspended blocks invocation until cleared. Every state transition must emit an agent.lifecycle.changed event carrying actor, reason, and timestamp, so lifecycle changes are themselves auditable rather than silent registry edits.

The Agent Registry is where this schema is populated for the twelve OS-owned agents, giving each one a full contract — input/output schema, tools and systems allowed, memory scope, decision_scope, execution_scope, approval_required, and escalation_path — plus a documented interaction pattern showing how OS agents call one another (goal decomposition and routing, the pre-execution policy gate, cross-domain anomaly response, explainability queries, a domain pack owning its own channel, and memory recall/commit). Domain packs contribute their own agents against the same §2 schema, with required constraints: a domain-prefixed agent_id (e.g. com-agt-001), owner set to the domain pack rather than synedrix-os, family: domain or family: customer, an escalation_path whose terminal node reaches os-agt-001 or os-agt-004, and approval_required.policy: true for any financial, regulated-messaging, or irreversible-write execution_scope.

Append-only at runtime is the invariant that most distinguishes this layer from an ordinary database table: no running workflow may add, remove, or modify an agent entry, OS-owned agents may not be overridden or shadowed by domain packs, and agent identifiers are not reused (the one deliberate, non-repeatable exception being the v0.4 os-agt-009–os-agt-012 reallocation recorded in the registry’s own §3.1). An agent with decision_scope: execute must carry a non-empty approval_required declaration, and the Audit & Lineage Agent (os-agt-008) must never appear in any agent’s tools_allowed list, since it is a query target, not a callable tool.

Platform mapping link

This layer has no platform-mapped implementation. It is realized purely as a specification (the Agent Registry Spec) plus its data — the twelve OS agent entries in the Agent Registry and, at runtime, canonical/agent-registry.yaml — rather than by a discrete stack platform. The recommended relational tables (agent_registry_entries, agent_registry_versions, agent_capability_tags, agent_dependency_declarations, agent_instance_controls, agent_lifecycle_events) live on Supabase PG17 (Layer 7), but Layer 7 hosting the tables does not make it the owner of this layer’s concern — see Ownership guidance.

OS agents at this layer link

One OS-owned agent is registered at this layer.

Layer principles that apply link

• Layer Principle 1 — Shared before specific. The registry schema, archetype vocabulary, and lifecycle state machine are reusable across every domain pack, which is why they are owned once at the OS layer rather than redefined per pack.
• Layer Principle 2 — Controls before execution. A retired, disabled, or suspended registry entry is a hard stop on invocation — the registry is itself a control that execution must pass through, not a passive lookup.

Related Synedrix OS documents link

• Layer Taxonomy Table — the authoritative row for this layer.
• Agent Registry Spec — the registry schema, lifecycle states, and archetype vocabulary.
• Agent Registry — the twelve OS-owned agent entries, using the schema above.
• Agent Spec — full agent anatomy; the fields a registry entry summarizes and points back to.

Synedrix OS · Layer reference · Agent Registry