Tip: select any text on this page to bring up the Ask tooltip and question the Synedrix OS assistant about it.
What Agent Registry is
Agent Registry defines discoverable capabilities and boundaries. It is the shared discovery, versioning, and lifecycle surface for every agent on Synedrix OS: answering what agents exist, what they're permitted to do, and whether a given agent is currently eligible to be invoked, as distinct from Agent Runtime, which actually executes an invocation once the registry has cleared it.
Without a formal registry, a multi-agent system accumulates implicit assumptions about roles and permissions that are hard to audit or evolve safely. This layer lets orchestration discover capable agents by tag, domain, or role class, lets governance enforce that only registered, compliant agents participate in governed workflows, and lets operators enable or disable agents per business instance without forking core definitions.
What it owns, and what it does not
Every layer in the architecture has a non-overlapping responsibility. The boundary is as much a part of the design as the capability.
Owns
- Agent metadata: identity, mission, family, owner, capability tags
- Permissions: tool, systems, and memory scope declarations
- Contract references: pointers to the full agent definition
- Lifecycle status: draft, active, deprecated, retired, disabled, suspended
- Versioning: SemVer lineage, separate from the stable agent_id
Does not own
- Domain workflows
- → Domain Pack Layer
- Runtime execution itself
- → Agent Runtime Layer (LangGraph)
- Prompt content or model routing
- → Agent Runtime Policy Spec
- Workflow contracts or execution sequencing
- → Orchestration Layer
- Invocation records or runtime state
- → agent_invocations table and Redis hot state
Interfaces with
The other layers this one exchanges work, state, or decisions with, and why.
Orchestration
the Orchestrator Agent never hand-codes which agent handles a capability; it asks the Registry & Capability Agent to resolve required_capabilities[] against live registry state.
Governance
an agent's lifecycle state and risk tier are checked before a production invocation; a retired, disabled, or suspended agent is rejected regardless of what a workflow requests.
Runtime
the registry is what the runtime is invoked as: registered tool permissions and memory scope are the boundary the runtime enforces, not something it's free to reinterpret.
How Synedrix OS implements it
The Agent Registry Spec defines the schema every registered agent must populate: a stable agent_id, an archetype, domain_scope, versioning and changelog, a status drawn from the six-state lifecycle, governed capability tags, dependency declarations, and an observability profile. Identity and version are kept sharply distinct: a new agent_id is reserved for a genuinely new agent, never for a routine change.
The lifecycle state machine is what makes the registry a real gate rather than a passive catalog: draft may not run in production, deprecated may still run but emits warnings, retired and disabled are rejected outright, and suspended blocks invocation until cleared. Every transition emits an agent.lifecycle.changed event.
Append-only at runtime is the load-bearing invariant here: no running workflow may add, remove, or modify an agent entry, OS-owned agents may not be overridden by domain packs, and identifiers are never reused. The Audit & Lineage Agent must never appear in any agent's tools_allowed list, since it is a query target, not a callable tool.
OS agents at this layer
Registry & Capability Agent
control · os-agt-003Resolves which agents and workflows are available for a given goal.
Layer principles that apply
- Shared before specific: the registry schema, archetype vocabulary, and lifecycle state machine are owned once at the OS layer rather than redefined per pack.
- Controls before execution: a retired, disabled, or suspended entry is a hard stop on invocation.
Agent Registry questions, answered
Short, citable answers drawn from this page.
What is the Agent Registry layer in Synedrix OS?
Agent Registry is layer 5 of the twelve-layer Synedrix OS architecture, in the "Orchestration core" group. The gate every invocation passes through. It says who may run, not what to do.
What does the Agent Registry layer own?
The Agent Registry layer owns: Agent metadata: identity, mission, family, owner, capability tags; Permissions: tool, systems, and memory scope declarations; Contract references: pointers to the full agent definition; Lifecycle status: draft, active, deprecated, retired, disabled, suspended; Versioning: SemVer lineage, separate from the stable agent_id.
What does the Agent Registry layer not own?
The Agent Registry layer does not own: Domain workflows (owned by Domain Pack Layer); Runtime execution itself (owned by Agent Runtime Layer (LangGraph)); Prompt content or model routing (owned by Agent Runtime Policy Spec); Workflow contracts or execution sequencing (owned by Orchestration Layer); Invocation records or runtime state (owned by agent_invocations table and Redis hot state).
The full reference page, with every canonical specification this layer touches, lives in the documentation repository, which is private while the platform is being built.