Skip to main content

Agent Registry Governance

Agent Registry Governance

Canonical governance for publishing and maintaining OSSA agents in the Bluefly platform registry. Authority: technical-docs wiki; OSSA spec in openstandardagents (v0.4).

Scope

  • Registry: platform-agents (registry.yaml, packages/@ossa/<name>/manifest.ossa.yaml). Single source of truth for agent identity, capabilities, and lifecycle.
  • Publishing path: BuildKit and CI; no ad-hoc scripts. Agents are validated (OSSA schema + lint) before merge to release/main.
  • Consumers: Drupal (ai_agents_ossa, mcp_registry), MCP (agent-protocol), mesh discovery, kagent deploy.

Metadata requirements (OSSA v0.4)

Manifests MUST satisfy the schema in openstandardagents spec v0.4. For registry inclusion we expect:

  • metadata.name (required)
  • metadata.version (required)
  • metadata.uuid (recommended): UUID v4 for stable Drupal/entity mapping.
  • metadata.machine_name (recommended): ^[a-z0-9_]+$ for Drupal-friendly identifiers.
  • metadata.status (optional): active | deprecated | revoked. Default treated as active.
  • metadata.revoked_at (when status is revoked): ISO 8601 date-time.
  • metadata.deprecated_message (when status is deprecated): Human-readable migration path.
  • metadata.signature / metadata.checksum (recommended for published agents): Integrity and trust. Format sha256:hex or sha512:hex; signature per platform policy.

Validation: ossa validate <path> (schema); ossa lint <path> (best-practice and registry rules).

How to publish an agent

  1. Author manifest: Create or update manifest.ossa.yaml under packages/@ossa/<agent-name>/. Use OSSA v0.4 schema; include metadata.uuid and metadata.machine_name for Drupal integration.
  2. Validate and lint: From openstandardagents repo or CLI:
    • ossa validate packages/@ossa/<name>/manifest.ossa.yaml
    • ossa lint packages/@ossa/<name>/manifest.ossa.yaml (fix errors; warnings/info as needed).
  3. Register in registry: Add or update the agent entry in registry.yaml (platform-agents root). Ensure manifest_path or equivalent points to the manifest.
  4. Merge via MR: Create a feature branch, open a Merge Request to release/v0.1.x (or project default). CI runs validate + lint; no merge without passing checks.
  5. After merge: CI publishes packages; deploy to kagent or mesh per project pipeline (e.g. generate:kagent-crds, deploy-to-k3s).

No direct commits to main/release; no scripts in repo for publish—use BuildKit and GitLab CI only.

Revocation and deprecation

  • Deprecated: Set metadata.status: deprecated and metadata.deprecated_message with migration path. Lint warns if deprecated_message is missing. Consumers may show deprecation notices and point to the message.
  • Revoked: Set metadata.status: revoked and metadata.revoked_at (ISO 8601). Revoked agents MUST NOT be used for new deployments; registry and discovery APIs should filter or flag them. Lint reports revoked as error when encountered in a publish path.

Formal disclosure

  • Security or integrity issues with a published agent: open a confidential issue in the owning project (platform-agents or openstandardagents); do not disclose in public MRs or wiki until patched.
  • Revocation of a compromised or superseded agent: follow revocation semantics above; announce via issue or release notes; update registry and any deploy pipelines to exclude or replace the agent.

References

  • OSSA spec and schema: openstandardagents repo, spec/v0.4/.
  • Registry layout: platform-agents registry.yaml and packages/@ossa/.
  • BuildKit: buildkit agent, buildkit deploy, gitlab workflow (issues, MR, wiki).
  • Separation of duties: technical-docs wiki architecture/separation-of-duties.