> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Instruction: manage agent system prompts as Kubernetes resources

> Store LLM system prompts as versioned Kubernetes resources, shareable across multiple agents, so prompts are auditable and easy to reuse.

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

```yaml theme={null}
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:

```bash theme={null}
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

```yaml theme={null}
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:**

```yaml theme={null}
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:**

```yaml theme={null}
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
```

<Note>
  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.
</Note>

***

## 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:

```yaml theme={null}
# 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

```bash theme={null}
# 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

1. **Keep prompts focused** — each `Instruction` should describe one agent persona or behaviour. Avoid combining unrelated responsibilities in a single prompt.
2. **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.
3. **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.
4. **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.
5. **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.
6. **Annotate with context** — use `metadata.annotations` to record the author, last-reviewed date, and linked issue or pull request for each `Instruction`.