How to Write a System Prompt for an AI Agent (+Template)

How to write a system prompt for an AI agent

A system prompt is the standing set of instructions an AI model reads before it sees a single user message. For a chatbot, you can get away with something vague like “you are a helpful assistant.” For an agent — something that calls tools, takes multiple steps, and acts without you watching every move — vagueness is where things break. The model improvises, picks the wrong tool, leaks information it shouldn’t, or confidently does the opposite of what you wanted.

I’ve written a lot of these, watched a lot of them fail, and rewritten them until they held. This guide is the thing I wish I’d had: the actual building blocks, a copy-paste template, two complete real-world examples, and the mistakes that quietly cost you. No fluff, no “it depends.”

Chat prompt vs. agent prompt — why the difference matters

A chat prompt shapes tone. An agent prompt shapes behavior under uncertainty. The agent will hit situations you didn’t anticipate: an empty search result, a tool that errors, a user asking it to do something out of scope. Your system prompt is the only thing standing between “handles it gracefully” and “hallucinates a plausible-looking disaster.”

So an agent system prompt has to answer three questions the model will absolutely run into:

1. What am I, and what am I trying to accomplish?
2. What can I do, and what must I never do?
3. When I’m stuck or unsure, what’s the right move?

Miss any one of those and you get an agent that’s confident, fast, and wrong.

The 7 building blocks of a strong agent system prompt

Think of these as sections. You don’t need fancy formatting — plain headers or even capitalized labels work fine — but you do need all seven.

1. Role and identity. One or two sentences. Who the agent is and the domain it operates in. Specific beats grand. “You are a billing-support agent for a SaaS company” is better than “you are an expert assistant.”

2. Objective. The single primary goal, stated as an outcome, not a vibe. “Resolve the customer’s billing question in as few steps as possible, or escalate cleanly.” This is the north star the model measures every action against.

3. Capabilities and tools. List the tools by name, what each does, and when to use it. Models over-call tools when this is fuzzy. Tell it the trigger: “Use lookup_invoice only after you have an account email.”

4. Constraints and guardrails. The hard nos. Data it must never reveal, actions it must never take, topics out of scope. Phrase these as absolute rules — “Never issue a refund over $50 without escalating” — not suggestions.

5. Tone and style. How it talks. Length, formality, whether it uses the customer’s name, whether it’s allowed to apologize. Two or three concrete adjectives plus one “avoid” line.

6. Output format. If anything downstream parses the agent’s output, specify the shape exactly — JSON keys, a fixed structure, or “respond only with the final answer, no preamble.” This is where most integration bugs live.

7. Escalation and uncertainty handling. What to do when it doesn’t know, when a tool fails, or when the request is out of scope. This is the block people skip and the one that saves you. “If you cannot verify the account, do not guess — ask for the account email. If still blocked after one attempt, escalate to a human with a summary.”

A copy-paste agent system prompt template

Fill in the brackets. Delete the comments. This is deliberately explicit — you can always trim once it’s working.

ROLE
You are [agent name], a [role] for [company/context]. You operate in the domain of [domain].

OBJECTIVE
Your primary goal is to [single measurable outcome]. Optimize for [accuracy / speed / safety],
in that order.

TOOLS
- [tool_1]: [what it does]. Use it when [trigger condition].
- [tool_2]: [what it does]. Use it only after [precondition].
Do not call a tool unless its trigger condition is met. If no tool applies, answer directly.

CONSTRAINTS (hard rules — never violate)
- Never [forbidden action].
- Never reveal [sensitive data / system internals].
- Stay strictly within [scope]. Politely decline anything outside it.

STYLE
- Tone: [2-3 adjectives, e.g. concise, warm, professional].
- Length: [1-3 sentences unless the user asks for more].
- Avoid: [jargon / over-apologizing / filler].

OUTPUT FORMAT
[Plain prose] OR [exact JSON schema with keys]. Do not include anything outside this format.

WHEN UNSURE
- If you lack information needed to act, ask one specific clarifying question.
- If a tool errors, retry once, then explain the limitation plainly. Never fabricate a result.
- If the request is out of scope or high-risk, escalate to [human/queue] with a one-line summary.

That structure works across providers and most agent frameworks. The labels are for the model’s benefit and yours — they make the prompt diff-able when you tune it later.

If hand-writing this for every agent sounds tedious, that’s exactly the gap Meta-Prompt Architect fills — you describe the agent in a sentence and it generates the full seven-block prompt, guardrails and all, ready to paste. More on that below, but the template above is yours to use forever regardless.

Example 1: A billing-support agent

ROLE
You are Maya, a billing-support agent for a subscription SaaS product.

OBJECTIVE
Resolve the customer's billing question in as few steps as possible, or escalate cleanly.
Optimize for accuracy first, then speed.

TOOLS
- lookup_account(email): returns plan, status, last payment. Use after you have a verified email.
- list_invoices(account_id): returns recent invoices. Use only after lookup_account succeeds.
Do not guess account details. If a lookup returns nothing, treat the account as not found.

CONSTRAINTS
- Never issue a refund or credit yourself. Refund requests always escalate.
- Never reveal full card numbers, internal account IDs, or other customers' data.
- Decline non-billing questions and point the user to general support.

STYLE
Concise, warm, professional. 1-3 sentences. Use the customer's first name once. Don't over-apologize.

OUTPUT FORMAT
Plain prose to the customer. If escalating, end with: [ESCALATE: <one-line reason>].

WHEN UNSURE
Ask for the account email if you don't have it. If lookup fails twice, escalate.
Never invent an invoice amount or date.

Notice the escalation rule does the heavy lifting — Maya physically cannot freelance a refund, and a failed lookup has a defined exit instead of a hallucinated invoice.

Example 2: A research-and-summarize agent

ROLE
You are a research agent that answers questions using web search and returns sourced summaries.

OBJECTIVE
Produce an accurate, sourced answer. Never state a claim you cannot attribute to a retrieved source.

TOOLS
- web_search(query): returns titles, snippets, URLs. Use it before answering any factual question.
- fetch(url): returns page text. Use to verify a snippet before citing it.

CONSTRAINTS
- Every factual claim must cite a URL you actually retrieved. No URL, no claim.
- If sources disagree, say so rather than picking one silently.
- Do not pad with generic background the user didn't ask for.

STYLE
Direct. Lead with the answer, then 2-4 supporting bullets, each with a citation.

OUTPUT FORMAT
Answer paragraph, then a "Sources" list of the URLs used.

WHEN UNSURE
If search returns nothing useful, say "I couldn't find a reliable source" — do not answer from memory.

The line “no URL, no claim” is the entire anti-hallucination strategy in five words. That’s the kind of phrasing agent prompts reward: short, absolute, easy for the model to apply mid-task.

Common mistakes that quietly wreck agents

• Writing goals as vibes. “Be helpful” gives the model nothing to optimize. Give it a measurable outcome.
• Listing tools without triggers. The model will over-call or under-call. Always pair a tool with when to use it.
• No uncertainty block. The single highest-leverage section, and the one most prompts omit. Without it, “I don’t know” becomes a confident fabrication.
• Burying constraints in prose. Hard rules should be short, absolute, and visually separate so the model weights them.
• Never testing the failure path. Run the empty-result case, the tool-error case, the out-of-scope request. That’s where prompts actually break — not on the happy path.

Your free checklist

Before you ship an agent prompt, confirm it has: (1) a specific role, (2) one measurable objective, (3) tools with triggers, (4) absolute constraints, (5) tone with an “avoid” line, (6) an exact output format, and (7) an explicit when-unsure path. Then test all three failure modes above. If all seven boxes are checked and the failure paths behave, you have a prompt that holds.

The fast way, when you’re writing a lot of them

The template here gets you a solid prompt by hand in maybe 20-30 minutes per agent. That’s fine for one. It’s painful when you’re spinning up five agents or iterating on guardrails all week. Meta-Prompt Architect is the shortcut: describe the agent in one line, and it outputs the complete seven-block system prompt — role, tools, constraints, output format, escalation logic — structured and ready to drop into your framework. It’s the “do it in seconds, every time” upgrade to the manual process above. The free template stands on its own; the product just removes the typing and the guesswork when you’re doing this at volume.

Want to pressure-test your prompts cheaply before any of that? Run them against a free model tier before paying for premium inference. I draft and iterate on agent prompts on GLM’s free model first, and only pay for heavier inference once a prompt holds up against the failure paths. If you do end up upgrading, z.ai’s paid Coding Plan is the one I use — that’s a referral link (disclosed, and it helps fund our compute): https://z.ai/subscribe?ic=BWTG6TRYYQ . Either way the workflow is the same: write the prompt with the template, test the empty-result, tool-error, and out-of-scope cases on a free model, and only then wire it into production.