Instruction: manage agent system prompts as Kubernetes resources

The Instruction CRD gives you a first-class Kubernetes resource for managing LLM system prompts. Instead of embedding a system prompt directly inside an Agent manifest — where it is easy to let it drift or go unreviewed — you create a standalone Instruction with a content field containing the prompt text. The operator stores this text in a ConfigMap and makes it available to any agent that references it. Because Instruction is a proper Kubernetes resource, you can version-control it, apply RBAC to it, diff it in pull requests, and share it across many agents without duplication.

API reference

apiVersion: agent.flokoa.ai/v1alpha1
kind: Instruction

Spec fields

The Instruction spec contains a single required field:

Field	Type	Required	Description
`content`	string	✅	The full system prompt text. Must be at least one character.

Creating an Instruction

apiVersion: agent.flokoa.ai/v1alpha1
kind: Instruction
metadata:
  name: customer-support-prompt
  namespace: production
spec:
  content: |
    You are a friendly and knowledgeable customer support agent for Acme Corp.
    Your goals are:
    - Answer customer questions accurately using the information available to you.
    - Escalate unresolved issues by creating a support ticket via the ticketing tool.
    - Keep responses concise — aim for three sentences or fewer unless detail is required.
    - Never speculate about product pricing or availability; direct customers to the sales team.
    - Always end the conversation by asking if there is anything else you can help with.

Apply it with:

kubectl apply -f customer-support-prompt.yaml

After reconciliation the operator creates a ConfigMap in the same namespace and records its name in status.configMapName.

Status fields

status:
  configMapName: "instruction-customer-support-prompt"
  observedGeneration: 1
  conditions:
    - type: Ready
      status: "True"
      lastTransitionTime: "2026-01-15T10:30:00Z"
      reason: ConfigMapCreated
      message: "Instruction ConfigMap created successfully"

Field	Description
`configMapName`	Name of the ConfigMap the operator created to store the prompt text
`observedGeneration`	Last spec generation reconciled by the operator
`conditions`	Standard condition array; the `Ready` condition carries error details

Referencing an Instruction from an Agent

Agents support two ways to attach a system prompt through spec.instruction: Inline — the operator creates a child Instruction CR automatically:

apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: support-agent
spec:
  instruction:
    template: "You are a helpful assistant. Be concise and accurate."
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/agent:v1.0.0
        ports:
          - containerPort: 8080

By reference — reuse a shared Instruction CR across multiple agents:

apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: support-agent
spec:
  instruction:
    instructionRef:
      name: customer-support-prompt
      namespace: production   # optional — defaults to the agent's namespace
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/agent:v1.0.0
        ports:
          - containerPort: 8080

The instructionRef approach is also required for the template runtime mode, where the operator builds the agent deployment from scratch and needs a stable reference to the system prompt.

A key benefit of the Instruction CRD is the ability to keep a single source of truth for a prompt and reference it from any agent in the cluster:

# Shared namespace hosts the canonical prompts
apiVersion: agent.flokoa.ai/v1alpha1
kind: Instruction
metadata:
  name: triage-prompt
  namespace: shared-resources
spec:
  content: |
    You are a triage agent. Classify incoming requests as "billing", "technical",
    or "general" and route them to the appropriate downstream agent.
---
# Team A's agent
apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: triage-agent-team-a
  namespace: team-a
spec:
  instruction:
    instructionRef:
      name: triage-prompt
      namespace: shared-resources
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/triage-agent:v1.0.0
        ports:
          - containerPort: 8080
---
# Team B's agent — same prompt, different runtime configuration
apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
  name: triage-agent-team-b
  namespace: team-b
spec:
  instruction:
    instructionRef:
      name: triage-prompt
      namespace: shared-resources
  runtime:
    type: standard
    spec:
      container:
        name: agent
        image: ghcr.io/example/triage-agent:v2.0.0
        ports:
          - containerPort: 8080

kubectl operations

# List all Instructions and the ConfigMaps they created
kubectl get instructions

# Inspect a specific Instruction
kubectl describe instruction customer-support-prompt

# Read the current prompt text
kubectl get instruction customer-support-prompt -o jsonpath='{.spec.content}'

# Check the operator-created ConfigMap
kubectl get configmap \
  $(kubectl get instruction customer-support-prompt -o jsonpath='{.status.configMapName}')

# Update the prompt by editing the manifest and reapplying
kubectl apply -f customer-support-prompt.yaml

# Delete an Instruction (also removes the operator-managed ConfigMap)
kubectl delete instruction customer-support-prompt

Best practices

Keep prompts focused — each Instruction should describe one agent persona or behaviour. Avoid combining unrelated responsibilities in a single prompt.
Version-control every Instruction manifest — because prompts directly influence agent behaviour, treat them with the same rigour as application code: peer review, changelogs, and staged rollouts.
Use namespaces to control sharing — place shared, canonical prompts in a dedicated namespace (e.g., shared-resources) and use RBAC to control who can modify them.
Prefer instructionRef over inline template for production agents — a standalone Instruction CR is easier to audit, update, and roll back independently of the Agent manifest.
Test prompt changes in a staging namespace before promoting them to production by creating a separate Instruction CR in your staging namespace and verifying agent behaviour.
Annotate with context — use metadata.annotations to record the author, last-reviewed date, and linked issue or pull request for each Instruction.

Get Started

Core Resources

Guides

Python SDK

Operations

Instruction: manage agent system prompts as Kubernetes resources

API reference

Spec fields

Creating an Instruction

Status fields

Referencing an Instruction from an Agent

kubectl operations

Best practices

​API reference

​Spec fields

​Creating an Instruction

​Status fields

​Referencing an Instruction from an Agent

​Sharing one Instruction across many agents

​kubectl operations

​Best practices

API reference

Spec fields

Creating an Instruction

Status fields

Referencing an Instruction from an Agent

Sharing one Instruction across many agents

kubectl operations

Best practices