Microsoft wrote 968 pages on AI agents. The best advice: don't use one

By the end of September 2026, the documentation for Agent Framework, Microsoft's framework for AI agents, had grown to 968 pages, most of them code. But between the lines of code you can read how one of the biggest tech companies in the world really sees agents: not as magic, but as a factory floor with shifts, logbooks and safety rules.

Agent Framework replaced two earlier Microsoft projects, Semantic Kernel and AutoGen, and the same teams built it. One project offered simple building blocks for agents, the other offered enterprise reliability. The new one merged them and added the key part: explicit work routes and saved state that survives a restart and knows how to wait for a human.

I pulled out six ideas that matter well beyond programmers. They explain why some companies get real value from agents and others get an expensive toy.

Idea one: the best agent is the one you didn't need#

On the second page of the docs there is a line worth hanging in every office: if a regular function can do the job, write the function, not an agent. Agents belong where the task is open-ended and conversational. If the steps are known in advance, code should run them.

The docs explain why without any romance. A model does not guarantee the same answer to the same question, even with the strictest settings. It confidently makes up facts and is bad at math: it does not calculate, it guesses what a correct answer looks like.

The developer journey in the docs is built as a ladder with eight steps:

1. an agent with instructions;
2. tools;
3. skills;
4. control layers in between;
5. memory;
6. agents inside agents;
7. links between agents of different companies;
8. workflows with a strict order of steps.

Each step adds both power and complexity. Microsoft's conclusion sounds like advice from a seasoned engineer: the best systems use the simplest option that solves the problem and climb higher only when life forces them to.

Idea two: decide who picks the next step#

The central question of the whole documentation is who decides what happens next, the model or the developer. An agent with tools picks on its own what to call, whom to hand a subtask to and when to stop. That is flexible, but unpredictable.

Microsoft draws a scale. On the left is an agent that decides everything itself, on the right a plain pipeline with no AI at all. Most useful systems live in the middle: a workflow sets the order of steps, and the model works only where thinking is needed.

Under the hood, workflows are strict: steps run in rounds, and the next round does not start until every branch of the previous one has finished. In return the system gives you the same order for the same input and saves state at the end of every round. A crashed process resumes where it stopped instead of starting over.

That is the answer to the fear that AI will break everything. Intelligence can be dosed: at every step you decide whether the model thinks, the code calculates or a human signs off.

Idea three: the harness wins, not the model#

The docs contain a line that explains half the market: modern agents are often held back not by model quality but by the overhead of organizing the work. So Microsoft built a harness: a ready-made frame that turns a language model into a worker for long, multi-step tasks.

What the harness includes out of the box:

• a to-do list the agent uses to track progress;
• two modes: in plan mode the agent asks questions and shows a plan, in execution mode it works on its own, and it is instructed to switch to execution only with a human's approval;
• memory in files, plus compaction of old messages that you switch on with one setting, so a long conversation does not overflow the model;
• standing tool permissions, so the agent does not ask a human the same thing twice;
• logs and work metrics.

Each item treats a specific pain. A long conversation gets more expensive, slows down and at some point no longer fits into the model, and answer quality drops even earlier. The docs recommend compacting in stages: first collapse old tool results, then have a small, cheap model summarize the history, and only as a last resort cut off the old part.

Skills are just as frugal. The agent sees only a short description of each skill, about 100 tokens, and loads the full instructions when it needs them. A token is a piece of a word: both a model's memory and its price are counted in tokens. Ten skills cost about 1,000 tokens instead of 50,000.

And there is a separate rule on autonomy: any loop that repeats work until it is done must have a ceiling. The default is 10 rounds, because the done criterion may never trigger, the model may get stuck, and the checker makes mistakes too.

Idea four: human sign-off is built into the mechanics#

By default an agent calls any tool without asking. The docs say plainly that this must change for risky actions, and give four signs of a tool that should wait for approval:

1. it changes data, sends emails or spends money;
2. it handles sensitive data: personal, financial, passwords;
3. its action cannot be undone, like deleting something or sending an email;
4. it touches many objects at once.

The most interesting part is how it works. An agent that needs permission does not wait and does not guess: it ends its turn with a question instead of an answer, and work resumes only with the human's decision. Even a loop that repeats until done stops at that question instead of hiding it behind another round.

There is also an uncomfortable truth. When an agent hands work to other agents, their approval requests may never reach a human. Background agents do not pass them up at all, and with nested Python agents an unanswered request is simply rejected. If approval has to be real, delayed or survive a restart, the docs recommend building a workflow with an explicit checkpoint rather than counting on the agent.

The takeaway for business: autonomy is a setting, not a property of the model. Where the human signs off is the process owner's call, and it has to be made before launch, not after the first mistake.

Idea five: models can't be trusted, and the manual says so#

The most sober section of the docs is about security. Its first point: whoever builds the agent is responsible for its security, not Microsoft. The framework provides the parts, but checking incoming data, protecting its path and configuring tools is the developer's job.

Next comes a trust table every manager should know. Only the system instructions written by the developer can be fully trusted. User messages, the model's own answers and tool results are all treated as untrusted: any of them can hide someone else's command.

This is not theory. A document found through a knowledge base search can contain a hidden instruction, and the model will follow it. The docs point out that this kind of instruction hijacking is considered the top risk for language models, and admit honestly that a protective line in the prompt and a homemade allow list give no guarantee. They quietly break the day an email or a task contains the line [SYSTEM OVERRIDE].

So Microsoft adds hard mechanisms:

• labels on data: trusted or not, public or private; the labels travel with the data through every call, and a risky tool will not run on untrusted data (still experimental and Python only);
• hooks that issue a verdict before an action and, in enforce mode, block it on failure (Python only for now);
• built-in quality evaluation: a separate judge model checks the answers, and every question can be run several times to catch inconsistency.

The small details say a lot too. Full message logging is off by default, and the docs advise against turning it on in production because it contains personal data. The framework sets no limits on request length or frequency at all: it does not know what is reasonable for your business and leaves that to you.

Idea six: the model became a replaceable part#

Microsoft's framework works the same way with models from Microsoft itself, OpenAI, Anthropic, Google, Amazon, Mistral and with open models you can run yourself. The docs promise that you can switch the model provider without rewriting the app. In some cases you can even swap the model in the middle of a conversation without losing context.

Around the model, Microsoft builds open standards rather than a walled garden:

• MCP, a common protocol through which any software can give agents its tools;
• A2A, a protocol that lets agents from different teams and companies find each other and agree on things, whatever they are written in; the docs call it the HTTP of agents;
• skills based on an open specification that move between agents, teams and even products;
• a single format for logs and metrics of language models.

The practical conclusion is simple. Different agents in one system can run on different models: complex reasoning on a large one, routine work and history summaries on a small, cheap one. Betting on a single model becomes a mistake, and value moves to where it is hard to copy: a company's processes, data and tools.

What this means for business and people#

Put the six ideas together and you get an unexpected picture: the main work in the age of agents is not choosing a model but designing the process. Someone has to decide which step to trust to the model, which to code and which to a human. Someone has to describe the tools as carefully as documentation for programmers: the model picks a tool only by its name and description.

The docs also offer practical rules that fit any team:

• without tools an agent is just someone to talk to, with tools it gets things done, so start with one or two actions you really need;
• extra tools hurt: each one eats into the model's memory, and from dozens of options it chooses worse than from a few well-described ones;
• when one agent has too many roles, split it into narrow specialists and hand simple tasks to small, cheap models;
• extra context does not just cost money, it makes answers worse;
• the model should not do the math: let it write code that calculates precisely, and a human still checks the result.

In my view, this is where new professions come from: designers of agent-driven processes, specialists who check agents' work, data security engineers for AI. And an old rule in a new form: the winner is not whoever has the smartest model, but whoever has organized the work around it best.

The bottom line#

Microsoft's 968 pages boil down to one idea: an agent is not a replacement for the process, it is a participant in it. The less you leave to the model where code can do the job, the more value it brings where you cannot do without it.