How to Design a System Prompt for a Production Agent

Teams that run agents at scale tend to converge on a similar skeleton. OpenAI recommends four sections, usually in this order: identity, instructions, examples and context, with context near the end because it changes from request to request (OpenAI prompt engineering guide). Anthropic suggests distinct sections such as background information, instructions, tool guidance and output description, separated with XML tags or Markdown headers (Anthropic). For an agent that takes actions, add explicit scope limits and a stopping rule.

Here is a compact template for a billing support agent:

# Role
You are the billing assistant for Acme's customer portal. You help account
owners understand invoices, change plans and update payment details.

# Scope
- In scope: invoices, plan changes, payment methods, refunds under the policy below.
- Out of scope: legal or tax advice, any account other than the signed-in one.
- Hand off to a person when the customer disputes a charge or asks to close the account.

# How to work
- Look up the account before answering any question about it.
- If a request is ambiguous and the answer would change what you do, ask one question.

# Tools
- get_invoice: use for any question about a specific invoice.
- change_plan: only after the customer confirms the target plan by name.
- If a tool returns an error, read it, correct the input once, then explain the problem.

# Output
- Plain sentences, under 120 words unless the customer asks for detail.
- End with the action you took, or the one thing the customer needs to do next.

# Examples
<example>...</example>

# Context
<account>{{account_json}}</account>
<today>{{date}}</today>

The exact headers matter less than the separation. Anthropic notes that precise formatting "is likely becoming less important as models become more capable" (Anthropic). The real benefit is that a reviewer, and the model, can find the refund rule without reading everything else.

The most common failure in production prompts is pitching instructions at the wrong level. Anthropic describes two opposite mistakes. At one end, engineers hardcode "complex, brittle logic" to force exact behavior, which makes the prompt fragile and expensive to maintain. At the other end, they give high-level guidance that "falsely assumes shared context" (Anthropic). The target sits between the two: specific enough to steer, general enough to give the model heuristics it can apply to cases you did not foresee.

Three habits keep a prompt at the right altitude.

Attach the reason to each rule. "Never promise a delivery date" is a rule. "Never promise a delivery date, because carriers change them and a missed promise turns into a refund claim" is a rule the model can generalize from. When a customer asks whether a parcel will arrive before a holiday, the reason guides the answer even though the rule never mentioned holidays.

Use a few canonical examples instead of an edge-case list. Anthropic says teams often "stuff a laundry list of edge cases into a prompt" and recommends against it. Its advice is to curate a small set of diverse, canonical examples instead, because for a model examples are "the pictures worth a thousand words" (Anthropic). OpenAI gives the same advice for few-shot prompting: show a diverse range of inputs paired with the outputs you want (OpenAI prompt engineering guide).

Start minimal and add lines only for observed failures. Anthropic recommends testing a minimal prompt first, then adding instructions and examples to fix the failure modes you find. Minimal does not mean short. It means every line earns its place. PromptHub's review of open source agent prompts makes the same point: more words do not always make a better prompt, and a teammate should be able to read yours and understand the instructions (PromptHub).

A quick altitude test: if a first-week hire read only your system prompt, could they handle their first ticket? If they would need to ask what good looks like, the prompt is too vague. If they would need a flowchart to follow it, the prompt is too rigid.

In an agent, much of the system prompt's job is helping the model choose and use tools. PromptHub advises putting as much effort into tool names, descriptions and parameters as into the prompt itself, and treating the model like a developer reading your API documentation (PromptHub). Anthropic warns that a bloated tool set with ambiguous decision points is one of the most common failures: "If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better" (Anthropic).

Tool descriptions explain each tool on its own. The system prompt covers what no single description owns:

• Order of operations. "Look up the account before answering account questions" belongs in the prompt because it spans several tools.
• Confirmation rules. Name the actions that need the user's explicit go-ahead. PromptHub's breakdown of the Cline coding agent shows a prompt that asks for one tool per message and a wait for the result, so errors are caught before they cascade (PromptHub).
• Failure handling. Say what to do when a tool errors, returns nothing or returns something surprising. Splunk's guide to production agents lists ignoring error messages as an anti-pattern, because keeping errors in context stops the agent from repeating the same mistake (Splunk).
• Stopping rule. Say when the task counts as finished and the agent should hand control back.

The Manus team adds a structural habit worth copying. They give related tools consistent prefixes, such as browser_ and shell_, so the system can restrict the agent to one group of tools at a given step without rewriting the tool list (Manus).

A production agent may call the model dozens of times per task, and each call resends the system prompt. Model providers cache repeated prompt prefixes, which reduces latency and cost, but only while the prefix stays identical. OpenAI advises putting content you reuse at the beginning of the prompt to get the most out of prompt caching (OpenAI prompt engineering guide).

The Manus team calls cache hit rate the single most important metric for a production agent. They also name a common mistake: a timestamp, especially one precise to the second, at the top of the system prompt. Because models read text in order, a single changed token invalidates the cache from that point onward (Manus).

Four rules follow:

1. Put identity, scope, method, tool guidance, output contract and examples first. They change only when you ship a revised prompt version.
2. Put per-user and per-request data at the end: account details, retrieved documents and the date.
3. Serialize injected data deterministically. Manus points out that many JSON libraries do not guarantee key order, which can silently break caching (Manus).
4. Avoid adding or removing tools in the middle of a task. Tool definitions usually sit near the front of the context, so changing them invalidates the cache and can confuse the model about earlier tool calls (Manus).

Stability helps quality as well as cost. A prompt that is assembled differently on every call is hard to test, because no two runs saw the same instructions.

A system prompt can describe limits, but it cannot enforce them on its own. A prompt is text, and other text can contradict it: a user message, a retrieved web page or a tool result. LaunchDarkly's prompt guidance recommends telling the model explicitly to ignore instructions embedded in the data it processes, and setting role-based limits, such as a support bot that cannot issue refunds above a set amount or a financial assistant that must get human approval before a trade (LaunchDarkly). Maxim recommends regular adversarial testing for prompt leakage and access controls on who can edit the system prompt (Maxim).

Write those instructions, and then design as if they will sometimes fail:

• Enforce hard limits in code. If refunds above a threshold need approval, the refund tool checks the amount and refuses, whatever the model asks for.
• Give the agent only the tools its role needs. A tool that does not exist cannot be misused.
• Label untrusted content. Wrap retrieved documents and tool output in tags and tell the model that text inside them is data, never instructions.
• Assume the prompt will leak. Keep secrets, keys and other customers' data out of it entirely.

The prompt makes the right behavior the easy default. The code makes the wrong behavior impossible.

A prompt change is a behavior change, so it deserves the same process as a code change. OpenAI recommends storing production prompts in application code, where you get typed inputs, code review, tests and your normal deployment process, and adding representative fixtures and evaluation checks before changing a production prompt. It also recommends pinning production apps to specific model snapshots and building evaluation suites, because even snapshots within one model family can respond differently to the same prompt (OpenAI prompt engineering guide).

A workable release loop:

1. Collect real cases. Pull a few dozen representative requests from logs or support tickets, including the awkward ones.
2. Write expected outcomes. For each case, record what a correct reply or action looks like.
3. Run the current prompt and the candidate side by side. Compare pass rates and read every failure.
4. Ship behind a flag. LaunchDarkly describes A/B testing prompt variants and keeping a fallback configuration ready in case a variant misbehaves (LaunchDarkly).
5. Read traces after launch. Splunk recommends tracking at the session level whether the agent completed the task, and at the step level whether it chose the right tool and followed the context it was given (Splunk).

Pay special attention to long sessions. Splunk describes context poisoning, where an early hallucination is written into the agent's goals or notes and then reread at every step, so the error compounds (Splunk). An instruction to verify a fact with a tool before recording it as settled helps, but only traces will tell you whether it works.

If you would rather not write every procedure into one prompt, keep the core prompt short and load task-specific instructions on demand. Quanta Intelligence publishes skills and playbooks built for that pattern.

Run through this list before a system prompt reaches real users:

• The first few lines name the agent's user, its job and its scope.
• Every rule that matters carries its reason.
• Out-of-scope requests and hand-off conditions are listed.
• Each tool has a one-line "use when" rule, and the prompt says what to do when a tool fails.
• There is an explicit stopping rule and an output contract with one example.
• Static content comes first, and dynamic data is injected at the end in a deterministic format.
• No secrets, keys or other customers' data appear anywhere in the prompt.
• Hard limits are enforced in tool code, not only described in prose.
• The prompt lives in version control with an evaluation set that runs before each change.
• Someone reads production traces after every release.