AI News
25 Feb 2026
Read 15 min
Agent Framework migration guide How to migrate safely
Agent Framework migration guide helps teams move from Semantic Kernel and AutoGen with clear steps.
This Agent Framework migration guide explains how to move from Semantic Kernel and AutoGen to Microsoft’s Release Candidate with low risk. You will map core concepts, replace packages, convert tools, and rebuild workflows in .NET and Python. Follow a safe rollout plan with parallel runs, feature flags, and strong validation so teams ship with confidence.
Microsoft’s Agent Framework has reached Release Candidate for .NET and Python. That means the API is stable and feature complete for 1.0. It unifies past learnings from Semantic Kernel and AutoGen into one set of patterns: simple agent creation, type-safe tools, graph-based workflows, and multi-provider support. If your apps use chat, tools, or multi-agent orchestration, this is the right time to plan your move.
In this Agent Framework migration guide, you will see what changes, what stays familiar, and how to cut over safely. You will also learn to reduce risk with a two-track rollout, add observability from day one, and keep performance and cost in check.
Stable surface: The API is locked for 1.0, so your code will not chase breaking changes.
Unified model: One way to build agents across .NET and Python, replacing split patterns from Semantic Kernel and AutoGen.
First-class tools: Clear, type-safe tool definitions that agents can call reliably.
Stronger orchestration: Graph-based workflows for sequential, concurrent, handoff, and group chat patterns, with streaming and checkpointing.
Multi-provider reach: Use Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic Claude, AWS Bedrock, Ollama, and more under one roof.
Interoperability: Built-in support for A2A (Agent-to-Agent), AG-UI, and MCP (Model Context Protocol).
Kernel → Agent host/context. You no longer pass a Kernel everywhere; you create agents with a client, then run them.
Skills/Plugins → Tools (function tools). Define tool schemas and let the agent call them with type safety.
Prompts/Functions → Agent instructions + prompts. Keep your prompt text but attach it as agent instructions and per-turn user messages.
Planner/Orchestrator → Workflow engine. Use sequential, concurrent, handoff, or group chat builders for task routing.
Chat history → Sessions and messages. Persist and pass Message objects across turns.
Memory/Embeddings → Optional retrieval steps. Use your existing RAG layers, but wire them as tools or pre/post steps.
Connectors (OpenAI, Azure OpenAI) → Multi-provider clients. Swap in the correct client and deployment name, keep the rest the same.
Agent class → Agent object from a chat/responses client. You get a similar mental model but with a simpler surface.
Tool functions → Function tools. Register callables with schemas; the agent invokes them when needed.
GroupChat → Group chat workflow. Use the built-in group chat orchestration for multi-agent conversations.
Human-in-the-loop → Workflow turn tokens and checkpoints. Pause, inspect, approve, or edit steps.
Streaming updates → Streaming runs/events. Subscribe to events and update your UI in real time.
Inventory your agents. List what each agent does, which tools it calls, and which models it uses.
Identify workflows. Note where you chain steps, run tasks in parallel, or hand work to a reviewer.
Gather prompts. Collect system prompts, user prompts, and prompt templates.
List integrations. Include data sources, vector stores, search endpoints, and third-party APIs.
Mark runtime constraints. Note token limits, latency needs, and cost targets per feature.
Decide language path. Pick .NET or Python for your first migration; plan to port the other side next.
In Python, install the Agent Framework core and any orchestration extras. If you use Azure OpenAI today, add the Azure client package.
In .NET, add Microsoft.Agents.AI packages. Include the OpenAI/Azure OpenAI client package and Azure.Identity for token auth if needed.
Reuse secure auth. If you already use Azure CLI, Managed Identity, or service principals, keep them. Swap keys only if you change providers.
Set endpoints once. Provide your Azure OpenAI resource endpoint and deployment name, or your preferred provider and model ID. Keep this in config.
Make each agent’s role explicit. Move your old “system” prompt into an agent’s instructions.
Keep user-facing prompts as turn messages. Do not blend system and user text; keep roles clear.
Use short, direct language. The Release Candidate works best with crisp instructions that set tone and bounds.
Store prompt templates. If you used template engines before, keep them. Render the final text into user turns at runtime.
Define tool schemas. Specify the name, purpose, input types, and constraints in code so the agent can plan calls.
Return structured data. Return clear objects (not raw strings) for stable follow-up turns and easier testing.
Gate risky tools. Mark tools that write, delete, or spend money. Add human approval steps in the workflow.
Log tool calls. Capture start time, end time, input, output size, and error details for debugging and cost review.
Use sessions for multi-turn. Keep conversation state as a list of messages. Save session IDs in your app store.
Add RAG as a tool or step. If you have a vector store, wrap retrieval as a callable tool, or enrich context before you call the model.
Summarize long threads. Use summarization tools to shrink history and stay within token limits.
Persist checkpoints. If a step fails, your orchestration can restart at the last checkpoint instead of from scratch.
Sequential flows. Model linear steps like “draft → review → publish” with a sequential builder.
Concurrent work. For fan-out tasks like “generate 5 variations,” run agents in parallel and merge results.
Handoff patterns. Route tasks to a reviewer, legal, or support agent based on confidence or topic.
Group chat. Set up multi-agent conversations where each agent has a clear role and the system resolves turn-taking.
Human-in-the-loop. Insert approval gates for tool calls that change data, invoke payments, or send external messages.
Streaming UX. Subscribe to response events so users see partial outputs fast and stay engaged.
Golden prompts. Build small test sets that hit your common intents, edge cases, and failure modes.
Determinism where possible. Fix temperature for tests so you can compare runs.
Telemetry. Track latency, token usage, call counts per tool, and provider costs per feature.
Quality metrics. Score helpfulness, groundedness (when using RAG), and safety. Sample daily.
A/B rollout. Compare old vs. new agents on the same prompts in shadow mode. Promote when you meet targets.
Cost control. Set model caps, batch work, and cache repeat tool results. Prefer smaller models when quality allows.
Feature flag every migrated path. Keep instant rollback without redeploys.
Dark launch and shadow mode. Run the new agent in parallel, do not show outputs to users yet, and log gaps.
Canary by cohort. Start with 1–5% of traffic, then ramp to 25%, 50%, and 100% as metrics stay green.
Clear rollback plan. Keep the previous agent live and the switch reversible in seconds.
Data safety review. Mask PII in logs, scrub prompts of secrets, and enforce least-privileged tool access.
Rate limits and retries. Respect provider quotas. Add backoff and circuit breakers.
Timeouts per step. Fail fast on slow tools and return safe fallbacks.
Drift watch. Monitor quality weekly; models and data can drift.
Token overflows: Summarize long chats and trim unused fields before calls. Use model-specific token calculators in tests.
Over-eager tools: Tools fire too often if instructions are vague. Add a rule like “Call tools only when needed and after you think step-by-step.”
Conflicting roles: In group chat, two agents may talk past each other. Define a coordinator or clearer turn rules.
Model mismatch: Do not assume one model fits all. Use a fast model for classification and a stronger model for long-form tasks.
Loose schemas: If tool parameters are vague, the model will guess. Tighten types and add examples of valid inputs.
State leaks: Clear session state between tests and when users start new tasks.
Error blind spots: Wrap every tool with try/catch and emit structured errors to logs with correlation IDs.
Pick one feature, like “write and review a product tagline.”
Create a writer agent with clear instructions and a reviewer agent that gives short feedback.
Wire a sequential workflow: writer → reviewer. Add a human approval gate before publish.
Move your old prompts into the new instructions and user messages.
Wrap external calls (search, product DB) as tools with strict schemas.
Add streaming so users see drafts in real time. Log tool calls, tokens, and latency.
Run shadow tests with the same inputs as your live system. Compare quality and cost.
Fix gaps, then enable a 5% canary behind a feature flag. Watch errors and spend.
Roll out to 50%, then 100% when stable. Keep the old path for quick rollback during the first week.
Official docs for concepts, APIs, and patterns.
GitHub repo with examples for agents, tools, and workflows.
Community channels for Q&A and migration tips.
Package feeds: NuGet for .NET, PyPI for Python.
Provider dashboards: Azure OpenAI or your chosen model provider for quotas and metrics.
Our Agent Framework migration guide is not just about code; it is about safe delivery. Keep roles clear, schemas tight, and workflows testable. Start small, measure hard, and scale only when quality and cost are steady. The Release Candidate gives you a stable base and modern patterns you can trust in production.
If you are moving from Semantic Kernel or AutoGen, you will find that most building blocks have a direct home in the new model. Your prompts, your tool logic, and your orchestration ideas all carry over. With a careful plan, you can ship better agents, faster. Use this Agent Framework migration guide as your checklist, and move with confidence.
Why move now: benefits of the Release Candidate
Agent Framework migration guide: from Semantic Kernel and AutoGen
Use this Agent Framework migration guide to connect old and new concepts. You can move feature by feature instead of a big bang rewrite.Concept map: Semantic Kernel to Agent Framework
Concept map: AutoGen to Agent Framework
Prepare your codebase
Update packages and authentication
Convert prompts, tools, and memory
Prompts and instructions
Tools and function calls
State, sessions, and memory
Rebuild orchestrations and streaming
Test, observe, and optimize
Safe rollout checklist
Common pitfalls and fixes
Sample end-to-end path
Resources to keep handy
(Source: https://devblogs.microsoft.com/foundry/microsoft-agent-framework-reaches-release-candidate/)
For more news: Click Here
FAQ
Q: Why should teams migrate now from Semantic Kernel or AutoGen to Microsoft Agent Framework?
A: This Agent Framework migration guide notes the framework has reached Release Candidate for .NET and Python, which means the API surface is stable and feature-complete for version 1.0. It also unifies patterns from Semantic Kernel and AutoGen into one model with simple agent creation, type-safe tools, graph-based workflows, and multi-provider support.
Q: What are the main concept mappings from Semantic Kernel to Agent Framework?
A: Common mappings include Kernel → agent host/context, Skills/Plugins → function tools, and Prompts/Functions → agent instructions plus per-turn user messages. Planner/Orchestrator becomes the workflow engine, chat history becomes sessions and messages, memory/embeddings map to optional retrieval steps, and connectors become multi-provider clients.
Q: How do AutoGen concepts translate to the Agent Framework model?
A: AutoGen’s Agent class maps to an Agent object from a chat or responses client and tool functions map to function tools with schemas. GroupChat becomes a group chat workflow, human-in-the-loop maps to workflow turn tokens and checkpoints, and streaming updates map to streaming runs and events.
Q: What preparatory steps does the Agent Framework migration guide recommend for a codebase?
A: Prepare by inventorying your agents, listing what each agent does and which tools and models it calls, identifying workflows, and gathering system and user prompts. Also list integrations (vector stores, search, APIs), mark runtime constraints like token limits and latency, and choose whether to migrate .NET or Python first.
Q: What package and authentication changes are required when migrating?
A: In Python, install the Agent Framework core and any orchestration extras and add the Azure client package if you use Azure OpenAI. In .NET, add Microsoft.Agents.AI packages and include the OpenAI/Azure OpenAI client package plus Azure.Identity for token authentication. Reuse existing secure auth methods such as Azure CLI, Managed Identity, or service principals and keep provider endpoints and deployment names in configuration.
Q: How should prompts, tools, and memory be converted during migration?
A: Move system prompts into explicit agent instructions and keep user-facing prompts as turn messages or rendered templates at runtime. Define tool schemas with clear input types, return structured data, gate risky tools with human approval and logging, use sessions to persist message lists, wrap RAG retrieval as a tool or pre-step, summarize long threads, and persist checkpoints for restartability.
Q: How should orchestrations and streaming be rebuilt in Agent Framework?
A: Rebuild flows using the framework’s sequential, concurrent, handoff, and group chat builders and model fan-out/fan-in patterns for parallel work. Insert human-in-the-loop approval gates where needed, enable checkpointing, and subscribe to streaming runs/events so UIs can show partial outputs in real time.
Q: What testing, rollout practices, and common pitfalls does the migration guide recommend?
A: Test with golden prompts and deterministic settings, add telemetry for latency, token usage, tool calls, and quality metrics, and run A/B or shadow comparisons before promoting changes. Follow a safe rollout checklist with feature flags, dark launches, cohort canaries and clear rollback plans, data safety reviews, rate limits and timeouts, and weekly drift monitoring; watch for pitfalls like token overflows, over-eager tools, conflicting roles, model mismatches, loose schemas, state leaks, and unhandled tool errors.
Contents
