Building Agents
MDX
How to Write an Agent System Prompt
Design instructions that define purpose, boundaries, tool behavior, and escalation without becoming brittle.
Editorial review: clarity, operational relevance, safety boundaries, and source quality.
Define the operating role
State the agent's job, intended users, and concrete definition of success. A narrow role helps the model prioritize relevant actions when several paths look plausible.
Start with a short hierarchy: purpose, scope, sources of truth, allowed actions, and completion criteria. Describe the user-facing result rather than a personality. If the prompt must explain dozens of business rules, those rules probably need a policy service or deterministic validation layer.
Separate policy from procedure
Policies describe constraints that always apply; procedures describe a preferred way to work. Keep critical security controls in code even when the prompt explains them.
Policies should be unambiguous and testable—never expose secrets, never write without a valid approval. Procedures can be flexible—search the account before asking the user to repeat information. Labeling the distinction helps the agent adapt its method without treating safety boundaries as suggestions.
Specify uncertainty behavior
Tell the agent when to ask, verify, refuse, or escalate. Examples of borderline cases are often more useful than long lists of abstract rules.
Define how uncertainty changes behavior. Specify which missing fields require a question, which claims require a tool, when conflicting evidence triggers escalation, and what the agent should return when limits are reached. Test paraphrases and adversarial inputs; do not optimize the prompt around one happy-path transcript.
Practical example
A compact support prompt
The prompt states that the agent explains billing records to the authenticated account holder, must use billing tools for account-specific claims, may draft but not execute adjustments, and succeeds when the question is answered with record evidence or handed off with missing information listed. Examples cover a routine charge, a disputed identity, and conflicting records. Authorization remains enforced by the tool layer.
Field checklist
Apply it in practice
- State purpose, scope, and sources of truth.
- Separate non-negotiable policies from flexible procedures.
- Define ask, verify, refuse, and escalate conditions.
- Regression-test prompt changes on a stable case set.
Decision framework
Questions to answer before you build
A system prompt should clarify purpose, boundaries, sources of truth, and uncertainty behavior. It should not become a fragile substitute for policy services and runtime enforcement.
What does success mean?
Describe the supported user outcome and the evidence required to claim completion. Avoid vague roles such as helpful general assistant.
Which rules are policies?
Separate non-negotiable constraints from preferred procedures. Enforce security, permission, and business invariants in code.
How should uncertainty change behavior?
Specify when to ask, retrieve, verify, refuse, or escalate, including examples near the boundaries of scope.
Common failure signals
Watch for these warning signs
- Adding instructions indefinitely instead of fixing weak tools or state.
- Using conflicting priorities without a clear hierarchy.
- Optimizing the prompt against one impressive transcript rather than a stable evaluation set.
Selected primary references
Continue with the source material
These sources inform the wider editorial perspective for this topic. They are not presented as line-by-line citations for every statement.