Reusable prompt action

What is a reusable prompt action?

A reusable prompt action is a saved prompt with a name, declared inputs and a declared output, kept somewhere your systems can call it. A flow runs it as a step. An agent can pick it up as a tool it is allowed to call. The instruction is the same on every run, and it lives in one place instead of in six colleagues' chat history.

A prompt template already gives you the placeholders. An action adds the parts that make it callable: a name other systems reference, an output shape the next step can rely on, and a home with an owner. An agent skill sits a level higher, since it tells an agent how to carry out a whole procedure, while a prompt action is one bounded job inside it.

Microsoft's prompt builder, the AI Builder feature you reach through the AI hub in Power Apps and Power Automate, shows the shape most plainly. Its documentation describes an experience that "allows makers to build, test, and save reusable prompts", which you can then share and use in agents, workflows or apps. In a cloud flow the saved prompt turns up as a Power Automate action called Run a prompt. In Copilot Studio the same object is added under Tools, and a prompt created there can be used in any agent or topic.

Four things separate an action from a well-written paragraph of instructions.

• A name. Something like classify-supplier-email. A flow references that name and a colleague searches for it. "The mail prompt Jan wrote" is not a name.

• Declared inputs. In prompt builder each input is text or an image or document, and you type a sample value for it. That sample is the first test the prompt ever gets.

• A declared output. Text is the default. JSON with named fields is what makes the answer usable by the step after it.

• A home with a lifecycle. In Power Platform a prompt is a solution component, so it travels from a development environment to production inside a solution, and Microsoft's advice is not to edit an imported prompt afterwards.

The same prompt in six flows

Take a prompt that decides whether an incoming email is an order, an invoice or something else. It works, so it gets pasted into the mailbox flow, then the supplier portal flow, then a second mailbox for the French entity, where a colleague adds a line about credit notes and tells nobody.

You now have six prompts that started as one, and not one of them is labelled as a copy. When somebody complains that credit notes are being booked as invoices, nobody can say which prompt produced the answer, and repairing the one you found leaves the others alone. The failure is boring: copies drifting apart over eight months, and odd results nobody can trace.

The whole difference shows up on the day the prompt needs changing.

• A prompt pasted into each flow. You edit every copy you can find, the ones you miss keep running the old wording until somebody notices, and afterwards you are guessing which copy produced the odd answer.

• A named prompt action. You edit one object, every flow that calls it picks the change up on its next run, and there is one text, one version and one test result to point at.

That is also why a change to an action deserves a test before it goes live: it lands everywhere at once.

Design rules for a prompt action in a flow

Ask for one thing. A prompt that classifies the email, drafts a reply and decides whether to escalate is three actions wearing one coat, and changing the reply wording puts the classification at risk. Split them, and the flow calls the second action only when the first says it is needed.

Define the output as a fixed set of values or a small structure, not free text. A category field with five allowed values gives the flow something to branch on. A paragraph gives it a parsing problem. Microsoft's performance guidance points the same way for JSON output: keep the structure simple, keep the number of keys down, and only ask for a reason field when a person or an audit trail is going to read it.

Say what to do when the input does not fit. Prompts get written against the happy case and then meet an empty body, a scan with no readable text, a message in Portuguese, or a forwarded thread with four emails inside it. Put the rule in the instruction itself: if the message fits no category, return other and set needs_review to true.

Never let it invent a value the next step treats as real. If the invoice number is not in the document, an empty field is the correct answer and a plausible-looking number is a booking error. Write that into the instruction, allow null, and let the flow treat null as a routing decision rather than a crash.

A worked example: sorting supplier email

A wholesaler gets a few hundred supplier emails a week. The action is called classify-supplier-email. It takes two inputs, subject and body, both text. It returns this and nothing else:

{
  "category": "order_confirmation",
  "supplier_reference": "PO-88213",
  "needs_review": false
}

category may hold one of five values only: order_confirmation, invoice, delivery_note, price_change or other. supplier_reference is the reference exactly as it appears in the email, or null when the email has none. needs_review is true when the model had to fall back on other, when the reference is missing on a category that normally carries one, or when the email clearly covers more than one document type.

The failure path is the part people skip. Before the flow does anything with the answer it runs three checks: the response parsed as JSON, category holds one of the five allowed values, and supplier_reference is either null or matches the reference pattern the ERP uses. Any check that fails sends the email to a review queue with the raw model output attached, and the flow stops there. It does not retry quietly, and it does not create a record with a guessed category. A person sees that email the same day, and the case joins the test set.

Is the output shape guaranteed?

Whether a structured output is enforced or merely requested depends on the product, and that decides how much checking your flow has to do. Call a model API directly and the shape can be enforced for real. OpenAI's structured outputs constrain decoding against the JSON schema you supply, and the documentation says the model will always generate responses that adhere to it, so a missing required key or an invented enum value stops being a worry. Anthropic makes the same promise through constrained decoding. Neither guarantee survives a reply that never finishes, since a refusal or a token limit can cut one short.

Low-code prompt builders work differently. In Microsoft's prompt builder you do not write a schema at all: you paste an example of the JSON you want, the tool derives the format from it, that format is recorded when you save, and you cannot edit the generated schema. The documentation also lists an error you can meet while testing, "A JSON could not be generated". That is a check catching a malformed answer, which is not the same as a malformed answer being impossible.

That difference explains the failure mode of this whole shape. An output that is right ninety-five times in a hundred sounds excellent and is a broken flow one run in twenty. At three hundred emails a week that is fifteen runs where the next step gets something it cannot use. The action does not have to be perfect. The flow has to have somewhere to put the run where it was not: a branch for the parse failing, for a value outside the allowed set, for a required field arriving empty. The thinking part is deciding what the review queue is and who reads it before Friday.

Testing a saved prompt action

The Test button in a prompt builder proves the prompt runs. It says nothing about whether the prompt is right often enough to leave unattended. That takes a small set of known inputs with the answer you expect next to each one: thirty to a hundred real emails, each with its correct category and reference, in a file that lives with the action. Run the action over the set, count the matches, and you have a number to compare against next time. That is an eval set, and at this size it is a spreadsheet and an afternoon.

Run it again when you change the instruction, when you switch the model the action uses, and when the model changes without you asking. That last one is the one people miss. The model list in prompt builder says it in as many words: the default model "is periodically upgraded as new, more capable models become generally available". Your prompt did not change, your flow did not change, and your results can still move. Pin the model on anything that matters, and treat an upgrade as a change that needs the same evidence as an edit.

Naming and owning your prompt actions

Most small companies never need fifty of these. Look at what a company of twenty people actually automates with AI and you land on three or four: sort what comes in, pull the fields out of a document, draft a first reply in the house tone, and summarise a long thread for whoever has to decide. Everything else turns out to be a variation, and a variation is usually one extra allowed value.

That small number is the argument for treating them as company assets rather than personal tricks. Each one gets a name, one line saying what it decides, a named owner in the department that lives with the result, and its test set. Finance owns the invoice extraction, not whoever happened to build the flow, so when a supplier changes its invoice layout the owner is the person who notices. Keeping the history of the edits is a discipline of its own, and prompt versioning is where it belongs: what each version was tested on, which model it ran against, and how you put the previous one back.