Prompt versioning is the least glamorous part of building agents in Microsoft Foundry, and the first thing you will wish you had done properly.

Here is a situation I have seen more than once. An agent has been live for a few weeks and is behaving well. Someone in the team notices it is a bit too verbose, so they open the Foundry portal, adjust a couple of lines in the instructions, and save. It is a small change and it takes thirty seconds.

On Monday, quality has dropped. The agent has started answering questions it should be deflecting. Nobody can say precisely what the prompt said before, when it changed, or who changed it. The only artefact of the change is the current contents of a text box.

The system prompt is the highest leverage piece of your agent. It defines behaviour, tone, scope, refusal conditions, and output format. In most agent projects it has more influence on quality than the model choice does. And in a lot of teams it is the only component with no version control, no review, and no test coverage.

This post covers how to fix that in Microsoft Foundry, in the order I would tackle it.

Step 1: Know what the platform already gives you

Foundry Agent Service does some of this for you. As you iterate on an agent, versions are snapshotted automatically, and you can roll back to a previous version or compare changes between versions. Publishing promotes an agent to a managed resource with a stable endpoint.

This is genuinely useful and it will save you the first time someone breaks production. But understand what it is: a safety net, not a process. Automatic snapshots tell you what the prompt used to say. They do not tell you why the change was made, what problem it was solving, who reviewed it, or whether anyone tested it before it went live. That context lives in your team’s heads and evaporates in about a fortnight.

So use versioning and rollback, absolutely. Just do not mistake it for a prompt management strategy.

Step 2: Move prompts into Git as real files

This is the change that makes the biggest difference, and it is not technically hard.

Microsoft’s own GenAIOps guidance is to treat prompts as versioned assets in a repository, with a defined structure for collaboration and a workflow for testing and promoting versions safely. The Microsoft Learn labs use a very simple pattern: a prompts/ directory containing v1_instructions.txt, v2_instructions.txt, v3_instructions.txt, each a progressively more developed version of the agent instructions, deployed from a script so the versions can be compared side by side.

It is unglamorous and it works. What you get out of it:

• A diff. You can see exactly what changed between v2 and v3, line by line.
• A reason. The commit message and PR description capture why.
• A reviewer. Prompt changes go through the same PR process as everything else, which means a second pair of eyes on the thing that governs your agent’s behaviour.
• Blame, in the good sense. When quality shifts, git log on the prompt file is your first stop rather than your last resort.

If you do nothing else from this post, do this one.

Step 3: Deploy prompts, do not paste them

Once prompts live in the repo, the portal should stop being the place where they get edited.

Read the instructions from the file at agent creation or update time, and pass them in through the SDK. Something as simple as this is enough to start:

from pathlib import Path
PROMPT_VERSION = "v3"
instructions = Path(f"prompts/{PROMPT_VERSION}_instructions.txt").read_text()
agent = client.agents.create_agent(
    model="gpt-4o",
    name=f"support-triage-{PROMPT_VERSION}",
    instructions=instructions,
)

The important part is not the code, it is the discipline. Once the prompt is read from a versioned file and the version is baked into the agent name or metadata, your Git history and your Foundry agent version history line up. You can point at a live agent and say which commit produced it. Until you can do that, you are guessing.

A related habit worth forming: if your prompt contains anything environment-specific, such as a support email address, an escalation threshold, or a knowledge source name, template it rather than hardcoding it. Otherwise you end up with near-identical prompt files per environment and a merge conflict every time you edit the shared parts.

Step 4: One change per version, and evaluate it

The most common way teams waste prompt iterations is bundling.

Five tweaks go into one version. Quality moves. Now nobody knows which of the five did it, whether two of them cancelled each other out, or whether the win came from something incidental. You have spent an iteration and learned nothing generalisable.

Change one thing per version, run the same evaluation set against each version, and record the result alongside the prompt. Even a lightweight approach helps: twenty representative inputs, expected behaviours written down, scored consistently. The point is not statistical rigour, it is having a fixed yardstick so that “this version is better” is a measurement rather than a vibe.

This also builds the asset you need for the next step.

Step 5: Line yourself up for Agent Optimizer

Agent Optimizer (Agent optimizer in Foundry Agent Service overview (preview) – Microsoft Foundry | Microsoft Learn) in Foundry Agent Service, which entered private preview in June 2026, automates the loop. It consumes production traces and evaluations from hosted agents, generates ranked candidate improvements across prompts and skills, validates each candidate against your scenarios and constraints, and recommends a winner with full lineage, diffs, audit, and rollback.

That is a genuinely significant capability, and it is worth noting what it assumes. It runs on traces and evaluations. If you have no evaluation set and no trace data, there is nothing for it to optimise against and nothing to validate candidates with. The teams who get value from it on day one will be the teams who already did steps 2 to 4.

Which is the general theme here. Every improvement in the tooling rewards the teams who already have their prompts under version control and their quality measured. The tooling does not replace that foundation, it compounds on top of it.

A note on Prompt Flow

If your current prompt management story lives inside Prompt Flow, there is a deadline attached. Prompt Flow is being retired, with migration to Agent Framework workflows required by 20 April 2027 (Prompt flow is being retired | Microsoft Community Hub).

Treat that migration as an opportunity rather than a chore. The temptation with any forced migration is to lift and shift, reproducing the existing setup in the new tool as faithfully as possible. If your existing setup has prompts living inside flow definitions rather than in versioned files, lifting and shifting means carrying the problem across into a platform you will be on for years. Do the extraction while you are in there anyway. Microsoft even made a nice guide to show you how to migrate: Migrate from Prompt Flow to Microsoft Agent Framework in Foundry (classic) – Microsoft Foundry | Microsoft Learn.

The short version

Prompts are code. They change behaviour, they can regress, and they need the same treatment as everything else you ship:

1. Use Foundry’s automatic versioning and rollback, but do not stop there.
2. Keep prompts as files in Git, reviewed through PRs.
3. Deploy prompts from the repo, do not edit them in the portal.
4. One change per version, evaluated against a fixed set.
5. Get traces and evaluations in place so Agent Optimizer has something to work with.

None of this is difficult. It is just easy to skip, right up until the Monday morning when you cannot explain why your agent changed its mind about something.