Microsoft Agent Framework Guide: Agents, Harness, Workflows

Microsoft Agent Framework is Microsoft's next SDK for building AI agents and multi-agent apps in Python and .NET (with Go in public preview). Searches for "microsoft agent framework" keep climbing next to AutoGen and Semantic Kernel, which makes sense: the same teams built it as the direct successor to both, and on 4 November 2026 they shipped installable builder skills so coding agents can scaffold apps against the current docs. I use agent stacks for client work, so I re-read the Learn overview, the migration guides, the GitHub repo, and the builder-skills post. Here is a practical map of Agents vs Harness vs Workflows, how to get started in Python and .NET, how the new builder skills fit, and how the framework compares to AutoGen, Semantic Kernel, Google ADK, and LangGraph.

What Microsoft Agent Framework covers

The overview groups the product into four areas:

Under that sit model clients, an agent session for state, context providers for memory, middleware for intercepting actions, and MCP clients for tools. The pitch is AutoGen-style simple agent abstractions plus Semantic Kernel-style enterprise pieces (sessions, type safety, middleware, telemetry), with graph workflows for explicit multi-agent control.

Agents vs Harness vs Workflows

The overview's decision table is short and useful. Use an agent when the task is open-ended or conversational, you need autonomous tool use, and a single LLM call (with tools) is enough. Use a workflow when the process has well-defined steps, you need explicit control over order, or several agents or functions must coordinate. And if a plain function already solves the problem, skip the agent.

The Harness sits in the middle: still a normal Agent Framework agent, but with batteries-included scaffolding for long tasks (todos, compaction, file memory, tool approval, OpenTelemetry, and more). The 4 Nov builder-skills post says the same thing in product language: prefer one agent when tools and sessions are enough, a harness when you need an operating loop, and a workflow when stages, routing, and checkpointing are real requirements.

That matches how I usually scope client work. A support bot with a handful of tools is one agent. A research or coding run that must track todos and ask before destructive tools is a harness. A review pipeline with writer → reviewer → editor and a resume-from-checkpoint path is a workflow.

Get started in Python

Install the meta package (core plus common providers). Experimental modules live in agent-framework-lab and are separate.

pip install agent-framework

A Foundry-backed hello agent, adapted from the Learn overview (you still need Azure CLI auth and a project endpoint):

import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project",
        model="gpt-5.4-mini",
        credential=AzureCliCredential(),
    ),
    name="HelloAgent",
    instructions="You are a friendly assistant. Keep your answers brief.",
)

async def main() -> None:
    result = await agent.run("What is the largest city in France?")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

For a long-running research or coding loop, the harness factory is the documented entry point:

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    client=OpenAIChatClient(model="gpt-4o"),
    name="research-agent",
    harness_instructions="Use tools deliberately and report verified results.",
    agent_instructions="You are a research assistant focused on academic sources.",
)

session = agent.create_session()
# response = await agent.run("Plan a weekend trip to Seattle.", session=session)

create_harness_agent is released. Background agents, file access, and looping are still marked experimental on the harness page, and shell tooling comes from the pre-release agent-framework-tools package. Check that page before you lean on those pieces in production.

Get started in .NET

The overview's Foundry quickstart uses a prerelease package:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease

The GitHub README also shows the core package plus Foundry helpers:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Minimal Foundry agent from the overview:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
        new Uri("https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"),
        new AzureCliCredential())
    .AsAIAgent(
        model: "gpt-5.4-mini",
        instructions: "You are a friendly assistant. Keep your answers brief.");

Console.WriteLine(await agent.RunAsync("What is the largest city in France?"));

For a harness agent, the concept page uses AsHarnessAgent from Microsoft.Agents.AI.Harness (any IChatClient):

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = chatClient.AsHarnessAgent();
AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

Builder skills (4 Nov 2026): development-time only

On 4 November 2026 Microsoft published installable builder skills for .NET and Python. They give coding agents (GitHub Copilot, Claude Code, Cursor, Codex, and others that speak the Agent Skills format) Microsoft-maintained guidance for choosing patterns and wiring tools, sessions, workflows, and hosting.

Install with GitHub CLI from main (pin a tag or commit if you need a reproducible snapshot):

gh skill install microsoft/agent-framework agent-framework-builder-dotnet@main
gh skill install microsoft/agent-framework agent-framework-builder-python@main

Or with the cross-agent skills CLI:

npx skills add microsoft/agent-framework --skill agent-framework-builder-dotnet
npx skills add microsoft/agent-framework --skill agent-framework-builder-python

Each skill has a SKILL.md entry point and focused references. The coding agent inspects your project first, then loads only the guidance it needs. The .NET skill covers AIAgent, Microsoft.Extensions.AI, NuGet packages, DI, and ASP.NET Core hosting. The Python skill covers Agent, provider packages, middleware, context providers, and Python workflow patterns.

Pair either skill with the Microsoft Learn MCP server so the coding agent can search the full docs when a snippet is not enough. For the Agent Skills format itself (what a SKILL.md is, how clients discover it), see my Agent Skills guide. If you are comparing "how coding agents extend themselves" more broadly, the Claude Code mods guide covers in-process guards, which sit next to skills rather than replacing them.

How it compares to AutoGen, Semantic Kernel, Google ADK, and LangGraph

Related searches still cluster around AutoGen, Semantic Kernel, Azure naming, Google ADK, and LangGraph. Short version:

If you are evaluating self-hosted coding agents rather than application SDKs, my notes on DeepSeek Harness / dsh-superagent cover a different problem (repo-watching workers), not an application framework.

Go preview and MCP

Go is in public preview and needs Go 1.26 or later. Declarative agents, CodeAct, and functional workflows are not implemented in Go yet. The harness helper, bounded looping, planning and todos, RAG, and some memory pieces are available; check the Go tabs on each docs page for limits.

MCP is a first-class integration path (stdio and streamable HTTP tools in Python). That sits next to the wider MCP server migration work I covered for the 2026-07-28 stateless MCP spec.

Checklist

• Confirm you need an agent at all; prefer a function when the path is fixed.
• Start with one Agent / AIAgent, add a harness only for long operating loops, and use Workflows when stages or checkpoints are real.
• Install agent-framework (Python) or Microsoft.Agents.AI.Foundry --prerelease (.NET) as documented today.
• Install the matching builder skill for your language, and point the coding agent at https://learn.microsoft.com/api/mcp.
• Read the AutoGen or Semantic Kernel migration guide before rewriting production agents.
• Treat Go as preview; verify which features exist on the Go tabs.
• Review third-party model and tool data flows before production.

That is enough to stand up a hello agent, choose the right pattern, and let a coding agent scaffold the rest against Microsoft's own guidance.