[Substrate] Registry → Substrate render (SandboxAgent + ActorTemplate; resolve promptRef)

[Sam123ben]

Part of the Agent Substrate epic ⬆️. Depends on #B (Substrate CRDs) + #C (authored agents).

Goal

Turn a published DevAI registry agent into the Substrate runtime objects automatically, the same way kagent-agent-sync already renders the classic Agent CR today.

Today (grounded)

agentic-registry serves GET /v0/export/kagent → renders kagent Agent (v1alpha2, spec.declarative) + ToolServer. kagent-agent-sync (CronJob) curls it and kubectl applys with --prune. We added per-variant rendering (provider/model) + the active-variants endpoint + lane-aware reconcile this session. Known gap: the export does NOT resolve promptRef → empty systemMessage → invalid CR (we built but reverted that one-line fix).

Tasks

• Teach the export to emit SandboxAgent (+ ActorTemplate / AgentHarnessSubstrateSpec) when the agent targets Substrate, vs the classic Agent otherwise.
• Resolve promptRef → Prompt.spec.systemPrompt at export so the 39 prompt-by-reference agents render a valid non-empty systemMessage (the reverted kagent.go Options.SystemPrompt + resolveSystemPrompt change — redo it).
• Map DevAI agent fields → SandboxAgent: runtime (Go/Python/ADK), model/provider, tools/MCP (RemoteMCPServer + toolNames — the v1alpha2 tool path still needs porting), WorkerPool ref, sandbox runtime.
• Reconcile in kagent-agent-sync: render → apply/prune SandboxAgents; keep the reap-on-empty + operator kill-switch semantics we shipped.
• Note the registry label-merge gotcha (apply merges metadata.labels; unlabelling a seed doesn't drop it) — the reliable off-switch is the active-variants kill-switch.

Acceptance

Publishing/labelling an agent for Substrate produces a valid SandboxAgent the controller accepts; unlabelling/kill-switch reaps it. No empty-systemMessage rejections.

Refs: agentic-registry/{adapters/kagent,internal/api/export.go,internal/api/resolve.go}, tesserix-k8s/charts/apps/kagent-agent-sync/; memory: Agent Harness + kagent (promptRef + reap gotchas).

— Part of #69

[Sam123ben]

✅ Schema alignment verified + cross-validation API shipped

Investigated DevAI's agent model ⇄ the kagent CRDs (read live from the cluster). Good news on two fronts.

1. The CRDs already line up — and SandboxAgent is already installed

agents.kagent.dev (v1alpha2) spec: type, declarative{modelConfig, systemMessage, runtime, tools, a2aConfig, memory, deployment, …}, sandbox{network}, skills, description.

sandboxagents.kagent.dev is ALREADY on the cluster (since 2026-05-25). Its spec = Agent plus substrate{workerPoolRef, snapshotsConfig} + platform. So a SandboxAgent is just "a declarative Agent pinned to a WorkerPool" — the declarative block is byte-identical. DevAI's agent maps to both with one renderer.

DevAI registry agent	→ kagent declarative
spec.llm.provider/model + chosen variant	modelConfig (ref to kagent-mc-<suffix>)
spec.systemPrompt or spec.promptRef→Prompt.spec.systemPrompt	systemMessage (must be non-empty)
spec.runtime.kind (python_class/…)	runtime
spec.mcpServers	tools (ToolServer refs today; RemoteMCPServer pending)
metadata.name	metadata.name
(Substrate only) operator-set	substrate.workerPoolRef, sandbox.network

2. The one real mismatch — fixed

39/40 DevAI agents keep their prompt in a referenced Prompt (not inline), and the export did not resolve it → empty systemMessage → the controller rejects the CR. Fixed in agentic-registry: kagent.Options.SystemPrompt + resolveSystemPrompt (follows promptRef → Prompt.spec.systemPrompt), wired into both export endpoints.

3. Cross-validation API (the "some API to cross-validate" ask)

New GET /v0/agents/{name}/export/kagent?validate=true → {"ok": bool, "issues":[{severity,field,message}]} — renders the agent exactly as the controller would and reports whether it'd be accepted (errors = rejected: empty systemMessage, missing ModelConfig, missing spec.type/declarative; warnings = e.g. the v1alpha1 ToolServer tool path). kagent.Validate() + Go tests shipped.

DevAI side: RegistryClient.kagent_validate(name) → calls it; defensive (never wedges authoring). Authoring/publish can now cross-validate an agent against the kagent contract before it ever reaches the cluster — closes the build/validate gap in #75 and de-risks #72/#73.

Still open (tracked in the sub-issues)

• Render SandboxAgent (+ substrate.workerPoolRef) when targeting Substrate — [Substrate] Registry → Substrate render (SandboxAgent + ActorTemplate; resolve promptRef) #73.
• Port tools to RemoteMCPServer + toolNames (kagent 0.9 shape) — [Substrate] Registry → Substrate render (SandboxAgent + ActorTemplate; resolve promptRef) #73/[Substrate] Dispatch integration — route runs to a Substrate Actor vs Job #74.
• Run kagent_validate in the authoring UI + the lifecycle gate — [Substrate] User-authored agents in DevAI (dashboard → registry schema → publish) #72/[Substrate] Full agent lifecycle gate — dev → test → deploy → run (harness) #75.

[Sam123ben]

✅ SandboxAgent rendering shipped (agentic-registry a67e35a)

kagent.Options.WorkerPoolRef → the export emits a SandboxAgent (kagent.dev/v1alpha2) instead of a classic Agent: same spec.declarative, plus spec.substrate.workerPoolRef so the controller runs it as a gVisor Actor in a shared WorkerPool (low overhead / fast cold start) rather than a Deployment per agent. Exposed via ?workerPool=<pool> on both export endpoints; Validate() checks a SandboxAgent pins a WorkerPool. One renderer, both CRDs — the declarative block is identical. Off unless a WorkerPool is passed → current behavior unchanged. Go tests green.

Software chain now complete + tested: agent → promptRef→systemMessage resolve → cross-validate (?validate=true) → render classic Agent or SandboxAgent.

Remaining for this issue: (a) the kagent-agent-sync cronjob pass ?workerPool= when Substrate is enabled (tesserix-k8s, gated by #71); (b) port tools to RemoteMCPServer (#74).

[Sam123ben]

RemoteMCPServer + valid SandboxAgent release deployed

The remaining exporter and GitOps migration is implemented, merged, released, and verified.

Source changes

• Agentic Registry PR: fix(registry): emit valid remote MCP substrate resources agentic-registry#85
  • merged commit: 21fa267badbc330f77a0e7c909263cecbc2c1d6b
  • emits kagent.dev/v1alpha2 RemoteMCPServer resources
  • emits explicit apiGroup/kind/name/toolNames references
  • enforces explicit tool allowlists and the CRD 50-tool maximum
  • routes gateway mode through the configured private AgentGateway MCP URL
  • fixes SandboxAgent rejection by emitting spec.platform=substrate
• GitOps PR: fix(kagent): reconcile remote MCP substrate resources tesserix-k8s#505
  • merged commit: 6e4a80c16ac55ed881fc60321f3e87b21ab398b0
  • chart release: kagent-agent-sync 0.2.1
  • passes the private agentgateway-mcp URL
  • adds RemoteMCPServer RBAC, reap, and prune ownership
  • retains legacy ToolServer cleanup during migration

Verification

• Registry: go test ./..., go test -race ./..., go vet ./..., go build ./..., gofmt, and diff checks passed.
• GitOps: focused pytest, Helm lint/template, repository-wide chart lint, manifest validation, Checkov, Trivy, GitGuardian, Argo validation, and Helm release all passed.
• Production CRD server dry-run accepted representative RemoteMCPServer and SandboxAgent objects; this caught and verified the spec.platform=substrate fix. No probe object persisted.
• Registry freight 8d5fa7c32d6707326f7809af3e2310b02c36a650 promoted successfully.
• agentic-registry is Synced/Healthy and Running/Ready with zero restarts on main-21fa267; /healthz returned 200.
• kagent-agent-sync is Synced/Healthy at 6e4a80c. Live CronJob config contains the URL-encoded private gateway http://agentgateway-mcp.agentgateway-system.svc.cluster.local:8080 and RemoteMCPServer prune allowlist/RBAC.
• First natural post-deploy schedule kagent-agent-sync-29785940 succeeded at 2026-08-19T16:20:06Z. DevAI reported no active variants, the job followed the fail-safe reap path, and no registry-managed Agent/SandboxAgent/RemoteMCPServer/ToolServer exists.

Remaining acceptance blocker

Keeping this issue open: no user agent is currently labelled/enabled, and #70 still has the production canary Ready=False / ActorTemplateNotReady. The API/schema and reconcile chain are shipped, but claiming a controller-ready published Actor before the substrate state is repaired and measured would be inaccurate.

[Sam123ben]

The export and reconciliation software is delivered: promptRef resolution, kagent validation, SandboxAgent rendering, RemoteMCPServer/tool allowlists, private AgentGateway MCP routing, and fail-safe reap are merged and production-verified. Live Actor acceptance is not planned under #70 current NO-GO because the canary is not Ready and no hardened compatible runtime release exists. No registry-managed runtime objects are active. Reopen only after #70 runbook re-entry gates pass.