AI Agent System Prompts Core Concepts

Welcome — this lesson explains the core concepts behind system prompts for declarative AI agents. System prompts are the single most important artifact when defining an agent: they set the agent’s role, behavior, and decision-making style. Good system prompts combined with the right tools and query handling produce reliable, useful agents. Prompt engineering for agents is a newer discipline compared with traditional software development. It requires iterative design, testing, and a different mental model—one that treats prompts, tools, and queries as co-evolving pieces of the agent’s behavior. Core concepts you must consider when writing system prompts:

1. Agent instructions
2. Tools
3. User queries

We’ll define each, show how they combine into an end-to-end workflow, and summarize design priorities and best practices.

​

1 — Agent instructions

Agent instructions are the heart of a system prompt. They tell the LLM:

• The agent’s role and domain expertise (for example: “You are an infrastructure expert.”)
• The agent’s goals and constraints
• Expected behaviors such as safety checks, confirmation steps, and error-handling rules

These instructions are provided alongside the user query to the LLM and influence both natural-language responses and the agent’s decision logic. Think of them as the agent’s personality and job description. Best practice examples:

• Define the agent’s role explicitly: “You are a Kubernetes troubleshooting assistant.”
• Explicitly state limits: “Do not delete resources without confirmation.”
• Provide examples of desired response style and level of detail.

​

2 — Tools

Tools are the functions, APIs, or capabilities the agent may call to interact with its environment. They are the agent’s “hands and eyes.”

• Examples for a Kubernetes-style agent: list_resources, get_logs, describe_service, delete_pod.
• Tools enable actions that go beyond text (query state, make changes, or call external APIs).
• The system prompt should document available tools and any usage constraints.

Tools are provided to the agent by the runtime environment. The agent decides when and which tool to call based on instructions and the user query.

​

3 — User query

The user query is the input that triggers the agent workflow.

• It supplies intent and task details the agent must satisfy.
• Designers have less control over user input, so anticipate likely variations and edge cases.
• Combine robust instructions and a well-chosen toolset to handle noisy or ambiguous queries.

​

End-to-end workflow

The agent workflow is the combination of:

• Agent instructions (role and behavior)
• Tools (what actions are available)
• User query (the task to perform)

These three inputs are passed to the LLM. The LLM evaluates the query in the context of the instructions, may call tools to gather state or take action, and returns a final response or result.

​

Key relationships

​

Agent instructions + Tools

• Instructions define what the agent should be and how it should behave.
• Tools define what actions the agent can take.
• Together they form the agent’s full capability set.

Example:

• Instruction: “You are an infrastructure expert.”
• Tools: list_resources, get_logs, describe_service
• Outcome: The agent understands operational tasks and can perform them programmatically.

Note: This lesson uses a container orchestration platform (Kubernetes) as a concrete example. The principles apply to other domains (databases, cloud infra, support bots, browsing agents, etc.).

​

Agent instructions + User query

• Instructions guide how to interpret and act on queries.
• Queries provide specifics and context for tasks.

Example:

• Instruction: “Always verify before making changes.”
• Query: “Delete resource xyz.”
• Result: The agent checks whether the resource exists and asks for explicit confirmation before deleting.

​

Tools + User query

• The query indicates which tools to use.
• Tools provide the mechanism to fulfill the request.

Example:

• Query: “Show me the logs for resource xyz.”
• Possible flow: call list_resources to locate the target, then get_logs to retrieve logs.

​

Design considerations (by priority)

Prioritize your design effort where it yields the most control and impact:

​

Best practices for writing system prompts

• Start explicit: state the agent’s role and primary objectives upfront.
• Declare capabilities and limits: enumerate what the agent can and cannot do.
• Describe behaviors: require confirmation flows, safety checks, and error-handling policies.
• Document tools in the prompt: list available tool names (e.g., list_resources, get_logs) and give usage examples.
• Anticipate user queries: include examples and edge cases the agent should handle.
• Test iteratively: simulate diverse queries and tool-call sequences before production.

Tip: Use short, deterministic rules for critical actions (deletions, credential changes) and keep conversational flexibility for information retrieval and diagnostics.

​

Key takeaways

• Agent instructions are the foundation—they define who the agent is and how it behaves.
• Tools are the mechanisms that allow the agent to interact with real systems.
• User queries drive action; they trigger the agent’s internal logic and tool usage.
• The combination of instructions, tools, and query handling produces practical, reliable agents.

Further reading and references:

• Kubernetes Basics
• Prompt engineering resources and best practices
• Consider runtime/tooling docs for your agent framework (tool registration, schema, and security).

As we’ve established the importance of system prompts, the next lesson will walk through how to build a concrete system prompt and register tools for an agent.