Status

Draft canonical spec. Companion to Synedrix OS - Agent Spec. Supersedes: none — first version. Related artifacts: Synedrix OS - Agent Spec, Synedrix OS Taxonomy Spec, Synedrix OS Responsibility Matrix, Synedrix OS Workflow Contract Spec.

Purpose

The Agent Registry is the shared discovery, versioning, and lifecycle layer for all agents running on Synedrix OS. It enables orchestration to discover capable agents by capability tags, domain, role class, and status. It enables governance to enforce that only registered, policy-compliant agents may participate in governed workflows. It enables operators and domain packs to enable or disable agents per business instance without forking core definitions.

The registry schema belongs to Synedrix OS. Domain packs contribute agent entries. Business instances enable, disable, or configure agents within the boundaries the domain pack declares.

Versioning

The Agent Registry distinguishes between identityandversion:

  • agent_id (for example, os-ctl-policy-guard-001, trd-int-technical-analyst-001) is a stable identity and never encodes version.
  • current_version and changelog.version use semantic versioning (MAJOR.MINOR.PATCH) to track the evolution of the agent definition over time.
  • Changing prompts, contracts, policies, or dependencies is represented as a new SemVer entry in changelog, not a new agent_id.
  • A new agent_id is only created when an agent is replaced by a fundamentally different identity (for example, a new control agent with a different mission), at which point the prior ID is marked deprecated or retired.

Canonical Synedrix OS specs (including this document) use vX.Y in file names and headers to track spec/document versions. This is distinct from agent SemVer and must not be conflated with agent_id naming.

Responsibilities

The Agent Registry owns:

  • Stable agent identity and discovery surface across all domain packs.
  • Version lineage — what changed between agent versions and when.
  • Lifecycle state management — draft, active, deprecated, retired, disabled, suspended.
  • Dependency declarations — which tools, policies, workflows, and memory resources an agent depends on.
  • Capability tags — searchable, governed vocabulary for orchestration routing.
  • Ownership and accountability metadata — domain pack, team, compliance labels.
  • Enable/disable controls per business instance.

The Agent Registry does not own:

Lifecycle states

An agent in the registry is always in exactly one of these states, and orchestration behaves differently in each.

StateMeaningOrchestration behaviour
draftDefinition under developmentMust not be invoked in production workflows
activeRegistered, validated, eligible for invocationDefault eligible state
deprecatedScheduled for retirement, replacement declaredMay still be invoked; deprecation warnings emitted
retiredNo longer eligible for invocationOrchestration must reject invocation attempts
disabledExplicitly disabled at business-instance levelTreated as retired for this tenant
suspendedTemporarily halted due to policy or incidentOrchestration blocks invocation until cleared

Every state transition must emit an agent.lifecycle.changed event with actor, reason, and timestamp.

The lifecycle states and the transitions the table describes:

stateDiagram-v2
    [*] --> draft
    draft --> active : registered, validated, all blocking evaluation suites pass
    active --> deprecated : scheduled for retirement
    deprecated --> retired : replacement active with passing suites
    active --> disabled : business instance disables
    active --> suspended : policy or incident
    note right of disabled
        Set per business instance in agent_instance_controls.
        Enabling it again restores the agent current status.
    end note
    suspended --> active : cleared, full suite plus incident review pass

Registry entry schema 

registry_entry:
  agent_id:                    # Stable machine identifier, e.g. os-ctl-policy-guard-001
  name:
  description:
  archetype:                   # control | execution | intelligence | interface | interop | audit
  domain_scope:                # os | ops | commerce | finance | ...
  owner_team:

  current_version:             # Semver e.g. 1.2.0
  spec_ref:                    # Pointer to full agent definition record
  changelog:

    - version:
      date:
      summary:
      breaking_change:

  status:                      # draft | active | deprecated | retired | disabled | suspended
  created_at:
  updated_at:
  deprecated_at:
  retirement_date:
  replacement_agent_id:

  capability_tags:             # Governed vocabulary list
  workflow_role_classes:       # Role types: validator, executor, analyzer, router, escalator, observer
  supported_task_classes:      # Mirrored from task_surface for routing queries
  domain_tags:

  required_tool_ids:
  required_policy_pack_ids:
  required_memory_layers:
  required_workflow_ids:

  compliance_labels:           # e.g. audit-required, pii-access, high-impact
  risk_tier:                   # low | medium | high | critical
  governance_class:            # autonomous | policy-gated | hitl-required

  instance_overrides_allowed:
  default_enabled:

  # Observability (optional but recommended)
  observability_profile:       # low | standard | strict
                               # low: cost and latency metrics only
                               # standard: all invocation-scope metric families
                               # strict: all families including risk alignment, guardrail effectiveness, user trust
                               # Defaults to standard if unset. Strict is required for risk_tier: high or critical.
  required_eval_dimensions:    # list drawn from evaluation spec dimension vocabulary
                               # e.g. [output-quality, policy-compliance, observability-metrics]
                               # observability-metrics must be included for any agent with risk_tier: medium or above
Illustrative example, not a production implementation. Review and test before use.

Capability tag vocabulary

Capability tags must use a governed vocabulary. Three namespaces are defined:

  • role: — functional role, e.g. role:validator, role:executor, role:analyzer, role:router, role:escalator, role:observer
  • domain: — owning domain, e.g. domain:ops, domain:commerce, domain:finance
  • class: — archetype class, e.g. class:control, class:intelligence, class:interface

Free-text tags are permitted as supplementary but must not be the primary routing signal.

Agent archetypes

ArchetypeDescriptionExamples
controlCross-domain coordination, policy enforcement, routingOrchestrator, Policy Guard, Capability Registry
executionDomain action specialists with side effectsFulfillment Agent, Pricing Agent, Refund Agent
intelligenceAnalysis, forecasting, anomaly detection — no direct side effectsForecasting Agent, Anomaly Detector, Risk Analyzer
interfaceHuman or customer-facing assistantsOperator Copilot, Customer Support Agent
interopA2A gateway, MCP broker, protocol adaptersA2A Gateway Agent, MCP Broker Agent
auditExplanation, trace synthesis, compliance reviewAudit Agent, Explanation Agent

OS vs domain pack vs business instance split

ConcernSynedrix OSDomain PackBusiness Instance
Registry schema and enforcementOwns.Contributes agent entries.Enables or disables per instance.
Capability tag vocabularyOwns governed namespace.Extends with domain-specific tags.No extension allowed.
Archetype definitionsOwns.Uses defined archetypes.No override.
Lifecycle state machineOwns.Follows state machine.May trigger disabled or suspended for their instance.
Compliance labelsDefines label vocabulary.Declares applicable labels per agent.Cannot remove compliance labels; may add instance-specific ones.

Who owns what in the registry:

flowchart LR
    OS["Synedrix OS: owns registry schema and enforcement, tag vocabulary, archetypes, lifecycle state machine, label vocabulary"]
    DP["Domain Pack: contributes agent entries, extends tags, declares labels per agent"]
    BI["Business Instance: enables or disables per instance, may trigger disabled or suspended, may add instance-specific labels"]
    OS -->|"governs"| DP
    DP -->|"entries enabled or disabled by"| BI

agent_registry_entries         — one row per agent_id, current status and version
agent_registry_versions        — full version history per agent_id
agent_capability_tags          — tag assignments per agent, normalized
agent_dependency_declarations  — tool, policy, memory, workflow dependencies per agent
agent_instance_controls        — enable/disable and override records per business instance
agent_lifecycle_events         — immutable audit log of every lifecycle state change
Illustrative example, not a production implementation. Review and test before use.

Invariants

  • Every agent invoked in a production workflow must have an active registry entry.
  • Every lifecycle state change is auditable and event-emitting.
  • Capability tags must use the governed vocabulary; routing must not rely on free-text tags.
  • Business instances cannot remove compliance labels declared by domain packs.
  • Deprecated agents must declare a replacement agent ID before retirement.

Version

Canonical Reference

Agent Specifications

Architecture

Runtime and Evaluation

Observability

  • Synedrix OS Observability Metrics Spec — Defines the observability_profile values and the metric families that required_eval_dimensions: observability-metrics implies. Agents with risk_tier: medium or above must include this dimension.

Synedrix OS · April 2026