Microsoft Agent Framework: From Agent Experiments to Governed AI Systems
Microsoft Agent Framework has moved well beyond its original preview-era positioning. Version 1.0 became generally available on April 2, 2026, with stable core APIs and long-term-support commitments for .NET and Python. At publication time, the latest repository releases are .NET 1.21.0 and Python 1.18.0, although individual integrations and experimental packages continue to have their own maturity levels and release cadence.
The framework is now Microsoft’s primary pro-code foundation for building agents and multi-agent workflows. It is the direct successor to Semantic Kernel and AutoGen for new agent development – not a rebranding of either project, but a convergence of AutoGen’s agent and orchestration ideas with Semantic Kernel’s production-oriented state, typing, middleware, telemetry, and provider support.
That distinction matters. Semantic Kernel and AutoGen remain useful, supported technologies, particularly for existing systems and research scenarios. But for a new production-oriented agentic application in 2026, Microsoft Agent Framework is the strategic starting point unless a required capability remains available only in the older framework.
Why
Agent development needs a software-engineering foundation
An agent is more than a prompt wrapped around a model. Its behavior emerges from instructions, model capabilities, conversation context, external data, tool calls, approvals, middleware, and runtime state. Once an agent can update records, invoke business processes, access sensitive data, or delegate work, it becomes a distributed software system with probabilistic components.
Microsoft Agent Framework addresses that engineering reality through a consistent agent interface, session-based state, typed messages and workflows, middleware, evaluation, OpenTelemetry, human approval, checkpointing, and multiple hosting options. These capabilities let teams separate business logic from cross-cutting concerns instead of embedding security, retry, observability, and state-management rules inside one increasingly fragile prompt.
The business benefit is not “more autonomy” by itself. It is controlled automation: systems that can handle ambiguous inputs while retaining deterministic boundaries around permissions, state transitions, approvals, and operational accountability. That makes the framework relevant to customer service, knowledge work, software engineering, data analysis, and business-process automation – not only conversational assistants.
Why start with Agent Framework rather than Semantic Kernel or AutoGen?
Microsoft’s current guidance calls Agent Framework the successor to Semantic Kernel and the next generation of both Semantic Kernel and AutoGen. Most new capabilities are being built for Agent Framework, while Semantic Kernel continues to receive critical fixes, security updates, and selected feature completion. Microsoft’s 1.0 announcement explicitly recommends migration for teams coming from either predecessor.
The architectural reasons are more important than product positioning:
- One agent contract. Application-owned agents, custom agents, managed agents, and remote A2A agents can be presented through a common interface. This reduces provider-specific code in applications and orchestration layers.
- One workflow model. Agents, normal functions, and sub-workflows can participate in explicit, inspectable data-flow graphs. This is a significant evolution from AutoGen’s combination of event-driven runtime concepts and higher-level team abstractions.
- Cross-cutting controls outside prompts. Middleware can intercept agent runs, model calls, and tool execution for validation, logging, policy, error handling, or result transformation. That improves maintainability because controls do not need to be duplicated across system prompts.
- Provider and protocol flexibility. The framework supports Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic, Ollama, Copilot Studio, GitHub Copilot, MCP, A2A, and other integrations through common abstractions, while still exposing provider-specific capabilities when required.
- Production lifecycle capabilities. Evaluation, OpenTelemetry, durable workflow state, checkpointing, human interaction, and managed or self-hosted deployment are part of the framework’s architecture rather than afterthoughts.
This does not mean every Semantic Kernel or AutoGen workload should be rewritten immediately. A stable Semantic Kernel application providing business value is not automatically obsolete. Semantic Kernel functions can be adapted incrementally as Agent Framework tools, and existing vector-store integrations can be reused during migration. AutoGen systems may require more redesign because Agent Framework workflows use explicit data routing rather than AutoGen-style message broadcasting and team state.
A sensible modernization strategy is therefore capability-led migration: inventory agents, tools, state, orchestration, and operational dependencies; migrate the shared foundation first; then move individual agent or workflow boundaries when the change produces measurable maintainability, governance, or interoperability benefits.
From experimentation to an operating model
For an SMB, architectural consistency reduces the number of custom components a small engineering team must own. One agent interface, a small set of tools, local evaluations, OpenTelemetry, and managed hosting may be sufficient to establish a credible production baseline.
For an enterprise, the same abstractions become control points. Teams can standardize tool contracts, middleware, session isolation, evaluation suites, telemetry conventions, deployment templates, and identity patterns without forcing every business domain to use the same models or application architecture. Microsoft Foundry can add centralized model, hosting, evaluation, tracing, RBAC, and policy capabilities around the application-level framework.
The crucial principle is not to build a “large-enterprise architecture” prematurely. Start with the smallest architecture that satisfies the risk and reliability requirements, then add controls where the blast radius grows. A read-only internal knowledge agent needs fewer gates than an unattended agent that changes customer, financial, or infrastructure records.
What
Microsoft’s current documentation organizes Agent Framework around four primary areas: Agents, Agent Harness, Workflows, and Integrations. Beneath them are shared building blocks such as chat clients, sessions, context providers, middleware, tools, MCP clients, evaluation, and observability.
The following architecture shows why framework choice, provider choice, hosting choice, and channel choice should be separate decisions.
Figure 1: Microsoft Agent Framework separates design approach (agent, harness, or workflow) from provider, protocol, hosting, and cross-cutting controls. Component-level maturity still needs to be verified for each production dependency.
Agents: reasoning within a bounded responsibility
An Agent Framework agent combines a common agent abstraction with either a model client or remote-agent connection, instructions, tools, middleware, context providers, and optional session state. In .NET, the central abstraction is
AIAgent; in Python, applications commonly use Agent, with compatible custom and provider-backed agent interfaces.Use a single agent when the task is open-ended, conversational, or benefits from model-directed tool selection. Good examples include answering questions over several sources, interpreting an ambiguous request, or choosing among a small number of well-described tools.
Keep the scope narrow. As the number of tools and responsibilities grows, tool selection and instruction adherence become harder. A lightweight next step is agent-as-tool composition: a coordinating agent delegates a focused subtask to another agent without requiring an explicit workflow graph.
This is simple, but routing remains model-driven and therefore requires strong descriptions and evaluation.
Sessions carry conversation continuity; they are not automatically synonymous with long-term memory. Context providers can inject and persist history, user context, retrieval results, or extracted memories before and after a run. Applications must define storage, retention, authorization, tenant boundaries, and deletion behavior appropriate to the selected provider.
Agent Harness: batteries included for long-running work
The Agent Harness is opinionated runtime scaffolding for tasks such as research, coding, and data analysis. It composes normal Agent Framework building blocks rather than creating a second runtime. Its architecture includes a chat client, function-invocation pipeline, per-service-call history, optional context compaction, context providers, todo tracking, plan/execute modes, approvals, observability, and optional looping or background delegation.
Choose a Harness Agent when the agent must keep progressing through a multi-step goal and needs working artifacts, task tracking, context management, or repeated tool use. Do not choose it simply because it offers more features. File access, shell execution, web search, background agents, and standing approvals increase the trust surface and should be enabled selectively.
The .NET and Python implementations share the same conceptual architecture, but they are not byte-for-byte identical. For example, Agent Skills are enabled by default in the .NET harness and opt-in in Python; composition and package details differ. Treat the language-specific capability matrix and current package metadata as the source of truth.
Workflows: explicit coordination and durable control
Workflows connect executors—agents, functions, or sub-workflows – through explicit paths. Executors perform work, edges route typed values, events expose execution behavior, and workflow state records run-scoped or durable information. .NET and Python support graph workflows; Python also has an experimental functional workflow API.
Use a workflow when:
- steps, dependencies, or approval boundaries are known;
- execution order must be inspectable;
- multiple agents or deterministic functions must coordinate;
- fan-out and fan-in are required;
- a process must pause, resume, or recover;
- auditability matters more than unconstrained autonomy.
Built-in orchestration patterns include sequential, concurrent, handoff, group chat, and Magentic coordination. These are convenience patterns—not a requirement to make every system multi-agent. A deterministic function should remain a function, and a fixed business process should not become a free-form agent conversation merely because an LLM is present.
Human interaction is a first-class workflow behavior. Request/response ports let an executor pause for external input; tool approvals use the same mechanism in agent orchestrations. Pending requests can be checkpointed and re-emitted when a workflow resumes. This supports approval, escalation, exception handling, and clarification without holding compute while waiting.
Integrations and ecosystem boundaries
Microsoft Foundry. The current platform name is Microsoft Foundry, following Azure AI Studio and Azure AI Foundry. Current Foundry projects use the Responses API and current
azure-ai-projects 2.x SDKs; the Assistants API and azure-ai-inference package reached their documented sunset on August 26, 2026.Agent Framework can use Foundry-deployed models while the application owns the agent logic, connect to managed agents, consume Foundry tools and context services, export evaluations and telemetry, or deploy code as a Foundry Hosted Agent. Azure OpenAI remains available, but Foundry is the recommended starting resource for scenarios combining models, agents, hosting, and evaluation.
Microsoft 365 and Copilot. Foundry agents can be published to Microsoft 365 Copilot and Teams for supported scenarios. Foundry Hosted Agents also support the Activity protocol used by Microsoft 365 channels. Separately, the Microsoft 365 Agents SDK provides channel, activity, authentication, and conversation plumbing; it can host Agent Framework as its reasoning and orchestration layer.
Microsoft Agent 365 SDK is another distinct layer. It does not build or host agents. It extends an existing agent with Agent 365 identity, OpenTelemetry, governed Work IQ MCP tools, and – where available – notifications. This distinction prevents overlap between the framework that implements agent behavior and the control/channel layers that connect it to Microsoft 365.
MCP and A2A. MCP standardizes tool and context access; A2A supports agent discovery and communication across runtimes. Agent Framework can consume local or hosted MCP tools, expose an agent as an MCP tool, and host or call A2A agents. Third-party servers remain separate trust domains, so data flows, credentials, retention, and geographic boundaries must be reviewed explicitly.
Security and governance. Agent Framework supplies extension points, not automatic end-to-end security. Treat model output and tool arguments as untrusted, validate all tool inputs, constrain paths and queries, require approval for high-impact actions, secure session storage, and set rate and token limits. System instructions must remain developer-controlled.
Microsoft Entra Agent ID gives Foundry-hosted agents distinct identities and supports attended and unattended authorization patterns. Agent identities should receive narrow RBAC assignments for downstream systems; publishing may create a new distinct identity that requires its own role assignments.
Observability and evaluation. Agent Framework emits traces, logs, and metrics using OpenTelemetry GenAI semantic conventions. Development can use Aspire Dashboard, while Azure deployments can export to Azure Monitor and Application Insights. Prompt, response, tool-argument, and tool-result capture should normally remain disabled in production unless the data-governance model explicitly permits it.
Evaluation supports fast local checks, custom functions, Microsoft Foundry evaluators, repeated runs, expected outputs, expected tool calls, and per-agent workflow breakdowns. Evaluation should measure outcome quality, tool behavior, safety, cost, latency, and failure recovery—not just whether an answer “sounds good.”
How
1. Start with the business boundary
Define the outcome, user, authoritative data, permitted actions, failure consequences, and escalation path. If deterministic code can perform the task reliably, use deterministic code. Introduce an agent only where language understanding, reasoning, synthesis, or dynamic tool selection creates value.
Choose the initial design:
| Need | Starting design |
|---|---|
| Open-ended conversation or dynamic tool selection | Agent |
| Focused delegation without fixed routing | Agent as a tool |
| Long-running research, coding, or analysis | Harness Agent |
| Known stages, branches, approvals, or recovery | Workflow |
| Reliable multi-agent execution over time | Workflow plus durable hosting |
2. Establish identical conceptual foundations in .NET and Python
Use the stable core packages, pin versions, and review the status of every provider or hosting integration independently. The core framework is GA, whereas some self-hosting, Foundry-hosting, Agent Hooks, and functional-workflow packages or APIs remain prerelease or experimental.
C#/.NET
1 dotnet add package Microsoft.Agents.AI
2 dotnet add package Microsoft.Agents.AI.Foundry –prerelease
3 dotnet add package Azure.AI.Projects
4 dotnet add package Azure.Identity
1 using Azure.AI.Projects;
2 using Azure.Identity;
3 using Microsoft.Agents.AI;
4
5 var client = newAIProjectClient(
6 new Uri(Environment.GetEnvironmentVariable(“FOUNDRY_PROJECT_ENDPOINT”)!),
7 new AzureCliCredential());
8
9 AIAgent agent = client.AsAIAgent(
10 model: Environment.GetEnvironmentVariable(“FOUNDRY_MODEL”)!,
11 name: “OperationsAssistant”,
12 instructions: “Answer from approved sources and request approval before actions.”);
13
14 Console.WriteLine(await agent.RunAsync(“Summarize today’s unresolved issues.”));
Python
1 pip install agent-framework azure-identity
1 import os
2 from azure.identity import AzureCliCredential
3 from agent_framework import Agent
4 from agent_framework.foundry import FoundryChatClient
5
6 agent = Agent(
7 client=FoundryChatClient(
8 project_endpoint=os.environ[“FOUNDRY_PROJECT_ENDPOINT”],
9 model=os.environ[“FOUNDRY_MODEL”],
10 credential=AzureCliCredential(),
11 ),
12 name=”OperationsAssistant”,
13 instructions=”Answer from approved sources and request approval before actions.”,
14 )
15
16 result = await agent.run(“Summarize today’s unresolved issues.”)
17 print(result.text)
These examples intentionally start small. Add sessions only when continuity is required, tools only when there is an explicit business capability, and a workflow only when execution control warrants it.
3. Select models and tools empirically
Build a representative evaluation dataset before committing to a model. Compare quality, structured-output reliability, tool selection, latency, throughput, regional availability, and cost. A powerful model for planning may be unnecessary for extraction or classification, and different agents in one workflow can use different models.
Define tools with narrow schemas, explicit descriptions, least-privilege credentials, idempotency where practical, and bounded outputs. Separate read tools from write tools, and require approval for irreversible, financial, communication, identity, or broad-impact operations.
4. Design identity and state before production
During development, Azure CLI credentials and in-memory sessions are convenient. In production, use managed or agent identities, RBAC, authenticated callers, encrypted storage, and tenant- or user-scoped continuation keys.
DefaultAzureCredential needs careful production configuration; a specific managed identity credential avoids unintended fallback behavior.For SMB deployment, a Foundry project, dedicated production agent identity, managed hosting, and a small number of approved tools may be enough. At enterprise scale, add separate environments, resource/project boundaries, policy-controlled model catalogs, private networking where supported, centralized tool registration, data classification, session-retention policies, and independent audit trails.
5. Build evaluation and observability into delivery
Create local deterministic checks for required content, forbidden behavior, expected tools, and schema validity. Add Foundry evaluators for relevance, groundedness, task adherence, completion, tool accuracy, and safety where appropriate. Repeat nondeterministic tests and record model, prompt, tool, and framework versions with every result.
Instrument the agent and workflow with OpenTelemetry from the first development iteration. Monitor model calls, tool latency, failures, approval rates, token usage, retry loops, and end-to-end outcomes. Redact or disable sensitive message capture in production unless access, retention, and compliance controls have been formally approved.
6. Choose hosting independently from protocol
Use Foundry Hosted Agents when Microsoft-managed containers, scaling, session lifecycle, dedicated identity, and platform integration match the requirement. The managed service is GA, although individual language integration packages can still be prerelease.
Choose self-hosting when the agent must share application infrastructure, custom middleware, network policy, routing, or deployment controls. Choose the Durable Extension for Azure Functions triggers, distributed execution, persistent sessions, long-running workflows, external events, and recovery. Then select Responses, A2A, AG-UI, MCP, or Activity protocol based on the consuming channel rather than the infrastructure model.
7. Iterate as a governed product
Promote only configurations that meet defined quality, safety, cost, and reliability thresholds. Keep prompts, tool contracts, workflow definitions, evaluation datasets, and deployment configuration versioned together. Introduce multi-agent orchestration only when specialization, parallelism, or control boundaries justify its added latency and operational complexity.
Most importantly, verify maturity at the component level. Agent Framework core is production-ready, but the surrounding Microsoft ecosystem contains a mixture of GA, preview, prerelease, and experimental capabilities. Current documentation explicitly warns against treating an entire platform’s GA milestone as proof that every dependent feature is GA.
Microsoft Agent Framework represents Microsoft’s next step toward making agentic AI a practical, production-ready software architecture rather than a collection of AI experiments. By bringing together the strengths of Semantic Kernel and AutoGen with a unified approach to agents, agent harnesses, workflows, integrations, observability, and governance, it gives organizations a clearer path from prototype to production.
The key is to start simple: use an agent where reasoning adds value, introduce workflows where control and predictability matter, and add multi-agent or harness patterns only when the problem genuinely requires them. Combined with Microsoft Foundry and the broader Microsoft ecosystem, Agent Framework provides a foundation that can grow from a focused SMB solution into a governed enterprise AI platform.
Ultimately, successful agentic AI is not about maximizing autonomy—it is about finding the right balance between AI reasoning, deterministic control, security, and human oversight.
