Microsoft Agent Framework is Microsoft’s current open-source framework for building AI agents and graph-based workflows in .NET and Python. It brings together concepts developed through Semantic Kernel and AutoGen while adding a more unified model for agents, sessions, tools, middleware, memory, workflows, hosting, and observability.
Migration should not begin by translating classes line by line. It should begin by deciding which parts of the existing system are truly agents, which are controlled workflows, and which should remain ordinary C# functions.
Understand the target architecture
Microsoft Agent Framework organizes capabilities into three broad categories.
Agents use models to process input, call tools or MCP servers, maintain session context, and generate responses. A harness adds opinionated support for longer multi-step tasks. Workflows connect agents and functions through explicit graph-based execution with routing, checkpointing, and human-in-the-loop controls.
Microsoft’s guidance is direct: use an agent for open-ended or conversational work, use a workflow when execution steps should be controlled, and use a function when a function can solve the task.
That distinction should drive the migration.
Inventory the existing system
Before changing code, document the current components:
- model and embedding clients;
- Semantic Kernel plugins or AutoGen tools;
- prompts and system instructions;
- planners, group chats, or orchestration logic;
- conversation and memory stores;
- retrieval and vector-store integrations;
- filters, middleware, telemetry, and content-safety controls;
- hosting endpoints and channel adapters;
- evaluation datasets and production metrics.
For each component, identify the business capability it supports. Remove unused abstractions and duplicate orchestration before introducing the new framework.
Classify each behavior
A migration is an opportunity to reduce unnecessary autonomy.
A support assistant that answers questions and invokes approved tools may remain an agent. A document process with extraction, validation, review, and system update should normally become a workflow. A pricing rule, authorization check, or database update should remain deterministic code exposed through a controlled tool only when needed.
This classification improves reliability and makes the new architecture easier to operate.
Isolate framework dependencies
Place Agent Framework behind application-specific interfaces. The domain should depend on capabilities such as `IIncidentInvestigator` or `IClaimsWorkflow`, not on framework-specific agent classes.
Tools should wrap existing application services rather than duplicate business logic. They should use typed inputs and outputs, enforce authorization, validate arguments, and emit audit events.
This boundary allows the team to migrate incrementally and preserves testability.
Migrate model access and tools first
Start with provider configuration and simple agent invocation. Then migrate tools one at a time. Test each tool independently before allowing model-directed selection.
Do not expose a broad service object as a tool catalog. Create narrow operations with explicit permissions. Require confirmation or human approval for financial, legal, security, data-changing, or externally visible actions.
Rebuild conversation state deliberately
Agent Framework uses sessions and context providers for state and memory. Decide what must persist, for how long, and under which user or tenant identity.
Do not copy every historical message into every request. Separate short-lived conversation state from durable business records. Apply retention, encryption, geographic, and deletion policies. Ensure that session identifiers cannot cross tenant boundaries.
Replace implicit orchestration with explicit workflows
If the old implementation relies on planners or loosely coordinated agents, consider whether a graph-based workflow can make the process clearer.
Explicit workflows provide known steps, branching, checkpointing, retries, and human review. They are usually preferable for regulated or operational processes where the organization must explain what happened.
Keep open-ended planning for tasks that genuinely cannot be expressed as a controlled process.
Preserve retrieval and vector-store choices
Agent Framework integrates with .NET vector-store abstractions and multiple back ends. Migration does not require changing the data platform unless the current design is inadequate.
Maintain authorization filters, tenant partitioning, source citations, document freshness, and ingestion controls. Test retrieval quality separately from model quality.
Add evaluation and observability before cutover
Run the old and new implementations against the same evaluation set. Compare task completion, groundedness, tool-selection accuracy, policy compliance, latency, cost, and human correction.
Trace agent and workflow execution. Record model, tool, prompt, policy, and framework versions. Monitor tool failures, loops, excessive step counts, token consumption, unsafe requests, and abandoned sessions.
A successful migration is measured by system behavior, not by whether the new package compiles.
Plan hosting and durability
Agent Framework supports ASP.NET Core integration and multiple hosting approaches. Long-running or interruptible work may need durable execution. Interactive agents need streaming, cancellation, authentication, rate limiting, and session management.
Choose hosting based on the business workload rather than the demonstration sample.
Use an incremental cutover
- Establish interfaces around the current capability.
- Recreate one low-risk agent or workflow in Agent Framework.
- Run offline evaluations and shadow traffic.
- Release to a limited user group.
- Compare quality, reliability, latency, and cost.
- Migrate additional capabilities only after the first one is stable.
- Retire old orchestration code after rollback risk has passed.
The migration goal
The objective is not to recreate every Semantic Kernel or AutoGen pattern in a new API. It is to produce a clearer system in which deterministic code, agents, and controlled workflows each handle the work they are best suited to perform.
Microsoft Agent Framework provides useful building blocks. Production quality still depends on architecture, identity, tool governance, evaluation, observability, and disciplined operations.
Want More?
- AI Assistants and Chatbots
- Enterprise AI Architecture (EAA)
- What Is Semantic Kernel, and When Should .NET Teams Use It?
- The AI Assistant Capability Library Model Explained
References
- Develop .NET apps with AI features
- Microsoft Agent Framework overview
- Understanding the kernel in Semantic Kernel
- Optimize cost for AI workloads on Azure
- AI workload operations on Azure
