Agentic Controller

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.

Overview

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.

CRDs

Key design decisions

• Agent Sandbox is a hard dependency for workload execution
• Git credentials stay in the entry point — the agent does not receive push credentials
• Skills are Agent Skills directories, delivered as ordinary OCI images mounted via ImageVolumes (K8s 1.33+), git clones, or inline content
• 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.

Authoring images and skills

• Create an agentic base image — extend agent-base, build language images, publish them, and understand the harness contract.
• Create a SkillCard image — author, validate, package, publish, and reference skills and rules.

Getting started

See docs/getting-started.md for a step-by-step guide to deploying the controller, configuring a Gateway with LLM credentials, and creating your first AgentRun.

End-to-end testing

See test/e2e/README.md for Kind setup and commands for the full pipeline, skill delivery, workflow reconciliation, and Go E2E suites.

Project structure

agentic-controller/
  api/v1alpha1/           CRD type definitions (Go structs)
  api/skill/              Agent Skills frontmatter parsing and validation
  internal/controller/    Controller implementations
  internal/skills/        Skill assembly, and SkillCard materialization
  cmd/skill-loader/       The init container and enumeration Job binary
  config/defaults/        Curated content the operator installs on enable
                            (skill catalog, stage Agents, AgentWorkflow) —
                            applied verbatim, so no Gateways or gateway refs
  config/samples/         Illustrative CRs you copy and edit (per-provider
                            Gateways, a standalone Agent + AgentRun) — never
                            auto-installed
  docs/                   Documentation (getting started, entry point contract, API specs)
  docs/adr/               Architecture Decision Records
  harness/                In-pod entry point: git lifecycle, parameter delivery, ACP tee
  skills/                 Agent Skills directories:
    plan, execute,          shipped in the bundle image built by
    verify,                 skills/Containerfile; a SkillCard selects
    javaee-to-quarkus         one of them via subPath
    grill-me,               contributor skills for developing ON this
    grill-with-docs,        repo — deliberately not in the bundle image
    submit-pr
    examples/               SkillCard fixtures (not shipped)
    Containerfile           builds the skill bundle image
  CONTEXT.md              Domain glossary
  AGENTS.md               Agent-facing instructions

Platform requirements

• Kubernetes 1.33+ (ImageVolume GA)
• OpenShift 4.20+
• Agent Sandbox v1.0.x

Related projects

Contributing

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.

Code of Conduct

Refer to Konveyor’s Code of Conduct here.

Controller diagnostics

See controller memory diagnostics for continuous metrics capture, periodic memory logs, and opt-in heap profiling during OOM investigations.