The Three-Platform Grammar

Copilot Studio fits a workload where a department owns the agent and no developer should be in the loop to change it. Microsoft Foundry fits where governance, evaluation gates and per-run cost attribution are the deciding factors. The Microsoft Agent Framework fits where several agents must coordinate on work too large for one. These are not a spectrum of sophistication: they are three distinct answers to three distinct questions.

Identifying the right question comes before naming the platform. Four questions settle most choices before capability is discussed at all: where the data may be processed, which identity governs the call, what has to be provable months later, and who may change the agent once it runs.

An agent that cannot be changed by its business owner without developer intervention is miscategorized, regardless of which platform was chosen.

Decisions Taken on Running Systems

Every decision on this page was taken on a system that runs, including the ones that were taken twice because the first answer was wrong.

Magentic teams fail against the Microsoft Foundry Responses API with a manager ledger error. The working configuration is the OpenAI-compatible Chat Completions client instead. That is the class of failure that takes days to diagnose and minutes to apply, which is why it lives in the repository’s skills rather than in someone’s memory. The next project starts from the answer rather than from the same unknown.

Topology is decided per workload rather than per project, and lifecycle drives the split. One content pipeline runs as two independently hosted Microsoft Foundry agent services because an optimize-and-translate router and a research-plus-writing team change at different rates. Each deploys without waiting on the other, which is the point of the split.

A Decision Record Built to Last

The architecture is chosen for the load and the compliance position the organisation actually has. Not for the one described in a briefing written before the project started.

Microsoft Foundry is retiring its own workflows feature on 2026-12-01 and directing new work to the Microsoft Agent Framework. A platform decision taken last year may now be the wrong one. Without a written reason, a migration has no way to distinguish a deliberate choice from a default.

The written record names the workload, the four question answers, the platform chosen, the reason at decision time, and the conditions under which the answer would change. A decision that lives in the repository travels with the codebase it governs. When the field moves, the reason makes the old decision reexaminable. Without it, a migration cannot defend why the original choice was made.

4 questions
before any platform is named: data residency, identity, provability, change ownership
3 platforms
Copilot Studio, Microsoft Foundry, Microsoft Agent Framework: three distinct answers
2026-12-01
Foundry workflow retirement: a decision without a written reason cannot defend itself
6 providers
Microsoft Agent Framework at 1.0 GA, Anthropic Claude included, one-line swap

From Workload Profile to Written Decision

Qualify 3 steps
01

Describe the Workload Before Any Platform Is Named

The first work is a description of the workload in isolation from any platform. What data does it touch, and where may that data be processed? What happens if the agent acts on state that has aged? What does a wrong output actually cost, in time, in money or in an audit record? These questions do not require a technology answer. They produce a profile of the workload that the platform decision can be measured against. Naming the platform before this profile exists is the most common source of re-decisions: the tool was chosen for a workload that was not yet understood.
02

The Four Questions That Settle Most Choices

Four questions settle most platform choices before capability is discussed at all. Where may the data be processed: inside the tenant, inside the European Economic Area, anywhere? Which identity governs the call: a service principal, a delegated user token, a managed identity? What has to be provable months later: which model was used, what the input contained, what the output said? And who may change the agent once it runs: a developer, a business analyst, the department that owns it? An agent that cannot be changed by its business owner without developer intervention is miscategorized regardless of which platform was chosen.
03

Lifecycle Drives the Topology Split

Topology is decided per workload rather than per project. The question is not how complex the workload is but at what rate it changes and who owns those changes. A workload that a business department will modify monthly without developer involvement belongs in a different host than one whose logic changes only when the engineering team releases. The distinction holds at a finer grain too: a single pipeline may correctly split into two services because its routing logic and its writing logic change at different rates, and deploying them together would couple two independent release cadences.
Select 3 steps
04

Copilot Studio, Microsoft Foundry or the Agent Framework

Copilot Studio fits where a business department owns the agent and the scope stays inside Microsoft 365. No developer should be required in the loop to update what the agent does. Microsoft Foundry fits where governance gates, evaluation runs and per-run cost attribution are non-negotiable. Agent Harness GA brings automatic context compaction and OpenTelemetry tracing to Application Insights. Foundry Hosted Agents GA adds scale-to-zero and per-session VM isolation. The Microsoft Agent Framework fits where several agents must coordinate on work too large for one, with durable state across long-running steps and human approval gates built in.
05

When Foundry Retires Its Workflow Feature

Microsoft Foundry is retiring its own workflows feature on 2026-12-01 and directing all new work to the Microsoft Agent Framework. The Microsoft Agent Framework 1.0 reached general availability on 2026-04-03, in .NET and Python, MIT licensed, unifying AutoGen and Semantic Kernel under one surface, with six model providers and a one-line swap between them, including Anthropic Claude. A platform decision taken before April 2026 that depended on Foundry's workflow engine may now be on the wrong platform. This is the strongest argument on this page for writing the decision down with its reason at the time it is made.
06

Prove the Riskiest Configuration Against the Real Platform

The riskiest configuration gets proven against the real platform before anything is built on top of it. Magentic teams fail against the Microsoft Foundry Responses API with a manager ledger error. The working configuration is the OpenAI-compatible Chat Completions client. That is the class of failure that takes days to diagnose and minutes to apply. The diagnosis lives in the repository's skills so the next project starts from the answer. No phase starts before the one before it has proven itself. The expensive unknown is settled while it is still cheap to be wrong about.
Record 3 steps
07

Stream the Run and Trace Every Stage of It

Streaming is an architectural choice, not a UI detail, and it belongs in the written decision. Results stream through the API as server-sent events with response buffering disabled on the .NET side, so a long run is visible while it is still in flight. Every pipeline stage writes one structured JSON line carrying an AsyncLocal correlation id. That makes per-run cost and the failure path of a stalled run readable afterwards, without instrumenting business code. Both choices are in the decision record because both are the kind of decision a new contributor needs to understand before touching the pipeline.
08

What the Written Decision Contains

The written decision names six things: the workload, the answers to the four qualifying questions, the platform chosen, the reason at the time of decision, the alternatives that were considered and why they were ruled out, and the conditions under which the answer would change. The reason matters more than the choice. When a vendor retires a feature, a record that carries only the choice cannot tell whether the feature was incidental or load-bearing. A record that carries the reason can. The decision is written in the repository that holds the system it governs, not in a separate document store.
09

How the Record Outlasts Its Author

A decision that lives in the repository travels with the codebase it documents. A cold clone that starts a new contributor also carries the decision history, the qualifying question answers, and the conditions set when each answer was given. When a platform changes around a decision, the record makes the review mechanical: compare the conditions stated at decision time against the current state of the platform. Without a record, every migration starts from scratch, unsure whether the original choice was deliberate or simply a default the project never revisited. The record is what makes a decision survivable rather than just traceable.

Frequently Asked Questions

When does a workload need the Microsoft Agent Framework rather than a hosted agent service?
The deciding factors are lifecycle and coordination. A hosted agent service on Microsoft Foundry fits when a team of agents has its own release cadence and the orchestration stays inside one bounded service. The Microsoft Agent Framework earns its cost when several agents must coordinate across a long-running workflow, with durable state between steps and human approval gates mid-run. The 2026-04-03 GA consolidated AutoGen and Semantic Kernel into one surface: code written before that date may be on an API the framework has since absorbed.
What makes platform decisions go wrong?
Most re-decisions trace to the same two causes. The first is naming the platform before the workload profile exists: the data residency, the identity model and the change-ownership question are answered by the platform before a single line of code is written, so choosing the platform first means accepting whatever those answers happen to be. The second is choosing without writing the reason down. When a vendor retires a feature or a regulation changes, a bare choice cannot be reviewed against the conditions that produced it.
What is Microsoft Foundry retiring, and why does it matter now?
Microsoft Foundry is retiring its own workflows feature on 2026-12-01 and directing new work to the Microsoft Agent Framework. For any agentic workload currently on Foundry's native workflow engine, the practical question is whether the migration to the Agent Framework is better done now or forced by the deadline. The Agent Framework reached 1.0 GA on 2026-04-03 and is MIT licensed. That is a stable target. A decision written with a reason will make the migration rational; one written without a reason will make it exploratory.
How observable does an agentic pipeline need to be?
Observable enough that a stalled run can be diagnosed without reading business logic. Results stream as server-sent events with response buffering disabled on the .NET side, so the run is not a black box while it is in flight. Every pipeline stage writes one structured JSON line carrying an AsyncLocal correlation id, which makes per-run cost and the full failure path readable after the fact. Both choices belong in the decision record: the next person to instrument a new stage needs to know which pattern the pipeline already uses.
What does the written decision look like in practice?
A file in the repository, not a separate document. It names the workload, the four qualifying question answers, the platform chosen, the reason at the time of decision, the alternatives considered and ruled out, and the condition set that would change the answer. The condition set is what turns a static record into a living one: when a vendor retires a capability or a data residency rule changes, the record tells a reviewer exactly what to check. A decision that lives in the repository travels with every clone of the codebase.