🚀 5-Minute Migration Summary

1. Replace Microsoft.Agents.AI.AzureAI → Microsoft.Agents.AI.Foundry
2. Update Azure.AI.Projects to v2.0.0+
3. Change InvokeAsync() → RunAsync(), AgentResponseItem<T> → AgentResponse
4. Register tools via AIFunctionFactory.Create() instead of [KernelFunction]
5. Use AIProjectClient + DefaultAzureCredential for cloud auth

Stuck? Run the official migration assistant for automated code analysis.

The era of rapid, prompt-driven prototyping—often referred to as “vibe coding”—has served its purpose for initial concept validation. However, enterprise systems demand predictability, robust state management, and clear orchestration. The transition to Agentic Engineering is how development moves from unstable demos to highly secure, production-grade backends.

With the Microsoft Agent Framework (MAF) reaching its 1.0 General Availability (GA) milestone in April 2026, the ecosystem has officially matured. This is a production-ready SDK for building intelligent agents and multi-agent workflows in .NET. However, the road to 1.0 brought a wave of package consolidations, rebrands, and architectural shifts.

If your backend is suddenly failing to resolve preview packages, or you are looking to architect a new AI system this month, this guide breaks down the current state of MAF, the exact features each package provides, and how to migrate your existing code.

✅ Pre-Migration Checklist

Before diving into code changes, verify your environment is ready:

• Inventory all Microsoft.Agents.AI.AzureAI namespace references in your codebase
• Verify your Azure subscription has Microsoft Foundry enabled
• Test DefaultAzureCredential auth flow in your dev environment (az login --tenant <your-tenant>)
• Audit custom plugins for [KernelFunction] → AIFunctionFactory conversion
• Plan observability strategy: OpenTelemetry endpoint, log retention policy, and evaluation metrics
• Backup existing agent definitions and conversation logs before migration

The Great Consolidation: Pre-1.0 to GA Migration

To align with the Microsoft Foundry branding (evolved from Azure AI Studio in late 2024, rebranded to Microsoft Foundry at Ignite 2025) and streamline the developer experience, Microsoft aggressively cleaned up overlapping responsibilities in the SDKs leading up to the 1.0 release.

Here is the definitive mapping of what happened to the release candidate (RC) and beta packages:

⚠️ Version Note: Azure.AI.Projects v2.0.0 is GA for core resource management. Advanced features like hosted agent deployment and evaluation dashboards may require preview add-on packages (e.g., Azure.AI.Projects.OpenAI).

Official Migration Assistants

If you are staring at a massive codebase built on earlier iterations of Semantic Kernel or AutoGen, you do not have to upgrade manually. Microsoft has released official migration tooling to automate the transition to MAF 1.0.

These tools analyze your existing codebase and generate a step-by-step upgrade plan, flagging deprecated APIs and suggesting replacement patterns.

• Official Semantic Kernel to Agent Framework Migration Guide
• Official AutoGen Migration Guides (via the Agent Framework Hub)
• Migration Assistant Tool (GitHub)

The Anatomy of the Framework: Package Breakdown

To successfully architect an agentic system today, you must understand the layered architecture of MAF. Each package and class has a strict, isolated responsibility.

1. The Foundation: Microsoft.Extensions.AI (v10.5.1)

This is the vendor-neutral bedrock. Programming against these interfaces ensures your backend architecture isn’t permanently coupled to a single provider. For example, if you are developing and running local inference models on a 128GB Mac Studio with an M4 chip to avoid cloud costs, this abstraction layer allows you to seamlessly swap your local model for a deployed Azure OpenAI endpoint when moving to production, without changing your core business logic.

• IChatClient: The core interface for interacting with models. It abstracts away the specific HTTP calls, serialization, and connection streaming, allowing you to focus strictly on the conversation logic.
• IEmbeddingGenerator: Standardized interface for generating vector embeddings across providers.
• AIFunctionFactory: This is the lifeblood of tool-calling. It seamlessly wraps standard C# methods into “AIFunction” objects that the AI can understand, invoke, and correctly map JSON parameters to.
• ChatResponseFormatJson: Enforce structured outputs to ensure machine-parseable responses—critical for reducing parsing errors in agentic workflows.
• CachingChatClient: A built-in delegating client that caches responses, vastly reducing API costs and latency during local testing and development.

2. The Core Primitives: Microsoft.Agents.AI.Abstractions (v1.0.0)

This lightweight library defines the foundational contracts that every agent must follow. Build custom plugins, tools, or memory providers in isolated, lean class libraries without dragging in the heavy orchestration engine.

• AIAgent (and IAgent): This is the definition of a reactive entity in your system. It represents an actor that can process information, reason, and act. It defines how an agent identifies itself, its system instructions, and how it receives inputs.
• IMessage: The universal carrier for information. Unlike a simple string, an IMessage carries vital metadata about the sender, the recipient, the intent, and any structured tool-call data (like JSON payloads). It is the standardized language used for agents to “talk” to each other in multi-agent systems.
• IPlugin: Think of this as a “Backpack of Capabilities.” An IPlugin is a container for one or more AIFunctions. By attaching an IPlugin to an agent, you are injecting a distinct set of skills into its context window (e.g., attaching an “HR Directory Plugin” or a “Database Query Plugin”).

3. The Execution Engine: Microsoft.Agents.AI (v1.0.0)

This is the operational brain of the framework. It implements the abstractions and handles the complex orchestration required for autonomous systems.

• Multi-Agent Workflows: It manages graph-based execution, supporting sequential routing, concurrent background tasks, and complex group chats.
• Model Context Protocol (MCP): This allows agents to dynamically discover and connect to external enterprise tools. Instead of writing manual HTTP wrappers for every new internal API, your agent can connect to an MCP server to instantly understand available enterprise tools.
• Agent-to-Agent (A2A) Protocol: Coming Soon – A structured messaging protocol enabling cross-runtime collaboration (e.g., .NET agent coordinating with Python agent). A2A 1.0 support is expected in a future update.

⚠️ Protocol Status Note: MCP integration is GA in MAF 1.0. A2A (Agent-to-Agent) protocol support is currently in preview with 1.0 GA expected in a future update.

Deep Dive: The Foundry Connection

When you integrate cloud resources into your .NET backend, the integration relies heavily on the Azure ecosystem SDKs.

Azure.AI.Projects and AIProjectClient

The Azure.AI.Projects.AIProjectClient is your programmatic entry point to the Microsoft Foundry ecosystem. Think of it as the central control plane for your cloud project resources, including telemetry, datasets, and endpoint configurations.

It establishes a secure connection using Azure.Identity.DefaultAzureCredential.

• DefaultAzureCredential: This is an intelligent authentication chain. It automatically inspects your environment to determine how to securely authenticate. If you are developing locally, it intercepts your Azure CLI or Visual Studio login tokens. If the backend is running in the cloud, it automatically authenticates using the Managed Identity of the host server. This completely eliminates the need for hardcoded connection strings or rotating secrets in your configuration files.

The Critical Role of Microsoft.Agents.AI.Foundry

A major architectural question often arises: “If my backend is just hitting an LLM model endpoint deployed on Foundry, but I am orchestrating the agents locally and NOT using the fully managed Foundry Agent service, do I still need the Microsoft.Agents.AI.Foundry package?”

The answer is Yes, and it comes down to enterprise observability, state management, and ecosystem access. Even if your multi-agent engine runs entirely in your own backend, this package provides indispensable integration capabilities:

1. Native OpenTelemetry and Tracing: Microsoft.Agents.AI.Foundry provides highly optimized, Foundry-specific extensions for IChatClient that automatically format and stream rich OpenTelemetry data directly to Foundry’s evaluation and tracing dashboards. This allows you to visually debug token usage, tool invocation latency, and exact reasoning steps without writing custom logging middleware.
2. Managed Memory (Threads) Offloading: Building custom databases to track complex, multi-turn conversational state is difficult. This package allows your local orchestrator to seamlessly offload conversational history to Foundry’s managed “Threads.” You simply pass a Thread ID, and the package handles retrieving and appending the context window directly from Azure’s highly available storage.
3. Zero-Boilerplate RAG (Retrieval-Augmented Generation): If you have documents indexed in Azure AI Search, the Foundry package provides native integration. It allows your standard IChatClient to perform complex vector searches and ground its answers using your specific Foundry data connections, bypassing the need to manually orchestrate the embedding generation and database querying steps.

✅ Initialization Example (GA 1.0)

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

// 1. Establish the connection to the Foundry Project
var projectClient = new AIProjectClient(
    endpoint: "https://your-project.services.ai.azure.com",
    credential: new DefaultAzureCredential());

// 2. Define the Agentic Workflow using GetChatClient (not GetResponsesClient)
var agent = projectClient
    .GetChatClient("gpt-4.5")  // ✅ Correct method name per official docs
    .AsAIAgent(
        name: "hr-sync-agent",
        instructions: "You process lifecycle events. Validate HR data payloads before calling the Active Directory sync tools.",
        tools: [new CodeInterpreterToolDefinition()]);

// 3. Execute with structured output enforcement
var response = await agent.RunAsync(
    "Process new employee onboarding for [email protected]",
    new ChatOptions { ResponseFormat = ChatResponseFormatJson.Instance });

📌 Source: Official .NET quickstart uses GetChatClient() and requires explicit credential parameter.

Middleware: The Secret Weapon for Production Safety

The middleware pipeline intercepts every agent turn—before and after LLM calls—enabling critical production capabilities without modifying your core agent logic.

Common Middleware Patterns

builder.Services.AddChatClient(openAIClient)
    // 🔒 Content Safety: Block PII or policy violations
    .UseMiddleware(async (context, next) =>
    {
        if (context.Messages.Any(m => ContainsSensitiveData(m.Content)))
        {
            return new ChatResponse { Content = "Request blocked: policy violation" };
        }
        return await next(context);
    })
    // 📊 Observability: Auto-inject OpenTelemetry spans
    .UseOpenTelemetry(loggerFactory, "my-agent", options =>
    {
        options.EnableSensitiveData = false; // Security best practice
        options.RecordToolCalls = true;
        options.RecordTokenUsage = true;
    })
    // ♻️ Retry Logic: Handle transient API failures
    .UseRetry(new RetryOptions
    {
        MaxRetries = 3,
        Delay = TimeSpan.FromSeconds(2)
    });

Middleware Capabilities Overview

Memory Management: Choosing the Right Backend

Agentic systems require robust state management. MAF 1.0 supports pluggable memory architectures—choose the backend that fits your use case.

Example: Using Foundry Managed Threads

// Offload conversation history to Foundry-managed storage
var thread = await projectClient.Threads.CreateThreadAsync();
var response = await agent.RunAsync(
    "Continue our discussion about Q3 planning",
    options: new ChatOptions { ThreadId = thread.Id }); // ✅ Automatic context hydration

Debug Like a Pro: Using the DevUI

MAF 1.0 includes a browser-based debugger that visualizes agent behavior during local development—no code changes required.

What DevUI Shows You

• 🔄 Message flow between agents in multi-agent workflows
• ⚡ Tool invocation timing, parameters, and results
• 💬 Token consumption per reasoning step
• 🎯 Checkpoint hydration points for stateful agents
• 🛑 Human-in-the-loop approval gates

Enable DevUI in Your Project

// In Program.cs or Startup.cs
builder.Services.AddAgentFramework()
    .UseDevUI(port: 5001); // Launches at https://localhost:5001/devui

💡 Pro Tip: DevUI works with both local and cloud-hosted agents. Use it to validate tool schemas, debug conversation loops, and profile performance before deployment.

Human-in-the-Loop: Adding Approval Gates for High-Risk Actions

Enterprise adoption requires explicit approval workflows for sensitive operations. Use checkpointing to persist state during approval waits.

Example: Approval Gate for AD Sync Operations

var workflow = new SequentialBuilder()
    .AddStep(async (context, next) =>
    {
        var action = await agent.ProposeActionAsync(context);

        // Pause for human approval on high-risk actions
        if (action.RiskLevel == RiskLevel.High)
        {
            var approval = await _approvalService.RequestApprovalAsync(
                action,
                context.User,
                timeout: TimeSpan.FromHours(1));

            if (!approval.Granted)
                return AgentResponse.Reject("Action denied by approver");
        }

        return await next(context);
    })
    .Build();

// Register workflow with checkpointing for state persistence
builder.Services.AddAgentFramework()
    .AddWorkflow("hr-sync", workflow)
    .UseCheckpoints(new AzureBlobCheckpointStore(connectionString));

🔒 Security & Validation: The Non-Negotiables

Critical patterns for enterprise-grade agentic systems:

1. Tool Authorization: Never trust agent-selected parameters. Validate all inputs before execution.

   Code

   Copy

   [AIFunction("syncToActiveDirectory")]
   public async Task SyncUser([AIFunctionParameter("email")] string email)
   {
       // ✅ Validate before execution
       if (!EmailValidator.IsValid(email) || !UserHasPermission(email))
           throw new UnauthorizedAccessException("Invalid target or insufficient permissions");
   
       await _adService.SyncUserAsync(email);
   }

2. Timeout Policies: Set explicit timeouts on external API calls to prevent hanging agents.

   Code

   Copy

   var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
   builder.Services.AddChatClient(new OpenAIClient(..., httpClient: client));

3. Structured Output Enforcement: Use ChatResponseFormatJson to ensure machine-parseable responses, reducing parsing errors.

   Code

   Copy

   var options = new ChatOptions
   {
       ResponseFormat = ChatResponseFormatJson.Instance,
       Temperature = 0 // Deterministic outputs for structured data
   };

4. Secrets Management: Never hardcode credentials. Use DefaultAzureCredential + Azure Key Vault for sensitive configuration.

🛠️ Troubleshooting Common Migration Issues

Based on community feedback, here are frequent pain points and solutions:

Declarative vs. Programmatic Agent Definition: When to Use Which

MAF 1.0 supports both YAML-based declarative definitions and programmatic construction. Choose based on complexity:

Rule of Thumb: Use declarative YAML for configuration-driven agents (instructions, tools, memory config). Use programmatic AIAgent construction when you need dynamic logic, conditional tool selection, or runtime-generated instructions.

Declarative Example (agent.yaml)

name: hr-onboarding-agent
model: gpt-4.5
instructions: |
  You process new employee onboarding. Validate all HR payloads before sync.
tools:
  - type: code_interpreter
  - type: azure_ai_search
    index_name: employee-directory
memory:
  type: foundry_threads

Programmatic Example

var agent = new AIAgent(
    name: "hr-onboarding-agent",
    model: "gpt-4.5",
    instructions: GenerateDynamicInstructions(userContext), // ✅ Runtime logic
    tools: SelectToolsBasedOnRole(userRole)); // ✅ Conditional tooling

Final Thoughts: From Vibe Coding to Production Engineering

Vibe coding is an excellent way to learn the syntax of an API, but Agentic Engineering builds the resilient backend systems that power real businesses. By upgrading to the MAF 1.0 stable release, mapping your AzureAI references to Foundry, and strictly relying on the Microsoft.Extensions.AI abstractions for model neutrality, you establish an architecture that is:

✅ Secure: DefaultAzureCredential, tool validation, and secret management built-in
✅ Observable: Native OpenTelemetry integration with Foundry dashboards
✅ Scalable: Pluggable memory, middleware pipelines, and cloud-native orchestration
✅ Maintainable: Vendor-neutral abstractions enable provider swaps without rewrites

📚 Essential Resources

🚀 Next Steps

1. Run the migration assistant against your codebase
2. Update package references using the migration table above
3. Instrument your agents with UseOpenTelemetry() for immediate observability
4. Add validation middleware to high-risk tool calls
5. Test locally with DevUI before deploying to Foundry

Remember: Agentic Engineering isn’t about replacing developers—it’s about empowering you to build systems where AI participates reliably in structured workflows. With MAF 1.0, Microsoft has given .NET teams the toolkit to do exactly that.