ai-integrations: dedicated package + catalog-model registration for AiResource agent type

[johnmcollier]

Summary

Move the AiResource spec.type: agent typed schema out of ai-experience-common into a dedicated package, and wire catalog-model registration the way upstream skill/rule and MCP mcp-server validators are registered (createCatalogModelLayer / declareKindVersion with specType: 'agent' + catalogModelExtensionPoint.addModelSource).

Today PR #4164 (issue #4128 / RHIDP-15867) adds types, KindValidator, type guard, JSON schema, examples, and unit tests under ai-experience-common. That package also carries ai-experience shared artifacts that consumers do not need when they only want the agent catalog type. The validator is also exported but not registered with the catalog entity model, so catalog ingest still only applies the default AiResource schema (type / lifecycle / owner) and does not enforce agent-specific fields (e.g. non-empty spec.instructions) via the model layer.

Tasks

• Create a dedicated package in workspaces/ai-integrations/plugins/ for the agent AiResource catalog model (types, JSON schema, KindValidator, type guard, and CatalogModelLayer / entity-model export). Prefer a name that signals catalog-model scope (e.g. catalog-model-ai-resource-agent) rather than nesting under ai-experience-*
• Move the agent schema implementation out of @red-hat-developer-hub/backstage-plugin-ai-experience-common into the new package; remove the agent public exports from ai-experience-common (and regenerate API reports / adjust imports)
• Export an agent CatalogModelLayer mirroring MCP/skill/rule (declareKindVersion.v1 with specType: 'agent' and the agent JSON schema)
• Add a thin catalog backend module (new package or colocated backend entry) that registers the agent model via catalogModelExtensionPoint.addModelSource, following @backstage/plugin-catalog-backend-module-ai-model
• Wire the backend module into the workspace packages/backend (and any required app-config / dynamic-plugin packaging for this workspace)
• Add/adjust unit tests for the moved package; keep schema accept/reject coverage; add a registration smoke test if practical
• Add a changeset for the new package (and a changeset for any ai-experience-common public API removal if that lands in the same PR)
• Update package README with a short agent field table / link to examples/ai-resource-agents.yaml

Acceptance Criteria

• Agent types/validator/schema live in a dedicated package that does not pull in unrelated ai-experience shared APIs
• ai-experience-common no longer exports the agent AiResource surface
• Agent specType is registered with the catalog model so ingest uses the agent schema (missing/empty/wrong-type spec.instructions rejected at the catalog-model layer)
• Workspace backend loads the registration module in local/dev
• Tests and changesets cover the move + registration
• No OpenAI Agents SDK dependency

Specifications

All paths below are relative to workspaces/ai-integrations/.

• openspec/changes/airesource-agent-typed-schema/design.md (especially D3 field mapping, D10 HOW — skill/rule + MCP registration pattern)
• openspec/changes/airesource-agent-typed-schema/tasks.md (task 2.3 wire validator into catalog model / backend module registration)
• openspec/changes/airesource-agent-typed-schema/specs/ai-resource-agent-schema/spec.md

Out of Scope

• Catalog processor validation for agent fields (RHIDP-15868 — ai-integrations: catalog processor validation for AiResource agent type #4129)
• Upstream RFC + implementation PR (RHIDP-15869)
• Agent runtime / orchestration / UI
• Reworking unrelated ai-experience-common utilities

Context

• Depends on ai-integrations: AiResource agent typed schema (catalog-model validator + examples) #4128 / PR feat(#4128): add AiResource agent typed schema #4164 for the initial agent schema, examples, and tests
• Sibling processor story remains ai-integrations: catalog processor validation for AiResource agent type #4129
• Jira / program context: RHIDP-15867 follow-on (registration + packaging); epic RHIDP-15865; ownership RHDHPLAN-1507
• Review finding: Fullsend + human review on feat(#4128): add AiResource agent typed schema #4164 called out missing catalog-model registration and suboptimal package home in ai-experience-common

[johnmcollier]

Blocked on #4128 / #4164 merging (or at least stabilizing the agent schema surface to move).

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 11:21 PM UTC · Completed 11:24 PM UTC
Commit: c91e228 · View workflow run →

[johnmcollier]

Closing — this split was wrong.

PR #4164 / #4128 should deliver the agent schema in a dedicated package up front, not land it in ai-experience-common and move it later. Catalog-model registration can stay in that same PR (per #4128) or be a registration-only follow-up if we explicitly defer it — not a “move + register” issue.

[fullsend-ai-triage]

This issue is blocked on PR #4164 (implementing the initial agent schema under ai-experience-common for issue #4128). That PR introduces the agent types, KindValidator, JSON schema, examples, and unit tests that this issue plans to extract into a dedicated package and register with the catalog model layer.

Until PR #4164 merges and the agent schema surface stabilizes, the extraction and catalog-model registration work described here cannot meaningfully proceed — there would be nothing to move yet.

Current blocker status:

• PR feat(#4128): add AiResource agent typed schema #4164 is open (not merged, not draft) and appears to be in review.

Once PR #4164 lands, this issue should be unblocked and ready for implementation. The task list and acceptance criteria in the issue body are well-defined and actionable.

Blocked by:

• feat(#4128): add AiResource agent typed schema #4164