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.
kubectl apply -f customer-support-prompt.yaml
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
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.
Sharing one Instruction across many agents
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.
