shield_lock
JinDaGe
← Back to skills
extension
Category: Content & MediaNo API key required

microsoft-agent-framework

Expert guidance for implementing AI agents and multi-agent workflows using Microsoft Agent Framework. Use when adding AI agent capabilities, implementing multi-agent orchestration patterns, integrating MCP tools, or building intelligent automation systems. Emphasizes gathering up-to-date information from official documentation before implementation.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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:

| Pattern | Topology | Use Case | |---------|----------|----------| | Sequential | Chain | Pipelines, multi-stage processing | | Concurrent | Broadcast | Parallel analysis, independent tasks | | Group Chat | Star | Iterative refinement, collaboration | | Handoff | Mesh | Dynamic delegation, expert routing | | Magentic | Star | Complex planning, generalist tasks |

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

<rules> <rule type="critical"> **Mandatory Research** - Follow pre-implementation checklist before ANY implementation - NEVER skip documentation verification - Framework is PREVIEW - APIs change frequently - Your training data does not include this framework </rule> 
<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>
</rules>

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.