Microsoft Agent Framework Labs – Step-by-Step Guide

Adapted for OpenAI and Local Ollama Models

This guide is adapted from the official Microsoft Agent Framework tutorials, specifically configured to work with:

1. OpenAI (direct API, not Azure OpenAI)
2. Local Ollama models running on your development machine

---

Setting Up the Project Solution

Prerequisites

Before diving into the labs, ensure you have:

• .NET SDK 8.0 or later – The Agent Framework supports all supported .NET versions (we recommend .NET 8.0+)
• OpenAI API Key – Get one from https://platform.openai.com/api-keys
• Ollama installed locally – Install from https://ollama.ai
  • Your available models:
    • gpt-oss:120b (65 GB)
    • llama3.2-vision:90b (54 GB)
    • llama3.3:70b (42 GB)
    • deepseek-r1:70b (42 GB)
    • nomic-embed-text:latest (274 MB)
    • mxbai-embed-large:latest (669 MB)
• Microsoft Agent Framework NuGet packages – The labs will use the Microsoft Agent Framework libraries

Required NuGet Packages

For OpenAI support:

dotnet add package Microsoft.Extensions.AI.OpenAI
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

For Ollama support:

dotnet add package Microsoft.Extensions.AI.Ollama
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Solution Setup

1. Create a Solution: In Visual Studio or via CLI:

   dotnet new sln -n AgentFrameworkLabs
   

2. Add a Console Project per Lab: For each lab (1 through 11), add a new .NET console application:

   dotnet new console -n Lab01_SimpleAgent
   dotnet sln add Lab01_SimpleAgent/Lab01_SimpleAgent.csproj
   

3. Create Shared Configuration at solution root:

   Copy the template to create your config file:

   cp appsettings.template.json appsettings.json
   

   Then edit appsettings.json and add your OpenAI API key:

   {
     "AI": {
       "Provider": "OpenAI"
     },
     "OpenAI": {
       "ApiKey": "sk-proj-YOUR-ACTUAL-KEY-HERE",
       "Model": "gpt-4o-mini"
     },
     "Ollama": {
       "Endpoint": "http://localhost:11434",
       "Model": "llama3.3:70b"
     }
   }
   

   Important: appsettings.json is in .gitignore to protect your API key. Never commit it to git!

   To switch providers: Just change "AI:Provider" to either "OpenAI" or "Ollama" - all labs will automatically use the selected provider!

4. Create Shared Helper Class at Shared/AgentConfig.cs:

   using Microsoft.Extensions.AI;
   using Microsoft.Extensions.Configuration;
   using Microsoft.Agents.AI;
   using OpenAI;
   using OpenAI.Chat;
   
   /// <summary>
   /// Shared configuration helper for all labs.
   /// Automatically loads appsettings.json from solution root and provides AI client.
   /// </summary>
   public static class AgentConfig
   {
       private static IConfiguration? _configuration;
   
       public static IConfiguration Configuration
       {
           get
           {
               _configuration ??= new ConfigurationBuilder()
                   .SetBasePath(Path.Combine(Directory.GetCurrentDirectory(), ".."))
                   .AddJsonFile("appsettings.json", optional: false)
                   .Build();
               return _configuration;
           }
       }
   
       /// <summary>
       /// Gets the configured AI chat client based on settings in appsettings.json.
       /// </summary>
       public static IChatClient GetChatClient()
       {
           var provider = Configuration["AI:Provider"] ?? "OpenAI";
   
           return provider.ToLowerInvariant() switch
           {
               "openai" => GetOpenAIChatClient(),
               "ollama" => GetOllamaChatClient(),
               _ => throw new InvalidOperationException(
                   $"Unknown provider: {provider}. Supported providers: OpenAI, Ollama.")
           };
       }
   
       /// <summary>
       /// Gets OpenAI chat client.
       /// </summary>
       public static IChatClient GetOpenAIChatClient()
       {
           var apiKey = Configuration["OpenAI:ApiKey"]
               ?? throw new InvalidOperationException("OpenAI:ApiKey not found in appsettings.json");
           var model = Configuration["OpenAI:Model"] ?? "gpt-4o-mini";
   
           ChatClient chatClient = new OpenAIClient(apiKey).GetChatClient(model);
           return chatClient.AsIChatClient();
       }
   
       /// <summary>
       /// Gets Ollama chat client.
       /// </summary>
       public static IChatClient GetOllamaChatClient()
       {
           var endpoint = Configuration["Ollama:Endpoint"]
               ?? throw new InvalidOperationException("Ollama:Endpoint not found in appsettings.json");
           var model = Configuration["Ollama:Model"]
               ?? throw new InvalidOperationException("Ollama:Model not found in appsettings.json");
   
           if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var uri))
           {
               throw new InvalidOperationException($"Invalid Ollama endpoint URI: {endpoint}");
           }
   
           return new OllamaChatClient(uri, model);
       }
   
       /// <summary>
       /// Gets the current provider name for display purposes.
       /// </summary>
       public static string GetProviderName()
       {
           var provider = Configuration["AI:Provider"] ?? "OpenAI";
   
           return provider.ToLowerInvariant() switch
           {
               "ollama" => FormatProvider("Ollama", Configuration["Ollama:Model"] ?? "(model not set)"),
               _ => FormatProvider("OpenAI", Configuration["OpenAI:Model"] ?? "gpt-4o-mini")
           };
   
           static string FormatProvider(string name, string model) => $"{name} ({model})";
       }
   }
   

5. Required NuGet Packages for Each Lab: Add to each .csproj:

   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.AI" Version="9.9.1" />
     <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.9.0-preview.1.25458.4" />
     <PackageReference Include="Microsoft.Extensions.AI.Ollama" Version="9.7.0-preview.1.25356.2" />
     <PackageReference Include="Microsoft.Agents.AI" Version="1.0.0-preview.251002.1" />
     <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251002.1" />
     <PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.0" />
     <PackageReference Include="OpenAI" Version="2.4.0" />
   </ItemGroup>
   
   <ItemGroup>
     <Compile Include="..\Shared\AgentConfig.cs" Link="Shared\AgentConfig.cs" />
   </ItemGroup>
   

---

Lab 1: Create and Run a Simple Agent

Goal: Build a basic AI agent that can switch between OpenAI and Ollama via configuration.

Complete Code

using System;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

internal class Program
{
    private static async Task Main(string[] args)
    {
        // Automatically uses provider from appsettings.json (AI:Provider)
        IChatClient chatClient = AgentConfig.GetChatClient();

        Console.WriteLine($"🤖 Using: {AgentConfig.GetProviderName()}\n");

        // Create AI Agent with Jamaican history expertise
        AIAgent agent = new ChatClientAgent(
            chatClient,
            instructions: "You are a PhD historian specializing in Jamaican history and Caribbean studies. " +
                         "Provide detailed, accurate information with cultural context and sensitivity.",
            name: "Professor JahMekYanBwoy");

        // Run the agent with streaming for real-time response
        string userPrompt = "Tell me about Jamaica's female national heroes and their contributions to the nation.";

        Console.WriteLine($"📚 Question: {userPrompt}\n");
        Console.WriteLine("💬 Response:\n");

        await foreach (var update in agent.RunStreamingAsync(userPrompt))
        {
            Console.Write(update.Text);
        }

        Console.WriteLine("\n\n✅ Complete!");
    }
}

How It Works

• Shared configuration: Uses AgentConfig.GetChatClient() which reads from shared appsettings.json
• Returns IChatClient: The helper returns IChatClient, enabling the same code to run against OpenAI or Ollama
• ChatClientAgent: Agents are created with ChatClientAgent so provider-specific clients can be swapped transparently
• Streaming output: Uses RunStreamingAsync() for real-time token-by-token display
• Themed prompts: Agent is configured as a Jamaican history expert

Key Differences from Original Tutorial

• Works with both OpenAI and Ollama by toggling AI:Provider
• Requires the Microsoft.Extensions.AI.Ollama package (preview) for local model support
• Uses ChatClientAgent directly instead of the older CreateAIAgent extension methods

Try Different Prompts

// Jamaican history and culture
"Tell me about Jamaica's female national heroes and their contributions to the nation."
"What was the significance of the Maroon Wars in Jamaica?"
"Explain the cultural impact of Marcus Garvey on Jamaica and the diaspora."
"Describe the development of reggae music and its cultural significance."

// Caribbean studies
"How did the sugar trade shape Caribbean societies?"
"What role did Jamaica play in the broader Caribbean independence movement?"

---

Lab 2: Using Images with an Agent

Goal: Analyze images using vision-capable models.

Note: For Ollama, change the model in appsettings.json to llama3.2-vision:90b

Complete Code

using System;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

internal class Program
{
    private static async Task Main(string[] args)
    {
        IChatClient chatClient = AgentConfig.GetChatClient();
        Console.WriteLine($"🤖 Using: {AgentConfig.GetProviderName()}\n");

        // Create vi