How to Write AI Agent Prompt Instructions

The agent stopped on the first odd case, or it wrote something your team rewrote from scratch. The model was fine. The instructions were not. Vague scope, no output shape, and no stopping rule produce exactly that. The most useful thing you write before a first build is the instruction set, and it has to leave the agent very little to guess.

Schulhoff and colleagues surveyed 58 prompting techniques in 2024 (arXiv:2406.06608). The consistent finding is that structured instructions, with an explicit format and a clear stop, beat open-ended ones. This is the version of that finding you can write yourself for an operations agent. The survey is a PRISMA-grounded review of published prompting research, and the five fields below are derived from the categories that review actually groups, not from a template we invented for the page.

Why do most agent instructions fail?

When the agent does not know the task, what a correct result looks like, or when to stop, it either asks you on every step or hands you work you have to fix. Both are slower than the manual process you were trying to leave behind. Teams often describe that stall as a model problem. In the runs we review, the model did what an underspecified instruction invites: it guessed, or it waited.

What does a vague scope look like on a real account?

The vague version looks like "help the team with client updates." Which clients? What shape? Weekly or on demand? From the CRM, or only from what was pasted in? The agent will assume, and some of those assumptions will be wrong for your week. A wrong assumption in a client update is not a small style issue. It is a sentence the client reads as if your team wrote it, and then your team spends the afternoon explaining a fact the agent filled in because the instruction never named the source.

What happens when the task is named and the output is not?

The second failure describes the task and not the output. A weekly update needs a section count, the headers, the tone, and what to write when nothing happened. Without that, the team edits the format every time, or the agent writes three paragraphs when the client expected five lines. After a few of those edits, the person who was supposed to be freed from the draft is back inside it, which is how an agent gets quietly abandoned while the login stays active.

Can you finish the task in one sentence?

Before you write anything else, finish one sentence: "The agent reads [input], does [one operation], and writes [specific output] for [named recipient]." If you need "and" to join two operations, you have two tasks. Split them. A status draft and a send are two tasks. A summary and a recommendation the input does not contain are two tasks. The sentence is the whole scope test, and it takes less time than the first bad run.

What belongs in a complete instruction set?

The Schulhoff survey groups the techniques that improve instruction following into five categories: role, task, format, examples, and constraints. Those map to five fields. Leave one out and you can predict the failure. No role means the voice drifts. No constraints means the agent acts outside the job the moment the input is odd.

Which five fields does every working set include?

Write all five, in this order of appearance in the document the agent reads. First, a role statement that names what the agent is and who it serves. Second, a task definition that names the one operation, the inputs, and the output. Third, a format specification that includes structure and a length limit. Fourth, at least two worked examples, each with a sample input and the output you would accept. Fifth, constraints that name what the agent must never do, including the cases where it must stop. Omitting the examples is how you get a format that looks right and a judgment that is wrong. Omitting the constraints is how a thin week turns into invented activity.

Which field should you write first?

Write the role first and the task second. In our own operating rule, a clear role plus a clear task gets you about 60 to 70% of the way to a reliable agent. That range is our rule of thumb for drafting, illustrative, not a client result, and not a published study result. Add format and examples next. Write constraints last. Constraints written before you have seen an example tend to be too broad. The examples show you which limits actually matter, because you can point at a line in the sample and say that line is the one the agent must not cross.

What does a role that works actually say?

A role that works has three parts: what the agent is, who reads the output, and the one thing it produces. "You are a weekly status writer for the Meridian account team. Your readers are the three account managers. Your job is to draft the Friday client update for each active account from the data in the input." "You are a helpful assistant" is not a role. It names a mood, not a job, and a mood does not tell the agent who will be embarrassed if the draft is wrong. Name the function, the readers, and the artifact. Stop there.

How do you define the task for an operations agent?

Scope is two questions: what the agent may read, and what it must write. You do not control how it thinks. You control the inputs and the outputs. Trying to specify the reasoning step by step usually produces a longer prompt and the same guesses, because the model still fills any gap you left between the input list and the output shape.

How do you bound what the agent may read?

Name every source. If it may use the CRM, name the fields. If it may use only what was passed in, say that. "Use the available data" invites the agent to invent a field when the real one is thin. A bounded version you can paste and then edit: "You will receive a JSON object with three fields: account name, last activity date, and open action items. You have no other source. Do not infer anything that is not in those three fields." The word "infer" matters. Without it, the agent will treat a familiar account name as permission to recall a story that was never in the input.

When is the task finished?

The task is finished when it names the stop. Done means one draft per account in the input. It does not send, it does not revise unless asked, and it does not go looking for more. A missing stop is how you get a loop that keeps polishing because nobody said the work was over. Polishing looks like quality until you notice the second draft added a recommendation that was not in the three fields. Put the stop in the same paragraph as the task, not in a later footnote the run never reaches.

What does a weekly report instruction look like when you can copy it?

A weekly report scope you can copy and then replace with your own fields: read the three inputs for each account. Write one section per account with one sentence on last week's activity, up to three open items as a list, and one sentence on the next planned contact. If the last activity date is more than 14 days ago, add one sentence flagging the gap. Stop when the accounts in the input are done. Do not add commentary, a closing summary, or a recommendation that is not in the input. The 14-day gap sentence is the exception you already know you want. Write it here so the agent does not invent a different threshold on the third Friday.

What output format does the agent need?

Salesforce's 2026 State of Marketing asked 4,450 decision makers, from 8 October through 17 November 2025. In that survey, AI-tool adoption is 75%, generic campaigns are still 84%, and complete service-data access is 58%. Adoption and usable output are not the same thing. When the agent's output does not match what the team expected, the team edits it, and after a few rounds they stop using the agent. The format specification is how you keep the second week from becoming an editing job.

How do you match the format to the next step?

Match the format to the next step. If an account manager pastes the update into email, write email-ready prose: no markdown, no asterisks, no headers. If it lands in a dashboard field, specify plain text under a character limit. If a reviewer reads it in a document that already uses headings, markdown is fine, and you should say so. The output should be ready to paste into the next step with no reformatting. A format that is almost right still costs the same editing minute every Friday, and that minute is the reason the team goes back to the old doc.

How long should each section be?

"A summary paragraph" is ambiguous. "A paragraph of no more than 80 words" is not. Name the header exactly as it should appear, the content type, and the word or item limit for each section. That takes less than ten minutes for a typical operations agent and saves weeks of editing. Do this for the empty week too. If nothing happened, the instruction should say the sentence to write, not leave the agent to decide that silence needs a paragraph of reassurance.

Which three output types cover most operations work?

Most operations outputs are one of three types. Structured prose is sections with headers, in plain text, with no extra formatting. A structured list is headers, then bullets, with no nested bullets. Structured data is JSON or CSV with named fields. Pick one type per agent and name it in the instruction. Mixing them produces a different shape every run, and the person pasting the output cannot tell which shape is the mistake.

How do you handle the cases the agent was not built for?

A missing field, a value outside the range, an ambiguous request, or a request that needs data the agent was not given will otherwise halt, invent the missing piece, or look correct while being wrong. All three are worse than a clean stop. The invented piece is the dangerous one, because it reads like the rest of the draft and it ships if nobody is checking line by line.

What should the agent do when a field is empty?

For each input, write what happens when it is empty. Use a default ("if open items is empty, write 'No open items'"), skip the section ("if the last activity date is missing, omit the date sentence"), or stop and return an error that names which account is incomplete. The default without a rule is to guess, and a guessed date in a client update is a trust problem. Pick one behavior per field. "Use your judgment" is the guess you were trying to prevent.

When should the agent stop and ask a person?

Every production agent needs at least one escalation. A usable one: "If any required field is empty, or the input has fewer than three accounts, stop and return exactly: 'Input incomplete. Required fields: account name, last activity date, open action items. Accounts in input: [count].'" That one rule catches the incomplete paste before the agent writes a draft the team has to throw away. Add a second rule only after you have seen a second failure in real runs. A page of hypothetical stops is harder to test than one stop you can trigger on purpose.

How do you write an escalation so it can fire?

Write every escalation as two lines: the condition, and the exact message. "The agent should flag problems" is not an instruction. Keep the message short enough to paste into Slack without editing, and tell the agent to return that message and nothing else. If you allow a preface, the run will sometimes add advice, and the person on the other end will not know whether the job stopped or continued.

How do you test the instructions before anyone depends on them?

You do not need a separate test environment. You need three inputs you can run yourself before a client ever sees a draft. If any of the three fails, that input shows you which field to revise. Fix the instruction and run the same three again. Do not "fix" the output by hand and call the test passed.

What are the three inputs?

Run a typical input, the case you designed for, and check the format section by section against the specification. Run a minimal input, the smallest complete case, one account with one item in each field, and check that the agent produces the minimum valid output and does not pad or invent. Run a broken input, with one required field missing, and check that the escalation returns the exact message, including the count. All three have to pass before anyone uses the agent on a live account.

What does a passing run look like?

A pass means the output needs no edits before someone uses it. Not "pretty good," and not "right, but the headings are off." If the team edits before using it, the agent is not ready. Edit the instructions. The revision cycle is faster than editing every draft, and it improves the next run instead of only the one in front of you.

Which two extra edges should you try after the three pass?

After the three pass, try two more edges that are specific to you: more accounts than a normal run, and one account whose last activity date is in the future, which is a common entry error. Both tell you whether the length limit and the constraints still hold when the input is unusual but plausible. Write down which edges you tried and what the agent produced. That log is the start of the evaluation set. The fuller testing loop is in how to test an agent.

How do you know when to rewrite the instructions?

Count how often the team edits or throws away the output in a week. One edit a week is tolerable on a new agent. Five edits in the first week means the instructions have a pattern, not a bad day. Format errors point at the format field. Content errors point at the task. Unpredictable errors point at a missing exception. The pattern is the revision. A single weird account is not.

How do you keep the first two weeks of corrections?

For the first two weeks, keep a three-column note: date, what was wrong, what you changed. A shared doc is enough. If the same correction shows up more than twice, it belongs in the instructions. Those two weeks are the feedback you use to tighten the set. They are not proof that the agent was a mistake, unless the same correction keeps coming back after you have written it into the instruction.

Which two rewrites cover most early failures?

In our operating rule, two rewrites fix most early failures: tighten what "done" means so the agent cannot keep adding sections, or add the exception for the bad input the team actually hit. That "most" is our experience of the first week, illustrative, not a client result, and not a study percentage. Do the rewrite that matches the column in the log. A format complaint does not get fixed by adding another role sentence.

How do you label a revision so you can find it later?

Label every revision with a date and one line: "2026-09-13: added a stop for a missing last-activity date." When something breaks three months later, the history tells you which change to look at. Keep it in the same document, under the live version. If you overwrite the old text without the line, you will not know whether the regression came from the new stop or from a format tweak someone made the same afternoon.

What comes after the instructions are written?

The five fields, the three-input test, and the exception rules are a complete first set. The work is specification. For a task on a repeatable schedule, the agent versus a fixed script decision belongs before you write a word, and the build sequence covers the architecture around the instructions. Once the set is tested, get your free Systems Plan. We will tell you whether this workflow is ready to run. The weekly owner report is where the corrections should show up after it does.

How we know this.

Schulhoff et al., 2024 (arXiv:2406.06608), catalogued 58 text prompting techniques through a PRISMA-grounded review. The five fields here (role, task, format, examples, constraints) are derived from that taxonomy. Salesforce's 10th State of Marketing, fielded with 4,450 decision makers from 8 October through 17 November 2025 (State of Marketing 2026), is where the 75% adoption figure, the 84% generic-campaign figure, and the 58% service-data figure come from. The 60 to 70% drafting rule, the two-rewrite rule, and the three-input test are operating frames for a non-technical team, adapted from that taxonomy, not client results. No client outcomes are cited.