Building AI Agents with Microsoft Agent Framework and Ollama: A Getting Started Guide

# Windows (using winget)
winget install Ollama.Ollama

# macOS (using Homebrew)
brew install ollama

# Linux (using curl)
curl -fsSL https://ollama.com/install.sh | sh

# Recommended model (balanced performance)
ollama pull qwen3:8b

# Alternative lightweight model
ollama pull llama3.2:3b

# Start Ollama in the background
ollama serve

# Verify it's running
curl http://localhost:11434

# Create new project
dotnet new console -n AgentWithOllama
cd AgentWithOllama

# Add required NuGet packages
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package OllamaSharp
dotnet add package Microsoft.Extensions.AI

# Run the application
dotnet run

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

// Configuration - Ollama endpoint and model selection
var endpoint = "http://localhost:11434";  // Default Ollama endpoint
var modelName = "qwen3:8b";              // Model to use for AI responses

// Agent personality configuration
const string JokerName = "Joker";
const string JokerInstructions = "You are good at telling jokes.";

/// <summary>
/// Example function tool that the agent can call to get weather information.
/// The Description attributes provide metadata for the AI to understand when and how to use this function.
/// </summary>
[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

// Initialize Ollama client and create the AI agent
// The ChatClientAgent wraps the Ollama client with Microsoft Agent Framework capabilities
using OllamaApiClient chatClient = new(new Uri(endpoint), modelName);
AIAgent agent = new ChatClientAgent(
    chatClient,
    JokerInstructions,
    JokerName,
    tools: [AIFunctionFactory.Create(GetWeather)]  // Register our weather function
);

/// <summary>
/// Custom middleware for intercepting and logging function calls.
/// This demonstrates how to add cross-cutting concerns like logging, monitoring, or validation.
/// </summary>
async ValueTask<object?> FunctionCallMiddleware(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    // Pre-invocation logging
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine($"🔧 Function Name: {context!.Function.Name} - Middleware Pre-Invoke");
    Console.ResetColor();

    // Execute the function and capture timing
    var startTime = DateTime.UtcNow;
    var result = await next(context, cancellationToken);
    var duration = DateTime.UtcNow - startTime;

    // Post-invocation logging with timing information
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine($"🔧 Function Name: {context!.Function.Name} - Middleware Post-Invoke (Duration: {duration.TotalMilliseconds}ms)");
    Console.ResetColor();

    return result;
}

// Create an agent with middleware pipeline
// The builder pattern allows for easy composition of middleware components
var agentWithMiddleware = agent.AsBuilder()
    .Use(FunctionCallMiddleware)  // Add our custom middleware
    .Build();

/// <summary>
/// Enhanced helper method for displaying streaming responses with visual formatting.
/// This method provides a better user experience by showing real-time character-by-character streaming
/// with colored output and progress indicators.
/// </summary>
async Task DisplayStreamingResponse(string prompt, AgentThread? thread = null, AIAgent? agentToUse = null)
{
    var agentInstance = agentToUse ?? agent;

    Console.ForegroundColor = ConsoleColor.Cyan;
    Console.WriteLine($"🤖 {JokerName} is thinking...");
    Console.ResetColor();

    var isFirstUpdate = true;

    var stream = thread != null
        ? agentInstance.RunStreamingAsync(prompt, thread)
        : agentInstance.RunStreamingAsync(prompt);

    await foreach (var update in stream)
    {
        if (isFirstUpdate)
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.Write($"{JokerName}: ");
            Console.ResetColor();
            isFirstUpdate = false;
        }

        Console.Write(update);
        await Task.Delay(10);
    }

    Console.WriteLine();
    Console.ForegroundColor = ConsoleColor.DarkGray;
    Console.WriteLine("✨ Response complete!");
    Console.ResetColor();
}

// ============================================================================
// EXAMPLE 1: Non-streaming multi-turn conversation
// Demonstrates context preservation across multiple conversation turns
// ============================================================================
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("🎭 MULTI-TURN CONVERSATION (Non-Streaming)");
Console.WriteLine("=" + new string('=', 60));
Console.ResetColor();

// Create a new conversation thread for context preservation
AgentThread thread1 = agent.GetNewThread();

// First interaction - agent responds with a joke
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", thread1));

// Second interaction - agent remembers the previous joke and modifies it
Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread1));

// ============================================================================
// EXAMPLE 2: Streaming multi-turn conversation
// Same as Example 1 but with real-time character-by-character streaming
// ============================================================================
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("\n🎭 MULTI-TURN CONVERSATION (Streaming)");
Console.WriteLine("=" + new string('=', 60));
Console.ResetColor();

// Create a new conversation thread for streaming context preservation
AgentThread thread2 = agent.GetNewThread();

// First streaming interaction
await DisplayStreamingResponse("Tell me a joke about a pirate.", thread2);

// Second streaming interaction - agent maintains context from previous turn
await DisplayStreamingResponse("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", thread2);

// ============================================================================
// EXAMPLE 3: Function tools interaction with streaming
// Demonstrates how agents can call custom functions to extend their capabilities
// ============================================================================
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("\n🔧 FUNCTION TOOLS INTERACTION (Streaming)");
Console.WriteLine("=" + new string('=', 60));
Console.ResetColor();

// This will trigger the GetWeather function tool
await DisplayStreamingResponse("What is the weather like in Amsterdam?");

Console.ForegroundColor = ConsoleColor.DarkGray;
Console.WriteLine("\n" + "=" + new string('=', 60));
Console.WriteLine("🎉 All conversations completed!");
Console.ResetColor();

// ============================================================================
// EXAMPLE 4: Agent with middleware pipeline
// Demonstrates custom middleware for function call interception and logging
// ============================================================================
Console.ForegroundColor = ConsoleColor.Magenta;
Console.WriteLine("\n🔧 AGENT WITH MIDDLEWARE (Streaming)");
Console.WriteLine("=" + new string('=', 60));
Console.ResetColor();

// Use the agent with middleware - this will show function call logging
await DisplayStreamingResponse("What is the weather like in Amsterdam?", agentToUse: agentWithMiddleware);

Console.ForegroundColor = ConsoleColor.DarkGray;
Console.WriteLine("\n" + "=" + new string('=', 60));
Console.WriteLine("🎉 All examples completed successfully!");
Console.ResetColor();

const string JokerName = "Joker";
const string JokerInstructions = "You are good at telling jokes.";
AIAgent agent = new ChatClientAgent(
    chatClient,
    JokerInstructions,
    JokerName,
    tools: [AIFunctionFactory.Create(GetWeather)]
);

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
    => $"The weather in {location} is cloudy with a high of 15°C.";

async ValueTask<object?> FunctionCallMiddleware(
    AIAgent agent,
    FunctionInvocationContext context,
    Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
    CancellationToken cancellationToken)
{
    // Pre-processing: Logging, validation, rate limiting
    Console.WriteLine($"🔧 Function Name: {context!.Function.Name} - Pre-Invoke");

    var result = await next(context, cancellationToken);

    // Post-processing: Logging, monitoring, cleanup
    Console.WriteLine($"🔧 Function Name: {context!.Function.Name} - Post-Invoke");

    return result;
}

async Task DisplayStreamingResponse(string prompt, AgentThread? thread = null, AIAgent? agentToUse = null)
{
    var agentInstance = agentToUse ?? agent;

    // Visual feedback for user
    Console.WriteLine($"🤖 {JokerName} is thinking...");

    // Stream processing with context awareness
    var stream = thread != null
        ? agentInstance.RunStreamingAsync(prompt, thread)  // Multi-turn
        : agentInstance.RunStreamingAsync(prompt);         // Single turn

    // Character-by-character streaming with visual effects
    await foreach (var update in stream)
    {
        Console.Write(update);
        await Task.Delay(10);  // Smooth streaming effect
    }
}