Agent

An Agent is a coding or automation agent expressed as a Kubernetes object. The operator creates a single pod per Agent (the agentlet plus the runtime CLI), wires its model credentials, mounts its tools, and fires runs on a schedule or on demand.

A minimal Agent

1apiVersion: v1
2kind: Secret
3metadata: { name: claude-code-token, namespace: adaptive }
4type: Opaque
5stringData: { token: "sk-ant-REPLACE_ME" }
6---
7apiVersion: agentkube.io/v1alpha1
8kind: Agent
9metadata:
10  name: triage-bot
11  namespace: adaptive
12  labels:
13    agentkube.io/agentgroup: support-team   # agents sharing this share memory
14spec:
15  runtime: ClaudeCode          # ClaudeCode|Codex|OpenCode|Aider|Cline|Goose|Cursor|Custom
16  mode: supervised             # supervised (exploratory) | system (deterministic)
17  paused: false                # YAML-created agents default to paused: true
18  goal:
19    inline: |
20      Triage incoming GitHub issues: fetch new ones hourly, label, assign.
21  model:
22    name: claude-opus-4-7
23    provider: anthropic
24  agentToken:
25    secretRef: { name: claude-code-token, key: token }

Core fields

• runtime — which agent CLI runs in the pod; selects the image (see Runtime images).
• mode — supervised lets the agent pick its own steps; system executes a deterministic playbook.
• paused — manifests default to paused so you can review the resolved status before a run fires; set false to arm.
• goal — inline text or a configMapKeyRef.
• model + optional provider — model binding; when provider is omitted the reconciler picks the tenant default for the model family.
• agentToken — a Secret ref holding the runtime's API key (mapped to the runtime's token env var).

Runtimes & modes

Set spec.image to override the default runtime image, or use runtime: Custom with your own image. Each Agent is single-replica by design — the controller names the pod after the Agent; there is no replicas knob.

Tools

spec.tools filters what reaches the agent across every source (runtime built-ins and bastion Tools):

1  mcpRefs:
2    - name: github-tools
3  tools:
4    mode: allow          # all | allow | deny  (top-level, across all sources)
5    allow:
6      - Bash
7      - Read
8      - Edit
9      - "mcp:github-tools/*"
10    # per-source sub-filters also exist: native: {…}  bastion: {…}

Wake-up & scheduling

1  wakeup:
2    enabled: true
3    mode: interval          # interval | schedule | oneShot
4    interval: 15m
5    # schedule: "*/15 * * * *"   # when mode=schedule
6    jitter: 30s
7    concurrencyPolicy: Forbid    # Allow | Forbid | Replace
8    activeDeadlineSeconds: 1800
9    backoffLimit: 3

Memory & context

memory (scope agent or group; backend objectStore, pvc, or none) plus context (restore prior memory, pinned files, token budgets) control what each run remembers. Agents sharing the agentkube.io/agentgroup label and scope: group share a memory store.

Status

.status carries phase (Active | Paused | Error | Succeeded | Failed), ready/desired replicas, currentRun / recentRuns with token usage, resolvedMCPEndpoints, effectiveTools, and conditions (Ready, MCPBound, TokenResolved, ScheduleValid, MemoryAccessible). kubectl describe agent <name> is your first stop when a run won't fire.