Prompt Structure - KodeKloud

In the previous lesson we covered core concepts of system prompts. This lesson focuses on prompt structure and practical details — how to design a clear, actionable system prompt for an agent that manages Kubernetes clusters.

High-level advice: start with a single, well-scoped objective. Avoid combining unrelated roles into one agent — a focused agent is more reliable and easier to secure. We will construct system prompts incrementally:

Start simple (role + purpose).
Add available tools.
Add detailed tool descriptions (parameters, outputs, when to use).
Define operational protocols (assessment, plan, execute, verify).
Add safety guardrails and confirmations.

A presentation slide titled "Introduction" with three colored circular icons and captions outlining a tutorial: "How to build a system prompt step by step," "Starting simple and adding complexity," and "Best practices for prompt structure." The slide uses a dark background and simple line icons.

Start simple: define the role and the purpose so the agent has a single primary objective. Example basic system prompt:

You are a Kubernetes agent. You help users manage their Kubernetes cluster.

This sets role and purpose but is not actionable: it omits available commands, expected inputs/outputs, and operational behavior. Add those next.

A presentation slide titled "Introduction" showing a "Start Simple" step. Below it is a two-column box with a green check listing positives (defines the agent's role; states the purpose) and a red X listing negatives (not enough detail; doesn't tell the agent what it can do).

Add tools: make a compact, explicit list of the tools the agent can call. Name each tool and give a one-line description so the agent can map user intent to concrete actions. Example tools list:

You can use the following tools to help users manage their Kubernetes cluster:

 list_resources: List all resources of a given type in the cluster

 get_all_resources: Get all resource types in the cluster

 get_pod_logs: Get the logs of a pod

 apply_resource: Apply a resource manifest to the cluster

Tool names help, but the agent needs usage details: required parameters, expected outputs, default behaviors, and whether a tool mutates the cluster.

A presentation slide titled "Introduction" showing step "02 Add Tools." A two-column box lists pros (green check) like "lists available tools" and "agent knows what it can do" and a con (warning icon) noting "still needs more detail on tool usage."

Detailed tool documentation — what to include for each tool:

Required parameters and expected formats (for example, resource_type, namespace, pod_name, manifest_url).
Whether the tool is read-only or can mutate the cluster.
When to choose this tool (mapping from user intent to tool).
Default behaviors (for example, default namespace = default vs. --all-namespaces).

Practical example guidance for the tools above:

list_resources — Use when the user asks for a list of resources of a specific type (e.g., “list pods” or “show deployments in namespace X”). Accepts resource_type and optional namespace. If resource_type is missing, ask a clarifying question instead of calling the tool.
get_all_resources — Use to enumerate all resource kinds present in the cluster (useful for discovery or inventory).
get_pod_logs — Use to fetch logs for a specific pod; accepts pod_name, optional container_name, and namespace. Prefer get_pod_logs only after confirming the correct pod via list_resources.
apply_resource — Use to apply a YAML manifest provided inline or via a URL. Require the agent to validate the manifest, confirm target cluster and namespace, and warn about potential blast radius before applying.

A dark-themed presentation slide titled "Introduction" with an illustrated person using a laptop and a speech bubble saying "You're a Kubernetes agent. You help users manage their Kubernetes cluster." To the right is a text panel describing a tool called "get_all_resources" for managing Kubernetes resources.

Tool reference (compact summary)

Tool	Purpose & When to Use	Parameters & Behavior
`list_resources`	List resources of a specific kind (pods, deployments, services). Use for targeted discovery.	`resource_type` (required), `namespace` (optional). Read-only. If missing `resource_type`, ask a follow-up question.
`get_all_resources`	Enumerate all resource kinds in the cluster for inventory/discovery.	No parameters required. Read-only. Useful as a first discovery step.
`get_pod_logs`	Retrieve logs for a specific pod to troubleshoot issues.	`pod_name` (required), `container_name` (optional), `namespace` (optional). Read-only. Confirm pod identity via `list_resources` first.
`apply_resource`	Apply a YAML manifest or URL to create/update resources.	`manifest` or `manifest_url` (required). Mutating. Validate manifest, confirm cluster & namespace, require explicit confirmation for changes.

A few practical rules for tool usage:

Validate required parameters before calling a tool. For instance, confirm a resource_type for list_resources.
Normalize user language to canonical Kubernetes kinds (map “app”, “application”, or “svc” to deployments, services, etc.).
Chain tools deliberately: discover with get_all_resources or list_resources, then inspect with get_pod_logs or other read-only tools, and only mutate with apply_resource after validation and confirmation.
For mutating operations (apply/delete), accept either a full manifest or a reference (URL, kind/name). For deletes, permit both full manifest or resource identifiers.

Operational protocols — define how the agent assesses, plans, executes, and verifies changes:

Initial assessment: confirm cluster context, access level, and the scope of the requested change. Ask clarifying questions for missing critical details.
Execution strategy: prefer read-only checks first, validate intended changes, make incremental updates, and verify results after each step.
Verification & documentation: after executing a change, run verification checks (status, events, logs), and record actions and outcomes.
Troubleshooting approach: narrow root cause systematically — review logs, events, metrics, configuration, and recent changes before proposing or applying fixes.

A presentation slide titled "Introduction" with a highlighted "Add Behavior Guidelines" badge and a rounded text box listing an operational protocol for Kubernetes cluster management. A simple illustration of a person sitting with a laptop appears on the left against a dark background.

Safety and guardrails — include explicit constraints in the system prompt:

Default to non-destructive, read-only actions unless the user explicitly requests a mutating operation.
Always confirm the target cluster and namespace before any mutating operation.
Consider blast radius and prefer small, reversible changes.
Back up critical configuration before editing.
When unsure, ask clarifying questions instead of taking action.

Be explicit in the system prompt about required confirmations, parameter validation, and the agent’s default safety-first behavior. This reduces accidental destructive actions and makes agent behavior more predictable.

Do not perform mutating operations (for example, apply_resource) without explicit, unambiguous confirmation that includes target cluster and namespace, and a description of the intended change.

System prompt checklist — what a complete prompt should include:

Component	Why it matters
Single clear role & purpose	Keeps behavior focused and predictable.
Tools list (names + short descriptions)	Allows intent → capability mapping.
Detailed tool docs	Enables correct parameter use, chaining, and expected outputs.
Operational protocols	Defines assessment, execution, verification, and documentation steps.
Safety guardrails & confirmation rules	Prevents accidental destructive actions and clarifies required approvals.

Summary

Start with a single, explicit role and primary objective.
Enumerate available tools with concise descriptions.
Provide detailed tool documentation: parameters, formats, read/write behavior, and when to use each tool.
Define operational protocols for assessment, execution, verification, and troubleshooting.
State safety guardrails and explicit confirmation requirements for mutating actions.

Being explicit about behavior, tools, and safety significantly improves agent reliability and reduces risk. Further reading and references

Watch Video