Implementation plan: Agentic Platform Controller POC

[djzager]

Overview

Implementation plan for the agentic platform controller POC, tracking the work from enhancement proposal through to a working system. Architecture decisions are captured in docs/adr/ in this repository.

Issue Tracker

Each stream and subtask has its own GitHub issue for board tracking:

Stream 1: Controller — #5

• 1.1: Project scaffolding #9 — 1.1 Project scaffolding
• 1.2: CRD type definitions (api/v1alpha1/) #10 — 1.2 CRD type definitions
• 1.3: SkillCard controller #11 — 1.3 SkillCard controller
• 1.4: SkillCollection controller #12 — 1.4 SkillCollection controller
• 1.5: LLMProvider controller #13 — 1.5 LLMProvider controller
• 1.6: Agent controller #14 — 1.6 Agent controller
• 1.7: AgentRun controller #15 — 1.7 AgentRun controller
• 1.8: Integration tests (envtest) #16 — 1.8 Integration tests (envtest)
• 1.9: E2E tests (real cluster) #17 — 1.9 E2E tests (real cluster)
• Phase 3: 1.3-P3: SkillCard git source resolution via skillimage #29, 1.3-P3: SkillCard inline content resolution via skillimage #30, 1.4-P3: SkillCollection child SkillCard creation for git-sourced entries #31

Stream 2: Hub — #6

• 2.1: Import CRD types into Hub #18 — 2.1 Import CRD types
• 2.2: Curated REST handlers #19 — 2.2 Curated REST handlers
• 2.3: AgentRun smart creation (Model B) #20 — 2.3 AgentRun smart creation (Model B)
• 2.4: ACP WebSocket proxy #21 — 2.4 ACP WebSocket proxy

Stream 3: UI — #7

• 3.1: API client layer #22 — 3.1 API client layer
• 3.2: Agent management pages #23 — 3.2 Agent management pages
• 3.3: AgentRun execution flow #24 — 3.3 AgentRun execution flow

Stream 4: Base Image — #8

• 4.1: Harness #25 — 4.1 Harness
• 4.2: Base image (agent-base) #26 — 4.2 Base image (agent-base)
• 4.3: Runtime images #27 — 4.3 Runtime images
• 4.4: Language images #28 — 4.4 Language images

---

Work Streams

The POC has four parallel work streams with one dependency gate:

Stream 1: Controller (this repo)
  → CRD types must be published before Hub work starts

Stream 2: Hub (konveyor/tackle2-hub)        ← depends on Stream 1 types
Stream 3: UI (konveyor/tackle2-ui)          ← depends on Stream 2 API contract
Stream 4: Base Image (separate repo)        ← independent

---

Stream 1: Controller (konveyor/agentic-controller)

1.1 Project scaffolding

• Initialize kubebuilder project with konveyor.io API group
• Set up Go module, Makefile, Dockerfile
• CI pipeline (build, test, lint, image push)
• Helm chart scaffolding (charts/agentic-controller/)

1.2 CRD type definitions (api/v1alpha1/)

• SkillCard types (spec: image/source/inline, type: skill/rule, status: resolvedImage, conditions)
• SkillCollection types (spec: skills array with skillCardRef/image/source, status: conditions)
• LLMProvider types (spec: endpoint, credentialRef, models with contextWindow/tier, status: connectionVerified, discoveredModels)
• Agent types (spec: image, prompt, providers, skillCards, skillCollections, params, status: conditions)
• AgentRun types (spec: agentRef, models with roles, params, instructions, env, envFrom, status: phase, startTime, completionTime, conditions)
• AgentPlaybook types (spec: guide, stages with agentRef/instructions)
• AgentPlaybookRun types (spec: playbookRef, models, params, envFrom, status: currentStage, stages, conditions)
• groupversion_info.go — register types with scheme
• Generate CRD manifests, deepcopy, RBAC markers
• Publish Go module so Hub can import types

1.3 SkillCard controller

• Reconcile SkillCards with image source — validate OCI ref exists, set status.resolvedImage
• Status conditions (Ready)
• Unit tests: image source path
• (Phase 3) Git source resolution via skillimage
• (Phase 3) Inline content resolution via skillimage

1.4 SkillCollection controller

• Watch referenced SkillCards
• Create child SkillCard CRs for git-sourced entries (Phase 3)
• Report aggregate readiness
• Unit tests: child creation, readiness aggregation

1.5 LLMProvider controller

• Verify connectivity on create/update by launching a container with the agent base image
• Update status with connectionVerified and discoveredModels
• Status conditions (Ready)
• Unit tests: valid endpoint, invalid credentials, model discovery

1.6 Agent controller

• Watch referenced SkillCards, SkillCollections, LLMProviders
• Validate referenced resources exist
• Report readiness based on dependency status
• Unit tests: param validation, dependency readiness

1.7 AgentRun controller

• Validate params match Agent declarations
• Resolve skills → OCI image refs from SkillCard status
• Resolve LLM providers → credential Secrets
• Inject params as KONVEYOR_PARAM_* env vars
• Pass through env and envFrom unchanged
• Create Sandbox CR with:
  • Agent container image
  • ImageVolumes for skills (via podTemplate.spec.volumes)
  • env/envFrom
  • EmptyDir workspace at /workspace
  • service: true for ACP endpoint access
  • GOOSE_SERVER__SECRET_KEY for ACP auth
• Watch Sandbox Finished condition
• Update AgentRun status (phase, startTime, completionTime, duration)
• Unit tests: param validation, Sandbox creation, env injection, status tracking

1.8 Integration tests (envtest)

• Full lifecycle: LLMProvider + SkillCards + Agent + AgentRun
• Param validation: missing required param, wrong type
• Error handling: non-existent Agent, unresolved skills

1.9 E2E tests (real cluster)

• Deploy controller with Agent Sandbox
• Run an AgentRun end-to-end (Goose agent, git clone, push)
• LLMProvider verification with real credentials
• Verify ACP endpoint is accessible on the pod

---

Stream 2: Hub (konveyor/tackle2-hub)

Depends on Stream 1.2 (published CRD types).

2.1 Import CRD types

• Add konveyor/agentic-controller/api/v1alpha1 to go.mod

2.2 Curated REST handlers

• AgentHandler — List, Get, Create, Update, Delete via h.Client(ctx)
• SkillCardHandler — List, Get, Create, Update, Delete
• SkillCollectionHandler — List, Get, Create, Update, Delete
• LLMProviderHandler — List, Get, Create, Update, Delete
• AgentRunHandler — List, Get, Create, Delete
• Resource converters for each (Hub REST format ↔ CRD format)
• Route registration in pkg.go with RBAC scopes

2.3 AgentRun smart creation (Model B)

• Accept minimal request: agent name, application ID, models, instructions
• Resolve application → git URL, source branch from Hub DB
• Resolve Identity (role: source) → git read credential Secret name
• Resolve Identity (role: asset) → git write credential Secret name (fallback to source)
• Generate target branch name
• Build fully-populated AgentRun CR with params and envFrom
• Create CR via client.Create()
• Return Hub-formatted response

2.4 ACP WebSocket proxy

• New route: GET /hub/agentruns/:name/stream
• Resolve Sandbox Service DNS from AgentRun status
• Read ACP secret key from AgentRun status/Secret
• Proxy WebSocket connection to pod:4000/acp with X-Secret-Key
• Handle connection lifecycle (close on AgentRun completion)

---

Stream 3: UI (konveyor/tackle2-ui)

Depends on Stream 2 API contract (can start once endpoint shapes are agreed).

3.1 API client layer

• Hub REST client for Agent, SkillCard, SkillCollection, LLMProvider, AgentRun
• React Query hooks for CRUD operations
• WebSocket client for ACP streaming via Hub proxy

3.2 Agent management pages

• Agent list/detail views
• SkillCard list/detail views
• LLMProvider list/detail views
• SkillCollection list/detail views

3.3 AgentRun execution flow

• Create AgentRun form (select Agent, select application, pick models, write instructions)
• AgentRun list with status polling
• AgentRun detail with ACP streaming (connect to Hub WebSocket proxy)
• Real-time display of agent output, tool calls, thinking
• Permission request handling (approve/reject with diff preview)
• Cancellation

---

Stream 4: Base Image

Independent of other streams. Tracked in PR #296.

4.1 Harness

• Git credential isolation (read from mounted Secret, configure remote without creds)
• Launch goose serve --port 4000 (POC)
• ACP session setup (session/new with MCP servers, workspace dir)
• On agent exit: commit .konveyor/ files, push using credentials
• Update AgentRun CR status with push result (single k8s API write)

4.2 Base image (agent-base)

• UBI 9 minimal + harness binary + skillctl + graphify + system tools
• /opt/skills/ directory for skill mounting
• Non-root execution compatible with OpenShift restricted SCC

4.3 Runtime images

• agent-base-goose — extends base + goose binary
• agent-base-opencode — extends base + opencode binary (future)

4.4 Language images

• agent-java-goose — extends goose runtime + JDK 21 + Maven

---

Phase 2+ (post-POC)

Tracked separately. Not blocking POC.

• AgentPlaybook + AgentPlaybookRun controllers (Phase 2)
• SkillCard git/inline source resolution + in-cluster registry (Phase 3)
• Agent memory service integration (Phase 4)
• Harness stdio-to-HTTP bridge for non-Goose runtimes
• OpenShell integration for credential isolation and L7 egress
• Agent-assisted skill creation (filed as separate issue)
• Context budget computation (advisory)
• Self-describing image labels for skill-to-image compatibility

References

• Enhancement: Enhancement: Agentic Platform Controller enhancements#295
• Base image enhancement: Add agent base image composition enhancement enhancements#296
• ADR 0001: CRD architecture
• ADR 0002: ACP transport and observability
• ADR 0003: Hub curated API