Microsoft Agent Framework

Microsoft Agent Framework Development

Build AI agents and multi-agent workflows using Microsoft Agent Framework, the next-generation framework combining Semantic Kernel and AutoGen.

When to Use This Skill

• Building AI agents with LLM capabilities
• Implementing multi-agent orchestration (Sequential, Concurrent, Group Chat, Handoff, Magentic)
• Integrating MCP (Model Context Protocol) tools
• Building workflow automation
• Managing agent sessions and state
• Connecting to Azure OpenAI, OpenAI, Anthropic, GitHub Copilot, or local models (Ollama)

⚠️ Critical Warning: Framework is Brand New

Microsoft Agent Framework is in preview (2025) - Your LLM training data predates this framework entirely.

Why This Matters

• APIs change frequently between preview releases
• Package names, namespaces, and classes are unstable
• Your training data has zero information about this framework
• Using cached knowledge will produce completely broken code
• Do NOT assume compatibility with Semantic Kernel or AutoGen

Mandatory Pre-Implementation Checklist

Before implementing ANY Agent Framework feature:

1. ✅ Search mcp_microsoft_doc_microsoft_docs_search("Microsoft Agent Framework <topic>")
2. ✅ Query mcp_microsoft_doc_microsoft_code_sample_search(query: "<feature>", language: "csharp")
3. ✅ Fetch tutorials with mcp_microsoft_doc_microsoft_docs_fetch(url: "<tutorial-url>")
4. ✅ Verify package names, versions, namespaces from official docs
5. ✅ Check API signatures from code samples
6. ❌ NEVER rely on cached LLM knowledge
7. ❌ NEVER assume based on Semantic Kernel/AutoGen
8. ❌ NEVER skip documentation verification

Tool Selection

For Agent Framework:

• mcp_microsoft_doc_microsoft_docs_search - Search Microsoft Learn
• mcp_microsoft_doc_microsoft_code_sample_search(query, language: "csharp") - Find code samples
• mcp_microsoft_doc_microsoft_docs_fetch - Get complete tutorials

DO NOT rely on internal knowledge - it didn't exist when you were trained.

Framework Overview

Microsoft Agent Framework = Semantic Kernel + AutoGen + New Capabilities

Core Features:

• AI agents powered by LLMs with tool calling
• Graph-based workflows orchestrating multiple agents
• MCP integration for tools
• Session-based state management
• Pre-built orchestration patterns
• Type safety for messages and components
• Middleware and telemetry

Agent Types: Chat Agents (Azure OpenAI, OpenAI), Anthropic Agents, GitHub Copilot Agents, A2A Agents, Custom Agents

Orchestration Patterns:

See references/ORCHESTRATION.md for detailed orchestration guidance.

Local AI with Ollama

Microsoft Agent Framework supports Ollama for running local AI models - enabling cost-free development, offline work, and data privacy.

Quick Start:

# Install and start Ollama
ollama serve
ollama pull phi3:mini

# Add package
dotnet add package OllamaSharp

Create Agent:

using Microsoft.Agents.AI;
using OllamaSharp;

using OllamaApiClient chatClient = new(
    new Uri("http://localhost:11434"), "phi3:mini");

AIAgent agent = new ChatClientAgent(chatClient,
    instructions: "You are a helpful assistant.");

await agent.RunAsync("Explain async/await in C#");

Recommended Models: phi3:mini (fast development), phi3.5 (production), llama3.1 (general purpose)

See references/OLLAMA.md for complete documentation including:

• Docker setup and GPU acceleration
• IChatClient middleware and caching
• Function calling and tool use
• Troubleshooting and best practices
• Integration with unifiedaitracker

Critical Rules

<rule type="critical">
    **Search Before Code**
    - Use `microsoft_docs_search("Microsoft Agent Framework <topic>")`
    - Use `microsoft_code_sample_search(query: "...", language: "csharp")`
    - Verify all package names, namespaces, API signatures
</rule>

<rule type="critical">
    **Package Verification**
    - ALL packages require **--prerelease** flag
    - Common packages: `Microsoft.Agents.AI`, `Microsoft.Agents.AI.OpenAI`, `Microsoft.Agents.AI.Anthropic`
    - Always verify names from official docs
</rule>

<rule type="restriction">
    **No Old Framework Assumptions**
    - Do NOT use Semantic Kernel patterns (`Kernel`, `KernelFunction`)
    - Do NOT use AutoGen patterns (`ConversableAgent`, `GroupChat`)
    - Agent Framework has different APIs - search documentation
</rule>

Standard Workflow

Phase 1: Discovery & Planning

1. Identify Requirements

• Single agent or multi-agent orchestration?
• Which AI provider? (Azure OpenAI, OpenAI, Anthropic, GitHub Copilot)
• Tool/MCP integration needs?
• State management requirements?

2. Research Current Implementation

Step 1: Search concepts
mcp_microsoft_doc_microsoft_docs_search("Microsoft Agent Framework <topic>")

Step 2: Find code samples
mcp_microsoft_doc_microsoft_code_sample_search(
  query: "Microsoft Agent Framework <feature>",
  language: "csharp"
)

Step 3: Get tutorial (if needed)
mcp_microsoft_doc_microsoft_docs_fetch(url: <url>)

3. Verify Prerequisites

• .NET 8.0 SDK or later
• AI provider access configured
• Environment variables ready
• Authentication credentials available

Phase 2: Implementation

1. Create Project

dotnet new console -o MyAgentProject  # or 'web' for ASP.NET Core
cd MyAgentProject

2. Install Packages (Always verify names from docs!)

# Core (always required)
dotnet add package Microsoft.Agents.AI --prerelease

# For Azure OpenAI
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

# For Anthropic
dotnet add package Microsoft.Agents.AI.Anthropic --prerelease

# For GitHub Copilot
dotnet add package GitHub.Copilot.SDK --prerelease

# For Ollama (local models) - see references/OLLAMA.md
dotnet add package OllamaSharp

3. Implement Using Official Patterns

• Follow exact patterns from official samples
• Verify class names, namespaces, method signatures
• Don't improvise based on Semantic Kernel/AutoGen

4. Configure Environment

# Azure OpenAI
$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

# Anthropic
$env:ANTHROPIC_API_KEY="your-api-key"
$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"

# For Ollama setup, see references/OLLAMA.md

Phase 3: Testing & Validation

dotnet build
dotnet run

Verify agent behavior, tool calling, state management, and error handling.

Quick Reference

Creating Basic Agent

Always search first:

mcp_microsoft_doc_microsoft_docs_search("Microsoft Agent Framework create agent Azure OpenAI")
mcp_microsoft_doc_microsoft_code_sample_search(query: "AIAgent Azure OpenAI", language: "csharp")

Azure OpenAI Pattern (verify before using):

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

var client = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")),
    new DefaultAzureCredential());

var chatClient = client
    .GetChatClient(Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME"))
    .AsIChatClient();

var agent = chatClient.AsAIAgent(new()
{
    Instructions = "You are a helpful assistant."
});

var response = await agent.RunAsync("What is Microsoft Agent Framework?");

Ollama (Local) Pattern (verify before using):

using Microsoft.Agents.AI;
using OllamaSharp;

using OllamaApiClient chatClient = new(
    new Uri("http://localhost:11434"), 
    "phi3:mini");

AIAgent agent = new ChatClientAgent(
    chatClient,
    instructions: "You are a helpful assistant.",
    name: "LocalAssistant");

var response = await agent.RunAsync("What is Microsoft Agent Framework?");

MCP Tools

Search: "Microsoft Agent Framework MCP tools"

Multi-Agent Workflows

Search: "Microsoft Agent Framework <pattern> orchestration" where pattern is:

• sequential - Pipeline processing
• concurrent - Parallel analysis
• group chat - Collaborative refinement
• handoff - Dynamic expert routing
• magentic - Complex task planning

See references/ORCHESTRATION.md for details.

State Management

Search: "Microsoft Agent Framework session state management"

Implementation Patterns

See references/PATTERNS.md for detailed patterns:

1. Single Agent with Tools - Function calling and tool integration
2. Sequential Workflow - Pipeline processing with multiple agents
3. Group Chat - Collaborative refinement with manager
4. Human-in-the-Loop - Checkpoint-based approval workflows
5. A2A Communication - Agent-to-Agent protocol for remote agents

Common Use Cases

Customer Support Agent:

Search: "Microsoft Agent Framework chat agent Azure OpenAI"
        "Microsoft Agent Framework tools function calling"
        "Microsoft Agent Framework session state management"

Document Processing Pipeline (Sequential):

Search: "Microsoft Agent Framework sequential workflow orchestration"
Implement: Extraction → Analysis → Summarization agents

Collaborative Analysis (Group Chat):

Search: "Microsoft Agent Framework group chat RoundRobinGroupChatManager"
Implement: Multiple analyst agents with iterative refinement

Expert Routing (Handoff):

Search: "Microsoft Agent Framework handoff orchestration mesh"
Implement: Domain experts with dynamic delegation

Complex Automation (Magentic):

Search: "Microsoft Agent Framework magentic planner"
Implement: Specialized agents with planner-based coordination

Local/Offline Development:

Use: Ollama with phi3 models for cost-free development
See: references/OLLAMA.md for complete setup

Integration with unifiedaitracker

Approach:

1. Add packages to unifiedaitracker.Application
2. Create agent services (e.g., TicketAnalysisService)
3. Register in unifiedaitracker.Infrastructure/Extensions.cs
4. Use via dependency injection in controllers
5. Configure OpenAI connection in AppHost

Search before implementing:

"Microsoft Agent Framework dependency injection ASP.NET Core"
"Microsoft Agent Framework configuration options"

Best Practices

1. Always Verify Documentation First - Search, find samples, fetch tutorials
2. Use Official Code Samples as Templates - Don't improvise
3. Handle Prerelease Carefully - Always use --prerelease, expect breaking changes
4. Implement Error Handling - Search for current patterns
5. Use Telemetry and Monitoring - Built-in observability
6. Secure Configurations - Use environment variables or Key Vault
7. Test Thoroughly - Various inputs, tool calling, error scenarios
8. Design for Observability - Use middleware and filters

Troubleshooting

See references/TROUBLESHOOTING.md for detailed solutions.

Agent Framework Issues:

• Package Not Found → Missing --prerelease flag or wrong package name
• API Signature Mismatch → Using outdated patterns, search for current API
• Authentication Failures → Verify environment variables and Azure RBAC
• Workflow Not Executing → Verify workflow builder syntax from docs
• Agent Not Using Tools → Check tool definition and registration

Ollama Issues: See references/OLLAMA.md for Ollama-specific troubleshooting

Migration

From Semantic Kernel or AutoGen: Do NOT assume compatibility.

Fetch migration guides:

mcp_microsoft_doc_microsoft_docs_fetch(
  url: "https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel/"
)

Success Indicators

✅ Using skill effectively:

• Search docs before every implementation
• Use official code samples as templates
• Verify all package names and API signatures
• Use --prerelease flag consistently
• Code matches current patterns

❌ Warning signs:

• Implementing from memory
• Using Semantic Kernel/AutoGen patterns
• Skipping documentation search
• Guessing at package names/APIs

Essential Commands

# Search docs
mcp_microsoft_doc_microsoft_docs_search("Microsoft Agent Framework <topic>")

# Find code samples
mcp_microsoft_doc_microsoft_code_sample_search(query: "...", language: "csharp")

# Install packages (ALWAYS use --prerelease for Agent Framework)
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

# For local Ollama (see references/OLLAMA.md for complete setup)
dotnet add package OllamaSharp
ollama serve && ollama pull phi3:mini

Additional Resources

See references/QUICK_REFERENCE.md for command cheat sheet.

Official docs:

• Overview: https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview
• Quickstart: https://learn.microsoft.com/en-us/agent-framework/tutorials/quick-start
• User Guide: https://learn.microsoft.com/en-us/agent-framework/user-guide/overview
• ChatClientAgent: https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-types/chat-client-agent
• GitHub: https://github.com/microsoft/agent-framework

Local AI with Ollama: See references/OLLAMA.md for complete documentation

Summary

Microsoft Agent Framework is brand new (2025) and in preview:

1. NEVER trust cached knowledge - framework didn't exist when you were trained
2. ALWAYS search documentation first - APIs change frequently
3. ALWAYS verify package names - use official docs
4. ALWAYS use official code samples - don't improvise
5. ALWAYS use --prerelease flag - all packages are in preview

Use Microsoft documentation MCP tools to gather current information before every implementation.

Never skip the mandatory pre-implementation checklist.

For local development: Use Ollama with Microsoft's Phi-3 models for cost-free, offline-capable development with the same agent code.