System Prompts for Agents
Why Prompting Matters
The Problem: An LLM without proper instructions is like a brilliant employee with no job description -- capable but directionless.
The Solution: Well-crafted system prompts transform a general-purpose LLM into a focused, reliable agent with clear behavior, tool awareness, and error handling strategies.
Real Impact: The difference between a mediocre agent and an excellent one is often just the quality of its system prompt.
Real-World Analogy
Think of a system prompt as an employee onboarding packet:
- Role Definition = Job title and responsibilities
- Tool Documentation = List of software and tools they can use
- Guidelines = Company policies and best practices
- Examples = Sample work from previous employees
- Constraints = What they should never do
Anatomy of an Agent Prompt
Identity & Role
Define who the agent is, its expertise, and personality. This anchors all subsequent behavior.
Capabilities
List what tools the agent can use, what actions it can take, and the scope of its abilities.
Instructions
Step-by-step guidance on how to approach tasks, handle errors, and format responses.
Constraints
Boundaries the agent must respect -- safety guardrails, scope limits, and fallback behaviors.
Without system prompt:
User: "Delete all records from 2020"
Agent: [executes delete immediately]
With system prompt ("Always confirm destructive actions"):
User: "Delete all records from 2020"
Agent: "I found 15,847 records from 2020. This action is
irreversible. Should I proceed? Please confirm with 'yes'."
Role & Persona Definition
Tool Descriptions in Prompts
# System Prompt for a Research Agent
You are a research assistant with expertise in technology topics.
## Your Tools
- web_search(query): Search the internet for current info.
- read_url(url): Read the full content of a web page.
- save_note(content): Save important findings for later.
## Instructions
1. Always search before answering factual questions.
2. Cite your sources with URLs.
3. If sources disagree, present both viewpoints.
4. Think step-by-step for complex questions.
## Constraints
- Never fabricate information or URLs.
- If you cannot find reliable info, say so clearly.
- Limit searches to 3 per question to manage costs.Common Mistake
Wrong: Writing tool descriptions like "search: searches stuff"
Why it fails: Vague descriptions cause the LLM to guess when to use tools and what parameters to pass. It may use the wrong tool or fabricate parameters.
Instead: Write detailed descriptions: "search_orders: Search customer orders by order_id, email, or date range. Returns order details including status, items, and tracking. Use when the customer asks about a specific order or order history."
Few-Shot Examples
messages = [
{"role": "system", "content": system_prompt},
# Few-shot example: demonstrate tool usage
{"role": "user", "content": "What is the latest Python version?"},
{"role": "assistant", "content": "Let me search for the latest Python release.",
"tool_calls": [{"function": {"name": "web_search",
"arguments": "latest python version 2026"}}]},
{"role": "tool", "content": "Python 3.14 released..."},
{"role": "assistant", "content": "Python 3.14 was released. [Source: python.org]"},
# Now the actual user query
{"role": "user", "content": actual_query}
]Prompt Templates
| Template | When to Use | Example |
|---|---|---|
| Role-Goal-Constraints | General-purpose agents | "You are X. Your goal is Y. Never do Z." |
| Tool-First | Tool-heavy agents | Lead with tool definitions and usage rules |
| Chain-of-Thought | Reasoning-intensive | "Think step-by-step before acting" |
| Output-Format | Structured output | Specify exact JSON schema in prompt |
Deep Dive: Few-Shot Examples for Tool Use
Including 2-3 examples of correct tool usage in the system prompt dramatically improves tool selection accuracy. Show the full flow: user message, agent reasoning, tool call with exact parameters, tool result, and final response. This teaches the model the expected format, when to use tools vs respond directly, and how to interpret tool results. For complex tools, one well-crafted example is worth paragraphs of description.
Quick Reference
| Principle | Do | Don't |
|---|---|---|
| Clarity | Be specific and explicit | Use vague instructions |
| Structure | Use headers and lists | Write a wall of text |
| Examples | Show desired behavior | Only describe abstractly |
| Constraints | State boundaries explicitly | Assume model will infer limits |
| Testing | Iterate and refine prompts | Write once and deploy |