svnscha - csharp

AI Agents in .NET: Beyond DevUI - LibreChat Integration

2026-01-04T00:00:00+00:00

Welcome back to the AI Agents in .NET series. In the introduction, I built a basic conversational agent. In Part 1, I added database persistence, embeddings, and semantic search capabilities.

Today I'm breaking free from the built-in DevUI. Time to escape the developer dungeon.

Don't get me wrong - DevUI is fantastic for development and debugging.

This post connects those agents to LibreChat through OpenAI-compatible endpoints.

The first version failed when a tool-calling agent was used through a downstream client. The solution was a reusable middleware pattern called ToolCallFilterAgent, which I explain below.

The Problem with DevUI

DevUI served me well. It let me test agents, inspect tool calls, and debug issues. But it has limitations:

Single-purpose: It's a development tool, not a production interface
No multi-user support: One conversation at a time
Limited customization: You get what you get

For real-world use, I need something more flexible. And rather than building my own chat UI (been there, done that in early 2025, don't want to repeat), let's leverage existing open-source solutions.

Why LibreChat?

I mentioned LibreChat in my DGX Spark post, and I really enjoy it. Like, really like it.

It's:

OpenAI API compatible: Speaks the same language as ChatGPT
Self-hosted: Your data stays yours (take that, cloud overlords)
Feature-rich: File uploads, conversations, presets, the whole shebang
Beautiful: Actually looks like something you'd want to use - not like a developer accidentally vomited JSON onto a webpage

The key insight? LibreChat doesn't care what's behind the API. It just needs something that speaks OpenAI's protocol. And guess what the Microsoft Agent Framework already supports?

The Plan

Here's what I'm building:

%%{init: {"theme": "dark"}}%%
flowchart LR
    LC[LibreChat] -->|OpenAI API| K[Knowledge API]
    K -->|Agent Framework| A[Agents]
    A --> KA[Knowledge]
    A --> KSA[KnowledgeSearch]
    A --> KTA[KnowledgeTitle]
    KSA -->|Vector Search| PG[(PostgreSQL)]

LibreChat talks to our Knowledge API using the standard OpenAI chat completions format. Our API routes requests to our agents based on the model parameter. From LibreChat's perspective, it's just another OpenAI-compatible endpoint with multiple models to choose from.

Removing DevUI, Embracing Swagger

First things first - I'm removing the DevUI dependency and redirecting to Swagger for API exploration. DevUI is great for debugging, but for an API-first approach, Swagger makes more sense. Plus, Swagger has that nice "I'm a real API" energy.

The home page now redirects to Swagger:

app.MapGet("/", () => Results.Redirect("/swagger"));

Clean and simple. The API is now focused on being a backend service. Goodbye, training wheels.

Exposing OpenAI-Compatible Endpoints

The Agent Framework provides a beautiful MapOpenAIChatCompletions method that exposes agents as OpenAI-compatible endpoints. Each agent gets its own endpoint path. It's almost too easy (foreshadowing...).

I collect agent builders during registration and map them after building the app:

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ... OpenAI client setup ...

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
});

var app = builder.Build();

// ... middleware setup ...

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

Now each agent has its own endpoint:

/Knowledge/v1/chat/completions
/KnowledgeSearch/v1/chat/completions

Pretty slick, right?

Setting Up LibreChat

Before I go further, let me get LibreChat running so I can test this integration. If you don't have LibreChat running yet, here's the quick setup. (If you do, feel free to skip ahead and judge my configuration choices.)

Docker Compose

mkdir -p ~/librechat
cd ~/librechat
git clone https://github.com/danny-avila/LibreChat.git .
cp .env.example .env

The LibreChat Configuration

Create librechat.yaml and point LibreChat at the API:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch"]
        fetch: false

      titleConvo: false
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Docker Compose Override

Create docker-compose.override.yml to mount the config:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
    extra_hosts:
      - "host.docker.internal:host-gateway"

The extra_hosts line is crucial - it lets containers reach the host machine where the Knowledge API runs.

Fire It Up

docker compose up -d

Navigate to http://localhost:3080, create an account (it's local, don't worry), and you should see "Agent Framework" in the endpoint list.

But wait - if you select "Knowledge" and send a message, LibreChat hits /v1/chat/completions with "model": "Knowledge". My per-agent endpoints live at /Knowledge/v1/chat/completions instead. Houston, we have a routing problem.

The Model Routing Middleware

LibreChat (and most OpenAI clients) expect a single endpoint at /v1/chat/completions where the model parameter determines the underlying model but in this scenario it should determines routing:

{
  "model": "Knowledge",
  "messages": [{"role": "user", "content": "What's on your mind?"}]
}

I need middleware that reads the model from the request body and rewrites the path to the agent-specific endpoint. Nothing fancy, just some good old path mangling:

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException)
            {
            }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

The key points:

Enable buffering: I need to read the body to extract model, then reset it for the actual handler
Path rewriting: Transform /v1/chat/completions → /{model}/v1/chat/completions
Error handling: Return a proper OpenAI-style error if model is missing

Now when LibreChat sends a request, it gets routed to the right agent automatically. Back to LibreChat - select "Knowledge" from the dropdown, send a message, and... it works! Streaming responses, proper formatting, everything.

At this point, I thought I was done. Celebrated with a coffee. Time to test KnowledgeSearch...

The Tool Call Disaster (And How I Fixed It)

I switched to the KnowledgeSearch model in LibreChat, asked it to search for something, and... nothing. The request just hung. Then cancelled. No error message. No response. Just the cold, judgmental silence of broken software.

I dug through LibreChat's source code, traced the request flow, added logging everywhere. Console.WriteLine debugging like it's 2005.

Note: We should get to Observability very soon...

The Problem

My KnowledgeSearch agent uses tools - specifically the SearchConversationHistory function. When the agent executes a tool, the response stream includes FunctionCallContent and FunctionResultContent alongside the text. This is how the Agent Framework communicates "I'm calling a tool" and "here's what the tool returned."

LibreChat receives the stream and interprets the function call as something it should execute. That fails because the function exists in the backend rather than in LibreChat, so LibreChat cancels the request.

[Our Agent] → "I'll search for that" → FunctionCallContent{SearchConversationHistory}
[Our Agent] → [executes tool internally]
[Our Agent] → FunctionResultContent{results...}
[Our Agent] → "Based on the search, here's what I found..."
          ↓
[LibreChat] → Sees FunctionCallContent → "I need to call this function!"
[LibreChat] → Can't find function → Cancels request
          ↓
[User] → "Why isn't anything happening?" 😤

The frustrating part? You can't disable this behavior in LibreChat. It's doing the right thing for its use case - if it sends a function call to an upstream model, it expects to handle the response. But I'm the upstream model, and I've already handled my own tool calls. We're both right, and that's the most annoying kind of bug.

The Solution

Don't send tool call content downstream. Filter it out before it leaves the API. If LibreChat never sees the tool calls, it can't get confused by them. taps forehead

Meet ToolCallFilterAgent - a delegating agent that wraps any agent and strips FunctionCallContent and FunctionResultContent from responses. It's like a bouncer for your API responses:

/// <summary>
/// A delegating agent that filters out tool call content from responses.
/// This prevents downstream consumers from seeing FunctionCallContent and FunctionResultContent
/// that they cannot execute.
/// </summary>
public sealed class ToolCallFilterAgent : DelegatingAIAgent
{
    public ToolCallFilterAgent(AIAgent innerAgent) : base(innerAgent) { }

    public override async Task<AgentRunResponse> RunAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        CancellationToken cancellationToken)
    {
        var response = await InnerAgent.RunAsync(messages, thread, options, cancellationToken);
        response.Messages = FilterToolCalls(response.Messages);
        return response;
    }

    public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var update in InnerAgent.RunStreamingAsync(messages, thread, options, cancellationToken))
        {
            yield return FilterToolCalls(update);
        }
    }

    private static IList<ChatMessage> FilterToolCalls(IEnumerable<ChatMessage> messages) =>
        messages.Select(m => new ChatMessage(m.Role,
            m.Contents.Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList()
        )).ToList();

    private static AgentRunResponseUpdate FilterToolCalls(AgentRunResponseUpdate update) =>
        new(update.Role, update.Contents
            .Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList());
}

Now in the AgentFactory, I wrap KnowledgeSearchAgent:

public static AIAgent CreateKnowledgeSearchAgent(IChatClient chatClient, IServiceProvider services, string key)
{
    var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

    var agent = chatClient.CreateAIAgent(new ChatClientAgentOptions
    {
        Id = key,
        Name = key,
        ChatOptions = new ChatOptions
        {
            ConversationId = "global",
            Instructions = KnowledgeSearchSystemPrompt,
            Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync, "SearchConversationHistory")],
            ToolMode = ChatToolMode.Auto
        }
    });

    // Wrap with filter to prevent downstream consumers from seeing tool calls they can't execute
    return new ToolCallFilterAgent(agent);
}

The agent still uses tools internally, but clients only see the final text response. Clean and transparent. What happens in the backend stays in the backend.

Back to LibreChat - KnowledgeSearch now works! The agent searches, finds results, and responds - all without LibreChat ever knowing tools were involved. It's like magic, except it's just careful filtering.

Title Generation with KnowledgeTitleAgent

LibreChat has a feature called titleConvo - it automatically generates titles for conversations using the AI. But my main agents have tools and complex system prompts that are overkill for simple title generation. It's like using a flamethrower to light a candle.

The solution: a dedicated title agent. It's intentionally simple - no tools, no embeddings, just a focused system prompt:

/// <summary>
/// Simple agent for generating conversation titles.
/// No tools, no embeddings - just a basic helpful assistant.
/// Designed for use with LibreChat's title generation feature.
/// </summary>
public static class KnowledgeTitleAgent
{
    private const string TitleSystemPrompt = @"You are a helpful assistant that generates concise, descriptive titles for conversations.
When given conversation content, create a brief title (3-7 words) that captures the main topic or purpose.
Be specific and informative. Avoid generic titles like 'Chat' or 'Conversation'.";

    public static ChatClientAgent Create(IChatClient chatClient, IServiceProvider services, string key)
    {
        return chatClient.CreateAIAgent(new ChatClientAgentOptions
        {
            Id = key,
            Name = key,
            ChatOptions = new ChatOptions
            {
                ConversationId = "global",
                Instructions = TitleSystemPrompt,
            }
        });
    }
}

agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
    AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));

Now update librechat.yaml to use the title agent:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch", "KnowledgeTitle"]
        fetch: false

      titleConvo: true
      titleModel: "KnowledgeTitle"
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Now LibreChat uses KnowledgeTitle specifically for generating conversation titles, while Knowledge and KnowledgeSearch handle the actual conversations.

The Complete Program.cs

Here's what Program.cs looks like after all these changes:

using System.ClientModel;
using Knowledge.Services;
using Knowledge.Shared.Agents;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

var builder = WebApplication.CreateBuilder(args);

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    if (string.IsNullOrWhiteSpace(settings.ApiKey))
    {
        logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets or environment.");
    }

    var options = new OpenAIClientOptions();
    if (!string.IsNullOrEmpty(settings.ApiEndpoint))
    {
        options.Endpoint = new Uri(settings.ApiEndpoint);
    }

    var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);
    var chatClient = client.GetChatClient("gpt-4.1").AsIChatClient();

    // Configure embedding service
    var embeddingClient = client.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();
    builder.Services.AddEmbeddingService(embeddingClient);

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
        AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));
});

// Register background service for embedding processing
builder.Services.AddHostedService<EmbeddingBackgroundService>();

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

var app = builder.Build();

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException) { }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

app.UseRouting();

app.ConfigureKnowledgePipeline();

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

app.MapGet("/", () => Results.Redirect("/swagger"));

app.LogStartupComplete();

app.Run();

That's it. No CORS configuration needed (LibreChat makes server-side requests). No custom request/response models. No manual streaming code. The framework does the heavy lifting - I just wire it up. Sometimes the best code is the code you don't have to write.

The key insights:

Each agent gets its own endpoint via MapOpenAIChatCompletions
Inline middleware handles routing from /v1/chat/completions based on model
ToolCallFilterAgent hides internal tool execution from downstream clients
KnowledgeTitleAgent handles title generation without tool complexity

LibreChat Test

Open LibreChat, select "Agent Framework" as the endpoint, choose a model from the dropdown (Knowledge, KnowledgeSearch, or KnowledgeTitle), and start chatting. You should see:

Streaming responses (that satisfying typing effect)
Tool calls working transparently (KnowledgeSearch uses tools, but you only see the results)
Automatic title generation (thanks to KnowledgeTitle)

Architecture Overview

Let me step back and look at what I've built (and maybe pat myself on the back a little):

%%{init: {"theme": "dark"}}%%
flowchart TB
    subgraph Clients
        LC[LibreChat]
        API[Direct API Calls]
    end

    subgraph "Knowledge API"
        MR[Model Router Middleware]
        E1["/Knowledge/v1/chat/completions"]
        E2["/KnowledgeSearch/v1/chat/completions"]
        E3["/KnowledgeTitle/v1/chat/completions"]
    end

    subgraph Agents
        KA[Knowledge Agent]
        KSA[KnowledgeSearch Agent]
        KTA[KnowledgeTitle Agent]
        TCF[ToolCallFilterAgent]
    end

    subgraph Storage
        PG[(PostgreSQL)]
    end

    LC -->|"/v1/chat/completions"| MR
    API --> MR
    MR -->|"model: Knowledge"| E1
    MR -->|"model: KnowledgeSearch"| E2
    MR -->|"model: KnowledgeTitle"| E3
    E1 --> KA
    E2 --> TCF
    TCF --> KSA
    E3 --> KTA
    KSA -->|Vector Search| PG

The flow is clean:

Request comes in to /v1/chat/completions with "model": "KnowledgeSearch"
Middleware rewrites path to /KnowledgeSearch/v1/chat/completions
Framework routes to the agent, which is wrapped in ToolCallFilterAgent
Agent executes tools internally, filter strips tool content from response
Client sees clean text output

Multiple clients, multiple agents, one simple routing pattern. It's almost... elegant?

Swagger is still available at /swagger for API exploration and testing.

Summary

I've taken the agents from a development-only DevUI to something that can serve real users through a proper chat interface. And I did it with surprisingly little code - plus one hard-won debugging lesson that I'm still a bit salty about.

The main points are:

MapOpenAIChatCompletions does the heavy lifting - one line per agent, full OpenAI compatibility
Each agent gets its own endpoint - clean separation, easy to test directly
Simple inline middleware handles routing - LibreChat sends to /v1/chat/completions, I rewrite to /{model}/v1/chat/completions
Tool-calling agents need filtering - the ToolCallFilterAgent pattern is essential when exposing agents to downstream clients that don't understand your internal tool calls.
Dedicated agents for specific tasks - KnowledgeTitleAgent for titles, KnowledgeSearch for search, Knowledge for general chat

Next Steps

I've got a solid foundation now - persistence, embeddings, semantic search, a proper UI, and automatic title generation. But there's more to explore:

Observability: OpenTelemetry, Jaeger, understanding what's happening at scale
Agent Loop: Exploring the magic behind automated AI Agents
Authentication: Proper API key validation for production deployments (because "meh, whatever" isn't a security strategy)

But first, I'm letting this settle. Play with LibreChat, see how your agents perform with real conversations, and notice what's missing. The best features come from actual use - not from staring at code and imagining what users might want.

See you in the next post. 🚀

The companion repository has been updated with the part/02-connect-librechat branch containing all the code from this post. Check it out on GitHub.

AI Agents in .NET: Building Agentic RAG

2025-12-28T00:00:00+00:00

Welcome back. In the first post, we set up a basic conversational agent. It worked. It responded. It was... fine.

But let's be honest - an agent that can only chat is just a very expensive echo chamber. Today we're giving our agent actual knowledge. It will remember past conversations, search through its own message history, and - most importantly - decide when to use that knowledge.

This is going to be a long one. Grab coffee. Let's build the next piece of the puzzle.

What We're Building

By the end of this post, we'll have:

A PostgreSQL database for persisting messages and embeddings
A second agent (KnowledgeSearch) that searches conversation history
Tool calling so our main agent can invoke KnowledgeSearch when needed
Autonomous decision-making about when to retrieve information vs. just respond

That last point is the key difference between classic RAG and agentic RAG. We're not blindly stuffing context into every prompt. The agent chooses when retrieval helps.

A Quick Word on RAG

RAG - Retrieval-Augmented Generation - has been the go-to pattern for giving LLMs access to external knowledge. The classic approach:

User asks a question
System searches a knowledge base
Retrieved documents get stuffed into the prompt
LLM generates a response using that context

It works. But it's also... dumb? Every query triggers retrieval, whether needed or not. Ask "What's the capital of France?" and you're still embedding the question, searching vectors, retrieving documents. Wasteful.

Agentic RAG flips this. The agent has tools for retrieval and decides when to use them. Simple questions get simple answers. Complex questions trigger the agent to go digging. Much more elegant.

Heads up: There's a whole universe of RAG variations out there - hybrid RAG combining vector search with full-text search (FTS), reranking strategies, query expansion, and more. If you go down the rabbit hole, you'll find dozens of ways to improve retrieval quality. We're intentionally skipping all of that here to focus on the agentic part - how an agent decides when and how to retrieve. Once you grok that, feel free to explore the retrieval optimizations.

Enough theory. Let's write some code.

Database Foundation

Our agent needs a place to store things - messages, embeddings, knowledge. PostgreSQL with pgvector gives us a solid foundation.

The Schema

We're keeping it simple: messages for chat history, embeddings for semantic search.

%%{init: {
  "theme": "dark",
  "themeVariables": {
    "fontFamily": "Jetbrains Mono",
  },
  "themeCSS": [
    ".er.relationshipLine { stroke: #858585; }",
    ".er.relationshipLabel { fill: #bbbbbb; }",
    ".er.relationshipLabelBox { fill: transparent; }",
    ".er.entityBox { fill: #252526; stroke: #303031; }",
    "[id^=entity-messages] .er.entityBox { fill: #1e3a5f; stroke: #5abae0; }",
    "[id^=entity-embeddings] .er.entityBox { fill: #451a03; stroke: #f59e0b; }"
    ]
}}%%
erDiagram
    messages ||--o| embeddings : "has"
    messages {
        uuid id PK
        uuid conversation_id
        uuid embedding_id FK
        varchar role
        varchar author_name
        text content
        bigint sequence_number
        timestamp created_at
    }
    embeddings {
        uuid id PK
        varchar source_type
        uuid source_id
        text content
        vector vector_1536
        timestamp created_at
    }

A few notes:

conversation_id: Groups messages by conversation/session - indexed for fast retrieval
role: Maps to ChatRole.Value from Microsoft.Extensions.AI (user, assistant, system, tool)
sequence_number: Auto-assigned by a database trigger - ensures correct ordering
source_type: Polymorphic pattern - can reference Message or any future entity (e.g., DocumentChunk)
vector_1536: 1536-dimension embedding from OpenAI's text-embedding-3-small

The DbContext

Entity Framework Core handles the mapping. The key thing we need is pgvector support:

// KnowledgeDbContext.cs
modelBuilder.HasPostgresExtension("vector");

This single line enables the vector data type in PostgreSQL. Without it, EF Core won't know what to do with our embedding vectors.

For the Embedding entity, we tell EF Core the exact column type:

// KnowledgeDbContext.cs
entity.Property(e => e.Vector)
      .HasColumnType("vector(1536)");

The rest is standard EF Core configuration - indexes on ConversationId (our primary query pattern), composite index on ConversationId + SequenceNumber for ordered retrieval, and SourceType + SourceId on embeddings for fast lookups.

Don't skip the indexes. Without them, you're doing full table scans.

Wiring It Up

Database registration goes into our extension method. The important choice: AddDbContextFactory instead of AddDbContext.

// ServiceCollectionExtensions.cs
services.AddDbContextFactory<KnowledgeDbContext>(options =>
{
    options.UseNpgsql(connectionString, npgsqlOptions =>
    {
        npgsqlOptions.UseVector();  // Enable pgvector
    });
});

Why the factory? Our message store and agents live outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context.

Migration Time

EF Core migrations version our schema:

cd src/Knowledge

# Create the migration
dotnet ef migrations add InitialCreate --project ../Knowledge.Shared --output-dir Migrations

# Apply it
dotnet ef database update --project ../Knowledge.Shared

We also add a trigger migration for auto-incrementing sequence numbers:

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE OR REPLACE FUNCTION assign_message_sequence_number()
    RETURNS TRIGGER AS $$
    BEGIN
        SELECT COALESCE(MAX(sequence_number), 0) + 1
        INTO NEW.sequence_number
        FROM messages
        WHERE conversation_id = NEW.conversation_id;
        RETURN NEW;
    END;
    $$ LANGUAGE plpgsql;
    """);

migrationBuilder.Sql("""
    CREATE TRIGGER trg_messages_sequence_number
    BEFORE INSERT ON messages
    FOR EACH ROW
    WHEN (NEW.sequence_number = 0 OR NEW.sequence_number IS NULL)
    EXECUTE FUNCTION assign_message_sequence_number();
    """);

This assigns sequence numbers per conversation. The WHERE conversation_id = NEW.conversation_id ensures each conversation has its own sequence. For high-concurrency production use, consider using a proper sequence/identity instead of MAX().

The Conversation Workaround

Before we get to the message store, there's a wrinkle. The framework's DevUI doesn't pass AgentThread information to custom ChatMessageStore implementations. No thread ID means no way to group messages by conversation using the framework's intended abstractions.

We could give up on persistence entirely. Or we could be pragmatic.

The workaround is dead simple: generate a conversation ID once at startup.

// ConversationWorkaround.cs
public static class ConversationWorkaround
{
    public static Guid CurrentConversationId { get; } = Guid.NewGuid();
}

One GUID, initialized once when the application starts, shared for the lifetime of the process. Every message gets tagged with that ID. Restart the app? New ID, new conversation.

We add a corresponding ConversationId column to our Message entity - just a Guid property that gets persisted alongside the role, content, and sequence number.

The Message Store

With our workaround in place, the ChatMessageStore implementation becomes straightforward. The framework calls AddMessagesAsync after each exchange, and GetMessagesAsync when loading history.

The key insight: we use IDbContextFactory<KnowledgeDbContext> instead of injecting a DbContext directly. Why? The store lives outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context - no connection leaks, no stale entity tracking.

When adding messages, we tag each one with ConversationWorkaround.CurrentConversationId:

// KnowledgeChatMessageStore.cs
var message = new Message
{
    Id = Guid.TryParse(chatMessage.MessageId, out var id) ? id : Guid.NewGuid(),
    ConversationId = ConversationWorkaround.CurrentConversationId,
    Role = chatMessage.Role.Value,
    AuthorName = chatMessage.AuthorName,
    Content = chatMessage.Text ?? string.Empty,
    SequenceNumber = 0,  // Trigger auto-assigns
    CreatedAt = chatMessage.CreatedAt?.UtcDateTime ?? DateTime.UtcNow
};

When retrieving, we filter by that same ID:

// KnowledgeChatMessageStore.cs
var messages = await dbContext.Messages
    .Where(m => m.ConversationId == conversationId)
    .OrderBy(m => m.SequenceNumber)
    .ToListAsync(cancellationToken);

This keeps each app instance isolated. Messages from yesterday's debugging session don't pollute today's conversation.

Why This Workaround?

The ideal solution would use the framework's AgentThread abstraction - each thread gets its own conversation, the UI manages thread creation, everything Just Works™. But DevUI doesn't pass thread information to custom stores yet.

Good news: our ChatMessageStore does get called. Messages persist. The agent loads context on startup. The workaround gives us:

Per-instance conversations: Each app restart starts fresh
Persistent context: Within a session, the agent remembers everything
Future-proof schema: When DevUI supports threads, we swap ConversationWorkaround.CurrentConversationId for the real thread ID

We've opened issue #3000 to track proper thread support. For now, this gets the job done.

Embeddings

Before building the KnowledgeSearch agent, it helps to understand embeddings, which are the basis of semantic search. If you already know how they work, you can skip this section.

This section covers the theory, but we're not just hand-waving. As we go, we'll be building toward our second agent that can search through conversation history and return relevant context.

The Big Reveal

An embedding is just a list of numbers. That's it. That's the tweet.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> B["[0.021, -0.034, 0.089, 0.012, ..., -0.045]"]
    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#252526,stroke:#303031,color:#bbbbbb

When you feed text into an embedding model, it spits out a vector - 1536 floating-point numbers for OpenAI's text-embedding-3-small. These numbers encode the meaning of the text. Not the letters, not the spelling - the actual semantic content.

The magic? Similar meanings produce similar numbers.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> V1["[0.021, -0.034, 0.089, ...]"]
    B["🐈 kitten"] --> V2["[0.019, -0.031, 0.092, ...]"]
    C["🗳️ democracy"] --> V3["[-0.067, 0.142, -0.023, ...]"]

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style C fill:#451a03,stroke:#f59e0b,color:#fff
    style V1 fill:#252526,stroke:#303031,color:#bbbbbb
    style V2 fill:#252526,stroke:#303031,color:#bbbbbb
    style V3 fill:#252526,stroke:#303031,color:#bbbbbb

See how "cat" and "kitten" have similar-ish numbers, while "democracy" is completely different? That's semantic similarity, encoded as math.

The "magic" demystified: This is the whole secret behind AI "understanding" - it's just numbers. There's no mystical intelligence, no consciousness pondering the nature of cats. Just insanely clever linear algebra operating in 1536-dimensional space. Once you see it, you can't unsee it. Beautiful, really.

Where Things Live in Vector Space

Imagine plotting these vectors in space. The real vectors have 1,536 dimensions, but a three-dimensional sketch is enough to show the idea of clusters and similarity scores.

%%{init: {
  "theme": "dark"
}}%%
flowchart LR
    subgraph Pets[" "]
        A[cat]
        B[kitten]
    end
    subgraph Civics[" "]
        D[democracy]
        E[parliament]
    end

    A ---|"0.94"| B
    A -.-|"0.31"| D
    D ---|"0.89"| E

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style D fill:#451a03,stroke:#f59e0b,color:#fff
    style E fill:#451a03,stroke:#f59e0b,color:#fff

Similar concepts cluster together. Words about pets huddle in one corner, political terms in another. In the real 1536-dimensional space, these relationships become incredibly nuanced - the model captures categories, analogies, context, even vibes. The scores on the edges are cosine similarities: higher numbers mean those meanings live closer together.

This is why semantic search works. Ask "how do I create an agent?" and the system finds documents about "instantiating agents" and "agent initialization" - different words, same neighborhood in vector space.

How "Close" Are Two Vectors?

We use cosine similarity - basically measuring the angle between two arrows in space.

Similarity = 1: Identical meaning (same direction)
Similarity = 0: Unrelated (perpendicular)
Similarity = -1: Opposite meaning (opposite direction)

You don't need to understand the math. Just know: higher number = more similar meaning. When we search our knowledge base, we're finding the vectors that point in roughly the same direction as the query.

%%{init: {"theme": "dark"}}%%
flowchart LR
    subgraph Query
        Q["How do I build an agent?"]
    end
    subgraph Results["Top Matches (by similarity)"]
        R1["0.94 - Creating your first agent"]
        R2["0.91 - Agent initialization guide"]
        R3["0.87 - Setting up agent tools"]
        R4["0.34 - PostgreSQL connection strings"]
    end
    Q --> R1
    Q --> R2
    Q --> R3
    Q -.-> R4

    style Q fill:#1e3a5f,stroke:#5abae0,color:#fff
    style R1 fill:#064e3b,stroke:#10b981,color:#fff
    style R2 fill:#064e3b,stroke:#10b981,color:#fff
    style R3 fill:#064e3b,stroke:#10b981,color:#fff
    style R4 fill:#451a03,stroke:#f59e0b,color:#fff

The PostgreSQL doc isn't wrong, it's just pointing in a completely different direction. Low similarity score, doesn't make the cut.

The Model We'll Use

OpenAI offers several embedding models:

Model	Dimensions	Use Case
`text-embedding-3-small`	1536	Most applications
`text-embedding-3-large`	3072	When you need more context
`text-embedding-ada-002`	1536	Legacy

We'll use text-embedding-3-small. It's cheap, fast, and good enough for most use cases. The larger model is more accurate but costs more - classic tradeoff. Start small, upgrade if you need to.

Now the question becomes: where do we store 1536 floating-point numbers per piece of text, and how do we search them efficiently?

pgvector Setup

PostgreSQL with pgvector gives us a proper vector database without leaving our existing stack. No separate Pinecone or Weaviate instance to manage.

Enabling the Extension

First, we need pgvector enabled in our database. Connect to PostgreSQL and run:

CREATE EXTENSION IF NOT EXISTS vector;

This installs the vector data type and operators. You only need to do this once per database. If you're using my dev container template, this is already handled in the database initialization scripts.

Verify it worked:

SELECT * FROM pg_extension WHERE extname = 'vector';
-- Should return one row showing the vector extension

The Embedding Entity

We want a generic approach - store embeddings for any content type (messages, documents, whatever). The key property:

// Embedding.cs
public Vector Vector { get; set; } = null!;  // pgvector's native type

We use pgvector's native Vector type instead of float[]. The Pgvector.EntityFrameworkCore package handles the mapping between C# and PostgreSQL.

The entity also tracks what was embedded via SourceType + SourceId - a poor man's polymorphic association. Not elegant, but flexible. We can add new source types (documents, code snippets) without schema changes.

We also store the original Content alongside the vector. Why? When we retrieve matches, we need the actual text to show. And if embeddings get stale, we can re-generate from the stored content.

EF Core Configuration

We already covered the key line in Section 1 - HasColumnType("vector(1536)"). The dimension must match your embedding model. OpenAI's text-embedding-3-small produces 1536 dimensions, so that's what we use.

Indexing for Speed

Without an index, similarity search scans every row - fine for 1,000 embeddings, catastrophic for 1,000,000. HNSW (Hierarchical Navigable Small World) gives us logarithmic search time.

We create the index via a migration (we include this in our AddCustomTriggers migration):

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE INDEX IF NOT EXISTS ix_embeddings_vector_cosine
    ON embeddings
    USING hnsw (vector vector_cosine_ops);
    """);

Breaking this down:

hnsw: The index algorithm - builds a graph structure for fast nearest neighbor search
vector_cosine_ops: Use cosine distance (1 - cosine similarity) as the metric
Creation time: ~1-2 seconds per 10,000 vectors on my laptop

The tradeoff: HNSW uses more memory and takes longer to build, but queries are dramatically faster. For a RAG system, this is always worth it.

Embedding Messages

Time to give our agent some actual knowledge. Instead of indexing external documentation, we're embedding our own conversation history - every message becomes searchable.

Why Messages?

We need something to embed, and chat messages are already there - no external datasets, no document ingestion pipelines, no extra setup. It's demo content that generates itself as you use the agent.

Important distinction: This is not the same as Microsoft.Agents.AI.Memory.ChatHistoryMemoryProvider, which provides memorable context during agent invocation (think: short-term working memory for the current conversation). What we're building is long-term semantic search over historical content. Different problems, different solutions.

The Chunking Problem (Or Not)

For large documents, chunking is essential - split into smaller pieces, embed each one. But messages are already bite-sized. A typical chat message is well under our embedding model's context limit.

We'll embed messages as-is. No chunking needed. If you later want to add document indexing (PDFs, markdown files, whatever), you'd apply chunking:

Fixed size: Every chunk is N tokens. Simple but might split mid-sentence.
Paragraph-based: Split on natural boundaries. Preserves context but uneven sizes.
Semantic: Use the LLM to identify logical sections. Expensive but smart.

For documents, fixed size with overlap (500 tokens, 50 token overlap) is the standard. But for messages, we skip this entirely.

The Embedding Service

We wrap IEmbeddingGenerator<string, Embedding<float>> from Microsoft.Extensions.AI in a simple service. The key conversion:

// EmbeddingService.cs
var result = await _embeddingGenerator.GenerateAsync(text, cancellationToken);
return new Vector(result.Vector.ToArray());

Text goes in, pgvector Vector comes out. The service handles the conversion from the AI library's float array to pgvector's native type. Nothing fancy - just a thin wrapper to keep the embedding generation consistent across the app.

Background Processing

We could embed messages synchronously when they're saved, but that blocks the chat response. Instead, a background service picks up unprocessed messages every 10 seconds.

The trick is using Message.EmbeddingId as both a foreign key and a processing flag:

// EmbeddingBackgroundService.cs
var pendingMessages = await dbContext.Messages
    .Where(m => m.EmbeddingId == null)  // Not yet embedded
    .Where(m => !string.IsNullOrEmpty(m.Content))
    .OrderBy(m => m.SequenceNumber)
    .Take(10)
    .ToListAsync(cancellationToken);

For each message, we generate the embedding and link it back. Once EmbeddingId is set, that message won't be picked up again.

No chunking, no complexity. Message goes in, vector comes out, gets stored. The SourceType = "Message" links back to the original - we'll use this when searching.

The KnowledgeSearch Agent

Once the embeddings are generated, the KnowledgeSearch agent can use them to search the conversation history by meaning.

Why an Agent Instead of a Simple Tool?

You could just wire up a tool function. But wrapping it in an agent brings benefits:

Clear separation: Search logic lives in its own class, testable in isolation
Dependency injection: Proper lifetime management for database contexts and services
Composability: Later, we can add more specialized agents (DocSearch, WebSearch, etc.)

This is the "agentic" part of agentic RAG - agents with tools, each specialized for their task.

The Implementation

The flow is straightforward: embed the query, search pgvector, format results.

First, we embed the search query using the same model that embedded our messages:

// KnowledgeSearchAgent.cs
var queryVector = await _embeddingService.EmbedAsync(query);

The vector search uses pgvector:

// KnowledgeSearchAgent.cs
var results = await dbContext.Embeddings
    .Where(e => e.SourceType == "Message")
    .Select(e => new
    {
        Embedding = e,
        Distance = e.Vector.CosineDistance(queryVector)
    })
    .Where(x => x.Distance <= (1 - DefaultMinScore))  // DefaultMinScore = 0.40
    .OrderBy(x => x.Distance)
    .Take(DefaultTopK)  // DefaultTopK = 10
    .ToListAsync();

A few notes:

CosineDistance() returns distance (0 = identical, 2 = opposite), not similarity. Lower is better.
Threshold of (1 - 0.40) means we want at least 40% similarity. Tweak DefaultMinScore based on your use case.
IDbContextFactory gives us a fresh context per search - the agent is a singleton, but each query gets its own connection.

Finally, we fetch the actual messages and format them with timestamps. The timestamps matter - they help the LLM understand recency.

The pgvector Query

EF Core translates this LINQ query to:

SELECT e.*, e.vector <=> @queryVector AS distance
FROM embeddings e
WHERE e.source_type = 'Message'
  AND e.vector <=> @queryVector <= 0.6  -- 1 - DefaultMinScore
ORDER BY e.vector <=> @queryVector
LIMIT 10;

The <=> operator is pgvector's cosine distance. Lower distance = better match. The HNSW index we created earlier makes this logarithmic instead of linear - critical at scale.

Wiring It Up

Now we connect everything in AgentFactory and Program.cs.

The Agent Factory

Wiring the tool is the key step. We use AIFunctionFactory.Create() to turn our instance method into something the agent can call:

// AgentFactory.cs
var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

return chatClient.CreateAIAgent(new ChatClientAgentOptions
{
    Id = key,
    Name = key,
    ChatOptions = new ChatOptions
    {
        ConversationId = "global",
        Instructions = KnowledgeSearchSystemPrompt,
        Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync)],
        ToolMode = ChatToolMode.Auto
    }
});

The [Description] attributes on our method and parameters become the tool's schema - the LLM sees them and knows what the tool does and what arguments it needs.

ToolMode = ChatToolMode.Auto is important. It tells the model to decide when to use tools, rather than always using them or never using them.

The system prompt is equally crucial. We tell the LLM when to use the tool:

DECISION FRAMEWORK:
- For general knowledge (math, common facts): Answer directly without tools
- For recall questions ('did we discuss X?'): Use SearchConversationHistory
- When unsure if something was discussed: Search first rather than guessing

Without this guidance, models either never use tools or use them for everything. The prompt teaches restraint.

Registration in Program.cs

The key registration:

// Program.cs
builder.Services.AddSingleton<KnowledgeSearchAgent>();

Why singleton? The agent factory resolves from the root provider during startup. This is safe because KnowledgeSearchAgent only depends on singletons (IEmbeddingService, ILogger) and factories (IDbContextFactory) - no scoped services leaking through.

The rest follows the same pattern we established: AddAIAgent with factory delegates, AddHostedService for the background embedding processor.

Before and After

Let's see the difference:

Without RAG:

User: "What did we discuss about database indexes?" Agent: "I don't have memory of our past conversations..."

With KnowledgeSearch:

User: "What did we discuss about database indexes?" Agent: calls SearchConversationHistory("database indexes") Agent: "Based on our earlier conversation, we discussed adding indexes for ConversationId and the composite index for ordered retrieval..."

Night and day.

Summary

We've covered a lot of ground today, but we're still just scratching the surface.

We learned how to take abstract concepts like embeddings and store them in an actual database using pgvector. We saw how to consume that knowledge by building a specialized agent that can perform semantic searches over our own conversation history.

Along the way, we touched on the importance of database persistence, the nuances of tool calling with AIFunctionFactory, and how to manage agent lifetimes in a .NET application. We also explored chunking and more advanced RAG strategies like hybrid search and reranking - topics that are definitely worth exploring as you dive deeper into the world of AI.

The full code is on the part/01-agentic-rag branch. Clone it, run it, break it, and most importantly, make it your own.

Microsoft's official examples are also worth reading. The framework implements some features, including search, with higher-level abstractions such as TextSearchProvider. I used the lower-level approach here to make each step visible.

Here are some examples worth checking in the Microsoft Agent Framework repository:

Getting Started on GitHub

Agent_Step03_UsingFunctionTools/Program.cs
Agent_Step06_PersistedConversations/Program.cs
Agent_Step07_3rdPartyThreadStorage/Program.cs
Agent_Step12_AsFunctionTool/Program.cs
AgentWithRAG/*

Next Steps

We now have an agent that can remember and retrieve earlier conversations.

The next step is the Agent Loop. Instead of a single request and response, the agent can act, observe the result, and adjust its next step until the task is complete. This pattern is the basis for more autonomous coding assistants.

As these agents become more autonomous, we also need to know exactly what they're thinking. That's why we'll be diving into Observability and tracing so we can peek inside the "black box" and see every tool call, every reasoning step, and every decision the agent makes in real-time.

We're moving from "chatbots" to "collaborators." I'll see you in the next one as we start closing the loop. 🚀

AI Agents in .NET: Let's Build Something Smart

2025-12-21T00:00:00+00:00

Welcome to a new blog series about building AI agents in .NET.

Yes, you read that right - I just said .NET. Not Python. C#. Curly braces. Strong typing. With drums and trumpets.

Over the coming posts, we'll explore the Microsoft Agent Framework, build actual agentic systems, and - most importantly - have some fun doing it. This first post sets the stage: why I'm doing this, what we're building, and how to get started with the companion repository.

Here is how to get started.

Why, You Ask?

Honestly? I got a little restless. Every AI agent tutorial out there follows the same well-worn path:

"Build a weather agent!" - Revolutionary stuff. Though I hear windows also exist.
"Spam detection with AI!" - Gmail's been doing this since 2004.
"Customer service chatbot!" - Oh good, we definitely need more of those.

These examples are useful for learning the basics, but I wanted to build something closer to a real application.

This series is about building agents that are genuinely smart, genuinely fun, or ideally both. No boring examples. No wrapping API calls in agent clothing and calling it intelligent.

As for the language choice - I've always been a C-family person. Python is lovely for what it does, but give me curly braces and strong typing any day. When Microsoft released the Agent Framework for .NET? Yeah, that got me genuinely excited. First-class AI agents in C#. Native support, proper tooling, the whole package.

The Microsoft Agent Framework

So what exactly are we working with? The framework comes with everything you need to build proper agentic systems:

Native C# support (obviously)
A beautiful DevUI for testing and debugging your agents - still in preview and missing some Python-side features, but it gets the job done
Built-in patterns for common agentic scenarios (the fun stuff)
Integration with the broader .NET ecosystem (finally!)

And that's what this blog series is all about.

About DevUI

Speaking of DevUI - if you head over to Microsoft's documentation and switch to the C# tab, you're greeted with this gem:

"DevUI documentation for C# is coming soon. Please check back later or refer to the Python documentation for conceptual guidance."

Ah yes, the classic "refer to Python" move. You know, the language we specifically chose not to use for this series? The irony isn't lost on me. But hey, I'm not bitter - I'm just impressed they managed to ship a working DevUI before the documentation. That's actually kind of bold.

The DevUI is a useful web interface for chatting with agents and inspecting their behavior during development. It does not replace proper tracing with tools such as OpenTelemetry and Jaeger, but it works well for quick iteration and debugging. I will cover observability separately in a later post.

The Knowledge Repository

To support this series, I've created a companion repository called Knowledge. I briefly considered "AI-Stuff-I-Throw-Together-At-2AM" but that didn't seem like a good fit. So I thought about it - I'm deepening my own knowledge about AI as I create this series, and hopefully you'll gain some knowledge along the way too. Yeah, let's face it: Knowledge is simple. Sometimes simple works.

The repository is structured as a progressive learning path. Each branch builds on the previous one, taking you from zero to building sophisticated agentic systems. Here's what we're working with:

Branch	Topic	What You'll Learn	Codespace
`main`	Repository & Hello World Agent	Project setup, DevUI, your first conversational agent

More branches will be added as the series progresses. And honestly? That Codespaces button is kind of magical - click it, grab a coffee, and come back to a fully configured dev environment. No setup, no dependencies, just ready to go. I still find that ridiculously cool.

Star the repo if you want to follow along!

Development Environment

You've got two options here - pick whichever fits your workflow.

Dev Container Setup

First things first: reproducible development environments. The repository includes a .devcontainer configuration with:

.NET 10
PostgreSQL with pgvector for when we get into embeddings and semantic search
All the tooling pre-configured

Just open the repo in VS Code, click "Reopen in Container," and you're ready to go. The classic "works on my machine" problem? Solved.

You can also open it in a Codespace and work entirely in the browser without a local setup.

Classic

And for those of you rolling your eyes at all this container and cloud stuff - fair enough. Install the .NET 10 SDK, fire up VS Code or Visual Studio, clone the repo, and just go. Sometimes the old ways are the best ways. That said, you'll want to get PostgreSQL with pgvector set up sooner rather than later - we'll need it for embeddings and semantic search in upcoming posts.

What's on the Main Branch?

Let me walk you through what you'll find when you clone the repo. The main branch sets up everything you need to hit the ground running with AI agent development.

Project Structure

The solution is organized into two projects:

Knowledge - The main web application that hosts our agents and the DevUI
Knowledge.Shared - Shared configuration, extensions, and utilities

This separation keeps things clean as we add more complexity in future posts.

Configuration Done Right

One thing I'm particular about is handling configuration properly. In Knowledge.Shared, we have a KnowledgeSettings class that gives us strongly-typed access to our config values.

The important bits are these two properties:

public string ApiKey { get; set; } = string.Empty;

public string ApiEndpoint { get; set; } = string.Empty;

ApiKey is where your OpenAI (or compatible) API key goes. ApiEndpoint is optional - leave it empty and we'll hit OpenAI's default endpoint, or set it to point at Azure OpenAI, a local model, whatever you need.

Now, you definitely don't want to hardcode API keys in your source code. That's how keys end up on GitHub and suddenly you're funding a stranger's LLM experiments. Instead, we use .NET User Secrets:

cd src/Knowledge
dotnet user-secrets set "Knowledge:ApiKey" "your-api-key-here"

Your key stays on your machine, outside of source control. Sleep well at night.

Wiring Up the Agent

The following sections walk through Program.cs piece by piece.

First, the imports - nothing too surprising here:

using System.ClientModel;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.DevUI;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

We're pulling in the Agent Framework (Microsoft.Agents.AI.*), Microsoft's AI abstractions (Microsoft.Extensions.AI), and the official OpenAI client. Standard .NET web app stuff otherwise.

Next, we create our builder and call into our configuration extension:

var builder = WebApplication.CreateBuilder(args);

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ...
});

ConfigureKnowledgeDefaults is a helper method in our shared project. It handles loading appsettings.json, binding it to our KnowledgeSettings type, and then gives us a callback where we can access both the settings and a logger. This keeps Program.cs clean while still giving us full control.

Inside that callback, we set up OpenAI. First, a sanity check:

if (string.IsNullOrWhiteSpace(settings.ApiKey))
{
    logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets.");
}

Better to warn loudly than fail silently.

Then we create the OpenAI client options. If a custom endpoint is configured, we use it:

var options = new OpenAIClientOptions();

if (!string.IsNullOrEmpty(settings.ApiEndpoint))
{
    options.Endpoint = new Uri(settings.ApiEndpoint);
}

This is what lets you swap between OpenAI, Azure OpenAI, or even a local model running through something like Ollama with an OpenAI-compatible API.

Now we create the actual client and register it with dependency injection:

var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);

builder.Services.AddChatClient(client.GetChatClient("gpt-4.1").AsIChatClient());

GetChatClient("gpt-4.1") gets us a chat client for that specific model. .AsIChatClient() wraps it in Microsoft's IChatClient abstraction, which is what the Agent Framework expects. Using this abstraction means we could swap out OpenAI for any other provider without changing our agent code.

And finally - the actual agent registration:

builder.AddAIAgent("Knowledge", "You are a helpful agent named Knowledge.");

That's it. One line. We give it a name and a system prompt, and the framework handles the rest. We'll make this more sophisticated in future posts, but for a "hello world" agent, this is all you need.

Finishing the Pipeline

After our configuration callback, we register a few more services:

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

These set up the Agent Framework's handlers for OpenAI's responses and conversations API patterns.

Then we build the app and configure the HTTP pipeline:

var app = builder.Build();

app.ConfigureKnowledgePipeline();

ConfigureKnowledgePipeline is another shared helper - it sets up logging, error handling, and other middleware that we'll want across all our experiments.

Finally, we map our endpoints:

app.MapOpenAIResponses();
app.MapOpenAIConversations();
app.MapDevUI();

app.MapGet("/", () => Results.Redirect("/devui/"));

app.Run();

MapOpenAIResponses() and MapOpenAIConversations() expose endpoints that follow OpenAI's API patterns. MapDevUI() enables the Agent Framework's built-in developer interface.

That last MapGet just redirects the root URL to the DevUI. Because when you're developing agents, that's where you want to be.

Running the Application

Once configured, getting started is simple:

dotnet run --project src/Knowledge

Navigate to http://localhost:5000/devui and you'll see the DevUI - a beautiful interface for interacting with your agents, inspecting their reasoning, and debugging when things inevitably go sideways.

Summary

We've covered a lot of ground in this introductory post. You now have:

A companion repository with a reproducible dev container setup
A working "hello world" agent using the Microsoft Agent Framework
Proper configuration with user secrets (no API keys in source control!)
The DevUI for testing and debugging your agents

The foundation is solid. Now comes the fun part.

Next Steps

We've got the foundation in place - a working agent, DevUI, proper configuration. But let's be real: a "hello world" agent isn't going to impress anyone, least of all ourselves.

Next, I will add tools so the agent can perform actions, explore multi-agent scenarios, and use PostgreSQL with pgvector for embeddings and semantic search. A later post will also add proper observability.

But first things first. Step by step.

If you're a .NET developer who's been watching the AI agent space from the sidelines, wondering when C# would get some love - welcome. If you're just someone who's bored of the same old tutorials and wants to see something different - also welcome.

Clone the repo, star it if you're feeling generous, and let's build something that's actually worth building.

See you in the next post. 🚀