Working with Microsoft Agent Framework Skill

Working with Microsoft Agent Framework

Microsoft Agent Framework (October 2025) unifies Semantic Kernel and AutoGen into one SDK. Both legacy frameworks are in maintenance mode.

Core principle: Agents are stateless. All state lives in threads. Context providers enforce policy about what enters the prompt, how, and when it decays.

Additional reference files in this skill:

context-providers.md - Policy-based memory, capsule pattern, Mem0 integration

orchestration-patterns.md - The 5 orchestration patterns with when-to-use guidance

design-patterns.md - Production patterns, testing, migration

When to Use

Building AI agents with Microsoft's unified framework
Implementing custom memory with Context Providers
Creating multi-agent workflows with checkpointing
Migrating from Semantic Kernel or AutoGen

When NOT to Use

Simple single-turn LLM calls (use chat client directly)
Projects staying on legacy SK/AutoGen
Non-Microsoft frameworks (LangChain, CrewAI)

Technology Stack Hierarchy

Official guidance (Jeremy Licknes, PM): Start with ME AI, escalate only when needed.

| Layer | Use For | When to Escalate | |-------|---------|------------------| | ME AI (Microsoft.Extensions.AI) | Chat clients, structured outputs, embeddings, middleware | Need agents, workflows, memory | | Agent Framework | Agents, threads, orchestration, context providers | Need specific SK adapters | | Semantic Kernel | Specific adapters, utilities not in ME AI | Never start here |

ME AI (foundation) → Agent Framework (agents/workflows) → SK (specific utilities only)

Key insight: ME AI provides universal APIs that work across OpenAI, Ollama, Foundry Local, etc. Agent Framework builds on ME AI for agentic patterns. SK primitives migrated to ME AI; only use SK for specific adapters not yet in ME AI.

ME AI features you get automatically:

Structured outputs (typed responses via extension methods)
Middleware (OpenTelemetry, chat reduction)
Universal chat client abstraction
Embeddings generation

Architecture Quick Reference

| Concept | C# Type | Purpose | |---------|---------|---------| | Agent | AIAgent | Stateless LLM wrapper | | Thread | AgentThread | Stateful conversation container | | Context Provider | AIContextBehavior | Policy-based memory/context injection | | Orchestration | SequentialOrchestration, etc. | Multi-agent coordination |

Installation

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Azure.AI.OpenAI --version 2.1.0

Agent Creation

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Azure OpenAI
AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<resource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .CreateAIAgent(
            instructions: "You are a helpful assistant.",
            name: "Assistant");

// Direct OpenAI
var agent = new OpenAIClient("api-key")
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient()
    .CreateAIAgent(instructions: "...", name: "Assistant");

// With tools
[Description("Gets weather for a location")]
static string GetWeather(string location) => $"Sunny in {location}";

AIAgent agent = chatClient.CreateAIAgent(
    instructions: "You help with weather queries.",
    tools: [AIFunctionFactory.Create(GetWeather)]
);

Execution

// Simple
Console.WriteLine(await agent.RunAsync("Hello!"));

// With thread for multi-turn
AgentThread thread = agent.GetNewThread();
await agent.RunAsync("My name is Alice.", thread);
await agent.RunAsync("What's my name?", thread); // Remembers "Alice"

// Streaming
await foreach (var update in agent.RunStreamingAsync("Tell me a story.", thread))
{
    Console.Write(update.Text);
}

Streaming with Resilience

For production streaming, add cancellation support and resilience:

// Basic streaming with cancellation
await foreach (var update in agent.RunStreamingAsync("Tell me a story.", thread)
    .WithCancellation(cancellationToken))
{
    Console.Write(update.Text);
}

// With Polly resilience pipeline
var pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 3 })
    .AddTimeout(TimeSpan.FromMinutes(2))
    .Build();

await pipeline.ExecuteAsync(async token =>
{
    await foreach (var chunk in agent.RunStreamingAsync(userMessage, thread)
        .WithCancellation(token))
    {
        Console.Write(chunk.Text);
    }
}, cancellationToken);

Error differentiation:

OperationCanceledException: User cancelled
TimeoutRejectedException: Polly timeout
HttpRequestException: Network issues

Development UI (DevUI)

Lightweight web interface for testing agents and workflows. Development only—not for production.

Python Setup

Install:

pip install agent-framework-devui --pre

Option 1: Programmatic Registration

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient
from agent_framework.devui import serve

agent = ChatAgent(
    name="WeatherAgent",
    chat_client=OpenAIChatClient(),
    tools=[get_weather]
)

# Launch DevUI with tracing
serve(entities=[agent], auto_open=True, tracing_enabled=True)
# Opens browser to http://localhost:8080

Option 2: Directory Discovery (CLI)

devui ./entities --port 8080 --tracing

Directory structure for discovery:

entities/
    weather_agent/
        __init__.py      # Must export: agent = ChatAgent(...)
        .env             # Optional: API keys
    my_workflow/
        __init__.py      # Must export: workflow = WorkflowBuilder()...

C# Setup

C# embeds DevUI as SDK component (docs in progress):

var app = builder.Build();

app.MapOpenAIResponses();
app.MapConversation();

if (app.Environment.IsDevelopment())
{
    app.MapAgentUI(); // Accessible at /ui
}

Features

| Feature | Description | |---------|-------------| | Web interface | Interactive testing of agents/workflows | | OpenAI-compatible API | Use OpenAI SDK against local agents | | Tracing | OpenTelemetry spans in debug panel | | File uploads | Multimodal inputs (images, documents) | | Auto-generated inputs | Workflow inputs based on first executor type |

Tracing in DevUI

Enable with --tracing flag or tracing_enabled=True. View in debug panel:

Agent Execution
├── LLM Call (prompt → response)
├── Tool Call
│   ├── Tool Execution
│   └── Tool Result
└── LLM Call (prompt → response)

Export to external tools (Jaeger, Azure Monitor):

export OTLP_ENDPOINT="http://localhost:4317"
devui ./entities --tracing

OpenAI SDK Integration

Interact with DevUI agents via OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")
response = client.responses.create(
    metadata={"entity_id": "weather_agent"},
    input="What's the weather in Seattle?"
)

CLI Options

devui [directory] [options]
  --port, -p      Port (default: 8080)
  --tracing       Enable OpenTelemetry tracing
  --reload        Auto-reload on file changes
  --headless      API only, no UI
  --mode          developer|user (default: developer)

Thread Serialization (Critical Pattern)

// Serialize for persistence
JsonElement serialized = await thread.SerializeAsync();
await File.WriteAllTextAsync("thread.json", serialized.GetRawText());

// Later: restore and resume
string json = await File.ReadAllTextAsync("thread.json");
JsonElement element = JsonSerializer.Deserialize<JsonElement>(json);
AgentThread restored = agent.DeserializeThread(element, JsonSerializerOptions.Web);
await agent.RunAsync("Continue...", restored);

Key behaviors:

Service-managed threads: Only thread ID serialized
In-memory threads: All messages serialized
WARNING: Deserializing with different agent config may error

Context Providers (Policy-Based Memory)

Context providers are not "memory injection" — they're policy enforcement:

| Policy | What It Decides | |--------|-----------------| | Selection | What becomes memory | | Gating | When it's retrieved | | Decay | When it expires | | Noise avoidance | When NOT to use |

ChatHistoryAgentThread thread = new();

// Long-term user memory
thread.AIContextProviders.Add(new Mem0Provider(httpClient, new() { UserId = "user123" }));

// Short-term conversation context
thread.AIContextProviders.Add(new WhiteboardProvider(chatClient));

// RAG integration
thread.AIContextProviders.Add(new TextSearchProvider(textSearch, new()
{
    SearchTime = TextSearchProviderOptions.RagBehavior.OnDemandFunctionCalling
}));

See context-providers.md for custom implementation patterns.

Orchestration Patterns

| Pattern | Use When | |---------|----------| | Sequential | Clear dependencies (draft → review → polish) | | Concurrent | Independent perspectives, ensemble reasoning | | Handoff | Unknown optimal agent upfront, dynamic expertise | | GroupChat | Collaborative ideation, human-in-the-loop | | Magentic | Complex open-ended problems |

// Sequential
SequentialOrchestration orchestration = new(analystAgent, writerAgent);

// Handoff - CRITICAL: Always set termination conditions!
var workflow = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
    .WithHandoffs(triageAgent, [mathTutor, historyTutor])
    .WithHandoff(mathTutor, triageAgent)      // Allows routing back
    .WithHandoff(historyTutor, triageAgent)
    .WithMaxHandoffs(10)                      // REQUIRED: Prevent infinite loops
    .Build();

// Execute
InProcessRuntime runtime = new();
await runtime.StartAsync();
var result = await orchestration.InvokeAsync(task, runtime);

CRITICAL for Handoffs: Missing .WithMaxHandoffs() causes infinite loops. Always set termination conditions.

See orchestration-patterns.md for detailed patterns and when-to-use guidance.

Workflow Checkpointing & Durability

For workflows that must survive process restarts:

// Basic checkpointing with CheckpointManager
var checkpointManager = CheckpointManager.Default;

await using Checkpointed<StreamingRun> checkpointedRun =
    await InProcessExecution.StreamAsync(workflow, input, checkpointManager);

// Resume from checkpoint
await InProcessExecution.ResumeStreamAsync(savedCheckpoint, checkpointManager);

Thread-Based Persistence Pattern

For long-running workflows, checkpoint thread state after each step:

// Save thread state after each workflow step
var serialized = await thread.SerializeAsync();
await checkpointStore.SaveAsync(workflowId, currentStep, serialized.GetRawText());

// Resume after restart
var json = await checkpointStore.GetAsync(workflowId);
var element = JsonSerializer.Deserialize<JsonElement>(json);
var restored = agent.DeserializeThread(element, JsonSerializerOptions.Web);
await agent.RunAsync(nextStep, restored);

Recovery on Startup

public class WorkflowRecoveryService : BackgroundService
{
    private readonly ICheckpointStore _store;
    private readonly AIAgent _agent;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        var pending = await _store.GetPendingWorkflowsAsync();
        foreach (var workflow in pending)
        {
            var thread = _agent.DeserializeThread(workflow.State, JsonSerializerOptions.Web);
            await _agent.RunAsync(workflow.NextStep, thread, cancellationToken: ct);
        }
    }
}

Key principle: Checkpoint after each step completes, not before. This ensures you can resume from the last successful step.

Migration Quick Reference

From Semantic Kernel

| SK | Agent Framework | |----|-----------------| | Kernel | AIAgent | | ChatHistory | AgentThread | | [KernelFunction] | [Description] on methods | | IPromptFilter | AIContextBehavior | | KernelFunctionFactory.CreateFromMethod | AIFunctionFactory.Create |

From AutoGen

| AutoGen | Agent Framework | |---------|-----------------| | AssistantAgent | AIAgent via CreateAIAgent() | | FunctionTool | AIFunctionFactory.Create() | | GroupChat/Teams | WorkflowBuilder patterns | | TopicSubscription | AgentWorkflowBuilder.WithHandoffs() | | BaseAgent, IHandle<> | AIAgent with tools |

Topic-Based to Handoff Migration:

// ❌ OLD AutoGen pattern (deprecated)
[TopicSubscription("queries")]
public class MyAgent : BaseAgent, IHandle<Query>
{
    public async Task Handle(Query msg, CancellationToken ct)
    {
        // Process and publish to another topic
        await PublishMessageAsync(new Response(...), "responses");
    }
}

// ✅ NEW Agent Framework pattern
var triageAgent = chatClient.CreateAIAgent(
    instructions: "Route queries to appropriate specialist.",
    name: "Triage");

var mathAgent = chatClient.CreateAIAgent(
    instructions: "Handle math queries.",
    name: "Math");

var workflow = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
    .WithHandoffs(triageAgent, [mathAgent, otherAgent])
    .WithMaxHandoffs(10)  // REQUIRED
    .Build();

await workflow.InvokeStreamingAsync(input, runtime);

Anti-Patterns

| Don't | Do | |-------|-----| | Store state in agent instances | Use AgentThread for all state | | Serialize only messages | Serialize entire thread | | Share agent instances in workflows | Use factory pattern | | Mix thread types across services | Threads are service-specific | | Use Magentic when Sequential suffices | Use simplest pattern that works | | Skip UseImmutableKernel with ContextualFunctionProvider | Always set UseImmutableKernel = true | | Start with Semantic Kernel for new projects | Start with ME AI, escalate to Agent Framework |

Red Flags - STOP

Using Kernel instead of AIAgent (old SK)
Using AssistantAgent instead of AIAgent (old AutoGen)
Thread deserialization fails (missing serialization constructor in context provider)
Memory lost between sessions (serializing messages instead of thread)
Infinite handoff loops (need termination conditions)

Known Limitations

Distributed runtime: In-process only; distributed execution planned
C# Magentic: Most examples are Python
C# message stores: Redis/database need custom implementation
Token counting: Budget calculation in providers undocumented
DevUI C# docs: Python has full docs; C# DevUI docs "coming soon" (embedded SDK approach differs)
GA timeline: Agent Framework stable release "coming soon" (as of Jan 2025)

Resources

GitHub: github.com/microsoft/agent-framework
Docs: learn.microsoft.com/en-us/agent-framework/
Migration: learn.microsoft.com/en-us/agent-framework/migration-guide/

Agent Skills: Working with Microsoft Agent Framework

Install this agent skill to your local

Skill Files