Skip to content

Agent Registry

Target Architecture — Final-State Design

The Agent Registry is the system of record for who can act in the Agent Mesh. It owns the AgentDefinition and AgentVersion aggregates, governs registration and versioning, scopes every agent's permissions, and backs the warm capacity managed by the AgentPoolManager. It is what makes agents interchangeable, versioned, and governable.

The registry is implemented by ConnectSoft.Factory.AgentMesh.AgentRegistryService. Registries are seeded from ConnectSoft.AI.SoftwareFactory.Platform/registry and ConnectSoft.AI.SoftwareFactory.Agents, with policies sourced from ConnectSoft.AI.SoftwareFactory.Workforce.

Domain Model

flowchart TB
    Def["AgentDefinition<br/>(aggregate root)"] -->|"has many"| Ver["AgentVersion<br/>(entity)"]
    Def --> Scope["PermissionScope<br/>(value object)"]
    Ver --> Skills["SkillBinding[]<br/>(value object)"]
    Ver --> ModelPolicy["ModelPolicyRef<br/>(value object)"]
    Pool["AgentPoolManager"] -->|"instantiates"| Ver
Hold "Alt" / "Option" to enable pan & zoom

AgentDefinition

The stable identity of an agent role (e.g. ConnectSoft.Agent.SolutionArchitect). It carries the role, owning cluster, default permission scope, and the lifecycle status of the agent. A definition has many versions but exactly one identity.

AgentVersion

An immutable, semver-tagged snapshot of an agent's configuration: the bound skills, the model policy reference, prompt strategy, tool permissions, and correction limits. Versions enable safe rollout, A/B evaluation, and rollback without changing the agent's identity.

Registration

Registration is the governed onboarding of an agent version. The POST /agents/register endpoint validates the submission against naming conventions, required skill bindings, and a permitted model policy before the version becomes claimable.

sequenceDiagram
    participant Client as Registrar (Control Plane / Studio)
    participant Reg as AgentRegistryService
    participant Gov as Governance & Compliance
    Client->>Reg: POST /agents/register (definition + version)
    Reg->>Reg: validate naming + skill bindings
    Reg->>Gov: authorize permission scope + model policy
    Gov-->>Reg: approved
    Reg-->>Client: agentId + version (Registered)
    Reg->>Reg: emit AgentRegistered
Hold "Alt" / "Option" to enable pan & zoom

A successful registration emits AgentRegistered in the canonical envelope.

Versioning

  • Versions follow semver; AgentVersion records are immutable once published.
  • Each definition tracks a current version per tenant, enabling staged rollout (canary → full) and instant rollback.
  • A task's required version can be pinned via the task contract; otherwise the current version is resolved at claim time.
  • Version changes are auditable events, so any artifact can be traced to the exact agent version that produced it.

Permission Scoping

Every agent version carries an explicit permission scope — the least-privilege set of tools, model policies, knowledge classifications, and resource actions it may use. Scopes are enforced at runtime by the ToolAdapterService, the ModelRouterService, and the Knowledge governance layer.

Scope dimension Example
Tool permissions repo:read, template:scaffold, validator:run
Model policy mp-architecture-default
Knowledge classification ceiling Internal (cannot read Confidential)
Resource actions artifact:create, pull-request:open

Scopes are authorized by the Governance, Security & Compliance Platform and re-checked on every invocation — registration alone never grants standing access. See Security.

Agent Pools

The AgentPoolManager maintains warm pools of agent instances per tenant and cluster to eliminate cold starts and to bound concurrency. It owns the AgentHealthStatus aggregate.

Pool concern Behavior
Warm capacity Pre-instantiated instances of high-demand agent versions.
Concurrency limits Per-tenant and per-cluster ceilings to protect fairness and cost.
Health draining Instances reporting unhealthy AgentHealthStatus are drained and replaced.
Scale signals Queue depth and execution latency drive scale-out/scale-in.

Health transitions emit AgentHealthChanged; the current health is queryable via GET /agents/{agentId}/health.

Persistence

Aggregate Store Notes
AgentDefinition Azure SQL / PostgreSQL (NHibernate) Tenant-scoped; indexed by agentId, tenantId.
AgentVersion Azure SQL / PostgreSQL (NHibernate) Immutable; indexed by agentId + version.
AgentHealthStatus Redis (hot) + relational (history) Hot status in Redis; transitions persisted for audit.