Docs / Concepts
Registry
A registry is the discoverable view of host capabilities, versions, availability, and requirements.
Plain English
A registry tells callers what capabilities exist before they try to use them.
Why it exists
Agents and applications need a trustworthy discovery step so planning does not depend on hidden or stale implementation details.
Formal definition
A registry is a manifest-backed capability index that exposes identity, version, lifecycle, permission, and metadata for selection and validation.
Concrete example
Ground the concept before the schema.
A caller checks the ServiceOpsHost registry and sees that schedule_technician is invokable at version 1.0.0.
Finds an available qualified technician and reserves a service window.
Invocation trace
- 01 Actor
Planning Agent
- 02 Capability
schedule_technician
- 03 Host
ServiceOpsHost
- 04 Policy
manager_approval
- 05 Context
job_context
- 06 Result
Confirmed Appointment
{ "id": "service-ops-host", "version": "0.1.0", "protocol_version": "0.1", "kind": "service", "capabilities": [{ "id": "schedule_technician", "version": "1.0.0", "description": "Finds an available qualified technician and reserves a service window.", "status": "experimental", "modes": ["sync"], "emits": ["execution_started", "execution_completed", "execution_denied"], "policy": { "risk_tier": "high", "auth_required": true, "approval_required": true, "allowed_actors": ["agent://planning-assistant"] }, "metadata": { "required_permissions": ["service:dispatch"], "lifecycle": "invokable" } }], "evidence": { "store": "local-append-only", "append_only": true }}Relationships
Where this sits in the protocol.
Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.
A registry is usually derived from host manifests.
Invocation should use registry facts for compatibility checks.
Conformance should prove registry data is truthful enough for callers.
Visual model
- 01Caller asks what exists.
- 02Registry returns capability metadata and state.
- 03Caller invokes only after selecting a compatible capability.
Implementation notes
- Include lifecycle and version metadata in the registry view.
- Avoid caching registry state beyond its safe freshness window.
- Make unavailable capabilities visible when callers need to reason about them.
Common mistakes
- Publishing only names without versions or policy.
- Letting stale registry state cause unsafe invocation attempts.
- Treating discovery as a developer convenience instead of protocol state.
Related concepts