Kubernetes controller for managing AI agent workloads. Defines CRDs
under the konveyor.io API group and controllers for composing and
executing agent workloads via Agent Sandbox.
The controller follows the Tekton Task/TaskRun pattern: an Agent declares what is available (skills, gateways (provider/model combinations), container image, prompt, typed parameters) and an AgentRun supplies concrete values (gateway selection, parameter values, instructions) to trigger execution.
The controller is domain-agnostic. It does not call Hub, Backstage, or any inventory system. Parameter values are opaque — the controller validates and passes them through. The creator of the AgentRun (UI, CLI, CI pipeline) resolves application metadata before creating the CR.
| CRD | Purpose |
|---|---|
| SkillCard | Individual skill or rule. Resolves to an OCI artifact mounted at /opt/skills/{name}/. |
| SkillCollection | Group of skills. References skills by OCI image, git source, or SkillCard CR name. |
| Gateway | LLM service endpoint serving one provider/model combination. |
| Agent | Template declaring available skills, gateways, container image, prompt, and typed parameters. |
| AgentRun | Execute a single Agent with specific values. Creates an Agent Sandbox. |
| AgentWorkflow | Ordered sequence of stages, each referencing an Agent. |
| AgentWorkflowRun | Execute a workflow. Creates AgentRuns sequentially per stage. |
- Agent Sandbox is a hard dependency for workload execution
- Git credentials stay in the harness — the agent does not receive push credentials
- Skills are OCI artifacts mounted via ImageVolumes (K8s 1.33+)
- Workspaces are ephemeral — git is the persistence layer
- ACP over HTTP (via
goose serve) provides real-time observability and human-in-the-loop interaction - Hub provides curated REST endpoints for the UI
See docs/adr/ for the full set of architecture decision records.
agentic-controller/
api/v1alpha1/ CRD type definitions (Go structs)
internal/controller/ Controller implementations
internal/registry/ OCI registry client
docs/adr/ Architecture Decision Records
skills/ Agent skills for contributors
CONTEXT.md Domain glossary
AGENTS.md Agent-facing instructions
- Kubernetes 1.33+ (ImageVolume GA)
- OpenShift 4.20+
- Agent Sandbox v0.5.x
| Project | Role |
|---|---|
| konveyor/enhancements | Enhancement proposals |
| konveyor/tackle2-hub | Application inventory, curated REST API for agent resources |
| konveyor/tackle2-ui | Web UI |
| kubernetes-sigs/agent-sandbox | Sandbox CRDs for agent workloads |
| redhat-et/skillimage | OCI skill packaging and distribution |
| NVIDIA/OpenShell | Secure runtime for autonomous agents |
Read AGENTS.md for project conventions. Use the skills in skills/
for design workflows — grill-with-docs for stress-testing designs
against the domain model.
Refer to Konveyor's Code of Conduct here.