svnscha - dotnet

The Joy of Writing a Debugger Adapter for Visual Studio Code

2026-04-15T00:00:00+00:00

Current State

Before I get into the story, here is the current result: Visual Studio Code debugging a C++ application with WinDbg under the hood through my first proof of concept integration.

Right now this is still an early POC, not a finished debugger experience. It proves the architecture works and that VS Code can drive WinDbg through a custom adapter, but it still needs a lot more iteration before I would call it really useful.

One detail I already like is that the debugger command window is not a fake simplified console. I can type regular WinDbg commands straight into it.

Why

Because I do what I always do when a workflow annoys me: I build a tool until the annoyance goes away.

This time the pain point was remote debugging a service application running inside a VM. My ideal flow was simple:

Compile locally
Deploy to the VM
Start or restart the service
Attach a debugger
Get back to work without ten minutes of clicking around

That sounded perfectly reasonable: a small helper extension for Visual Studio Code, a bit of automation, some launch configuration glue, and done.

That was the plan.

It did not stay the plan.

Removing Friction

I started with the pragmatic part first: automate the annoying steps.

I wired up a helper extension that could compile the service, copy the binaries to the VM, and prepare the remote machine for debugging. This is my favorite kind of productivity work, because the payoff is immediate. Every bit of friction you remove saves time again and again.

Once the plumbing was in place, I expected the final step to be easy: tell VS Code to remote debug the service and call it a day.

Instead, I hit a wall.

VS Code Is Not Visual Studio

At first glance, this feels like something that should already exist. Visual Studio has mature debugging capabilities. VS Code has debugging. Microsoft builds both. Surely there must be a supported path to do classic remote Windows debugging from VS Code, right?

Not really.

The more I dug into it, the clearer it became that the debugging stack in VS Code is a different world. VS Code speaks the Debug Adapter Protocol, or DAP. It expects debugger extensions to implement that protocol and sit between the editor and the actual debugger engine.

That part is good. DAP is a clean idea.

The frustrating bit was this: the specific native Windows remote-debugging flow I wanted was not available through a supported public route in VS Code. The Visual Studio native debugger stack is not something you can just plug into from your own VS Code extension and say, "Thanks, I will take remote debugging from here." And the VS Code side does not magically inherit Visual Studio's remote debugging capabilities just because both products come from Microsoft.

So after spending time exploring options, the conclusion was simple:

There was no supported way to get the workflow I wanted with the existing pieces.

Building It Anyway

Once I accepted that I would not be wiring together existing public APIs, the problem changed shape.

The question was no longer, "How do I enable remote debugging in VS Code?"

It became:

"What debugger engine can I control myself, and how do I make VS Code talk to it properly?"

That is where WinDbg entered the story.

WinDbg already knows how to do the important parts. User-mode debugging. Remote debugging. Kernel debugging. Crash dump analysis. It is a serious tool with decades of capability behind it.

But again, my tool of choice did not give me the VS Code experience I wanted out of the box.

So the next step was clear:

Build a debugger adapter for WinDbg.

Learning DAP

If you want to integrate a debugger with VS Code, DAP is the contract. Once I sat down and read it properly, a lot of things clicked.

The official home for it is the Debug Adapter Protocol website, and that site is worth bookmarking because it has both the overview and the actual specification. At the time I was working through this, the important mental model was simple: VS Code and the adapter exchange JSON messages with a very predictable shape, and the protocol defines what those messages are supposed to mean.

The protocol is straightforward. VS Code sends requests like initialize, launch, attach, setBreakpoints, stackTrace, variables, continue, next, and so on, and your adapter answers them while emitting events like initialized, stopped, continued, and terminated.

That sounds simple enough until you remember that a debugger is mostly state, timing, and edge cases.

Still, the protocol gave me exactly what I needed: a structured way to make VS Code think in terms of debugging, while I figured out how to translate that into WinDbg behavior.

This was the moment where the project stopped being a helper extension and became a real debugger adapter.

To make that a bit more concrete, a minimal launch payload for the current POC looks roughly like this:

The adapter currently points at the debugging engine directly, so the windbg setting names the WinDbg stack even though the configured path is dbgeng.dll rather than windbg.exe.

{
	"type": "dapwdbg",
	"request": "launch",
	"name": "Launch through WinDbg",
	"windbg": "C:/Program Files (x86)/Windows Kits/10/Debuggers/x64/dbgeng.dll",
	"program": "${workspaceFolder}/build/Debug/testapp.exe",
	"stopAtEntry": true
}

That stopAtEntry flag is a small but useful quality-of-life feature. I added it because it is a familiar debugger option and useful to have. By default it is false, so the adapter continues after configurationDone. If you set it to true, VS Code stays paused at entry and waits for the next command.

And on the wire, the messages are simple, which is exactly what you want from a protocol. A stop event coming back from the adapter looks roughly like this:

{
	"seq": 17,
	"type": "event",
	"event": "stopped",
	"body": {
		"reason": "entry",
		"description": "Paused at process entry.",
		"threadId": 1,
		"allThreadsStopped": true
	}
}

That might not look exciting, but it is the important part: once VS Code receives something in that shape at the right time, it knows how to show the stack, scopes, variables, and stepping UI around it.

Step 1: Parse the Schemas Instead of Hand-Writing Everything

One thing became obvious very quickly: I did not want to manually model the entire protocol by hand in C#.

That is the kind of task that feels fine for the first ten message types and becomes a waste of time by the next fifty.

DAP is defined by schemas. Machines should read schemas. Machines should generate code. Humans should not write all of that by hand.

So one of the first pieces I built was a small toolchain around the protocol definitions.

The idea was straightforward:

Parse the protocol schemas
Convert them into C# types
Use generated models for requests, responses, events, and payloads
Stop wasting time on repetitive plumbing

This bought me two things immediately:

Better consistency with the protocol
Faster iteration whenever I needed to expand coverage

It also reduced a whole category of annoying bugs where hand-written DTOs silently drift away from the spec.

That generator phase was not glamorous, but it kept paying off. Every time I added another request handler later, I was very happy not to be hand-authoring another stack of protocol classes.

The nice part is that the generated code stays very literal. For example, the generated LaunchRequest model is basically just a strongly typed wrapper around the DAP shape, with Command = "launch" baked in and a typed Arguments property. A generated event model like StoppedEvent then points at a generated StoppedEventBody class with fields such as Reason, Description, ThreadId, and AllThreadsStopped.

That is exactly the level of abstraction I wanted. The protocol layer should be boring and explicit so the interesting work can happen one layer above it.

Step 2: A Python Generator That Produces C#

Yes, the adapter is in C#.

Yes, I used Python to generate part of it.

That combination made sense for the job. Python is still one of the fastest ways to build a transformation tool, especially when the task is basically: read structured input, normalize it, and generate source code.

So I built a Python tool that parsed the protocol definitions and generated the corresponding C# code.

That generator handled the boring but important parts:

Request and response classes
Event payloads
Shared protocol types
Optional fields and enum-like shapes
Enough structure to keep serialization predictable

This turned out to be one of the highest leverage steps in the whole project. Instead of spending my time on protocol plumbing, I could focus on the parts that actually matter: session management, command execution, state transitions, and debugger behavior.

In other words, I automated the boring part so I could focus on the interesting part.

Step 3: Wrap WinDbg Through dbgeng

Once the protocol layer was under control, the next question was how to talk to the debugger engine itself.

For that I went with dbgeng, the Windows debugging engine behind the debugger family. That is where the real power is. It is also where some of the complexity is.

On the package side, the current codebase still reflects some iteration. The wrapper layer currently leans on the public DbgEng interop exposed through the ClrMD packages Microsoft.Diagnostics.Runtime and Microsoft.Diagnostics.Runtime.Utilities. Separately, the broader adapter codebase also references Microsoft.Debugging.Platform.DbgEng and Microsoft.Debugging.Platform.DbgX, which are part of the newer Microsoft debugging platform stack. That split is real in the code today, but I do not want to pretend it is already the final architecture.

In the wrapper itself, the core interfaces in use right now are IDebugClient, IDebugControl, IDebugSymbols, and IDebugSystemObjects. For callbacks, I register IDebugEventCallbacks and IDebugOutputCallbacks. That gives me the essential surface area I need to launch or attach, execute commands, inspect symbols, enumerate threads, and react to breakpoints, exceptions, exits, and debugger output.

This wrapper layer became the core of the adapter. Its job was to expose the debugger in a way that fit the expectations of DAP rather than the expectations of a human typing commands into a debugger console.

That means translating concepts like:

Launching or attaching to a target
Resuming and breaking execution
Enumerating threads
Building stack traces
Reading locals and variables
Handling modules and symbols
Surfacing exceptions, exits, and other stop reasons

If you have ever worked with debugger APIs, you know they do not hide much complexity. You need to be explicit. You need to think about ownership, state, timing, callbacks, and edge cases that often show up only once things are already going wrong.

One small example was line stepping. I had already enabled source line support and saw source locations show up, so for a moment I thought step over was working.

It did not.

What I had actually proven was that WinDbg could show me line information. That is not the same thing as telling it to do source-based stepping. I had forgotten to enable that part as well. The fix was one extra command:

public void EnableSourceLineSupport()
{
	ThrowIfDisposed();
	ExecuteDebuggerCommand(".lines -e", "Could not enable source line support");
	ExecuteDebuggerCommand("l+t", "Could not enable source-based stepping");
}

That was a very debugger-adapter kind of bug. Everything looked correct for just long enough to be misleading.

Step 4: Implement the Real Requests and Iterate

With the generated protocol types on one side and the WinDbg wrapper on the other, I could finally work on the adapter loop itself.

At this point, the adapter was useful for actual debugging.

I began with the core requests: initialize, launch, attach, setBreakpoints, configurationDone, threads, stackTrace, scopes, variables, continue, pause, next, stepIn, stepOut, disconnect, ...

On paper that looks like a clean checklist. In reality, each of those requests is a conversation between at least three parties:

VS Code and its expectations
The adapter and its internal state machine
The debugger engine and its current state

So the implementation loop looked roughly like this:

Add one request
Run it in VS Code
Watch it fail in an interesting way
Fix the translation layer
Hit the next state mismatch
Repeat until the experience works the way it should

This is also where you learn that "technically works" and "feels right to use" are not the same thing.

It is not enough to answer the request. You have to answer it in the right order, at the right time, and with enough fidelity that the editor can build a coherent UI around it.

That was one of the more interesting parts of the project.

Here is a tiny slice of what that translation layer looks like today. After launch, the adapter records whether it should remain paused at entry or continue once VS Code finishes sending its setup messages:

_launchAwaitingConfigurationDone = true;
_launchStopAtEntry = DapArgumentReader.TryGetBoolean(arguments, "stopAtEntry")
	?? DapArgumentReader.TryGetBoolean(arguments, "stopOnEntry")
	?? false;

This is the kind of code that looks harmless until you realize it decides whether the whole session feels smooth or broken.

When It Worked

At some point the pieces clicked together.

I could launch a debugging session from VS Code, talk to WinDbg through the adapter, and use the editor as if this had always been a normal supported workflow.

It also stopped being just about the original VM service scenario. Because the adapter sits on top of WinDbg, it opened the door to more than the first use case:

Local launch and local attach already work in the adapter
Dump-file attach is wired in
Remote attach and kernel scenarios are the next serious end-to-end targets
Crash dump debugging is now a realistic extension of the same architecture

That was the point where the project started to feel solid.

Why This Was Fun

This was fun for the same reason good tooling work is always fun: it changes how you work.

You remove friction once, then benefit from it every day after that. And along the way, you learn where the real product boundaries are. Visual Studio and VS Code may look adjacent from the outside, but their debugging plumbing is very different. Once that became clear, the path forward became clear too.

What I Learned

This project taught me a few things very clearly:

If a workflow matters enough, it is often worth productizing it for yourself
DAP is a really good abstraction for debugger integration
Code generation is the right answer when a protocol brings lots of repetitive structure
Debugger adapters are mostly about state, timing, and translation
WinDbg becomes much more approachable when you put a good UX in front of it

Also: if you think you fixed stepping, make sure you actually fixed it and did not just make the debugger show line numbers.

Most importantly, I was reminded again that some of the best side projects start as practical attempts to make tomorrow less annoying than today.

Summary

I only wanted a better remote debugging workflow for a service running in a VM.

That turned into DAP, schema parsing, code generation, dbgeng, and a long series of state-machine bugs.

The result so far is a working first proof of concept: a WinDbg-backed debugger adapter for Visual Studio Code with local launch, local attach, dump-file attach, stack traces, scopes, variables, breakpoints, and step commands working well enough to prove the architecture.

That matters because it means I finally have a base I can build on. I have not implemented remote debugging or kernel debugging yet, but I now feel ready to take a real shot at both without getting lost in the basics again.

Next Steps

The next step is to use this base for the work I actually set out to do:

Harden the current adapter and clean up rough edges in the state machine
Start implementing the actual remote debugging flow for the VM scenario
Take a first real implementation shot at kernel debugging too
Keep the scope under control so the project does not drift again like it did at the start
Open source the project once the foundation is stable enough
Keep turning WinDbg power into something that feels normal inside VS Code

And yes, this all started with "I just want to remote debug a service on a VM."

That is usually how the best tools start.

Meet Ralph: The AI Coding Agent That Just Keeps Going

2026-01-26T00:00:00+00:00

📺 Watch Ralph in Action: Ralph implementing its own features

🔗 Links: GitHub Repository

Shoutout to Matt Pocock whose viral tweet about "Ralph Wiggum" sparked this whole thing.

Why, You Ask?

Because AI coding assistants have a dirty little secret: they forget.

You start strong. "Refactor this auth module." The AI gets it. Code looks good. You're feeling productive.

Then 15 minutes later... it forgets what you discussed. It starts solving problems you never asked about. It rewrites code you specifically said to leave alone.

Sound familiar?

The Problem

Most AI coding tools are built for short bursts. Quick questions, small fixes, code snippets. Try to run them for hours on a bigger task? Good luck. Context degrades. Focus drifts. You spend more time course-correcting than coding.

I always wanted something different. An AI that could work autonomously on well-defined tasks. Start it before bed, wake up to working code. The missing piece? An agent that you can programmatically control.

Now, with the GitHub Copilot SDK and the Ralph loop, this has become too easy not to do.

So I built yet another Ralph.

What Is Ralph?

Ralph is a .NET CLI tool that treats AI as an autonomous agent, not a chat buddy. The key insight: structure breeds autonomy.

Here's how it works:

You describe what you want. Ralph asks clarifying questions, then generates a structured PRD with prioritized user stories.
Ralph executes autonomously. Picks up one story at a time, implements it, runs verification scripts to confirm it works, commits, moves on.
Repeat until done. You come back to find working, tested code.

The Secret Sauce: The PRD

At the heart of Ralph is a simple JSON file - the Product Requirements Document:

{
  "project": "my-app",
  "taskName": "add-auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create login endpoint",
      "acceptanceCriteria": [
        "POST /api/auth/login accepts email and password",
        "Returns JWT token on success",
        "ralph_verify(Build) passes",
        "ralph_verify(Test) passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

Each story is small enough to complete in one go. Ralph picks the next one where passes: false, implements it, runs verification, and marks it complete. If the build fails, it sees the errors and fixes them. If tests fail, same thing.

The magic is in the ralph_verify() calls. These run actual C# verification scripts - compiled at runtime with Roslyn - that confirm the work is correct before moving on.

Verification Scripts

Traditional AI assistants produce code and hope for the best. Ralph takes a different approach: every story must pass verification before it's marked complete.

The ralph_verify() function in acceptance criteria tells Ralph which scripts to run. When Ralph sees ralph_verify(Build) passes, it executes the Build script and confirms it succeeds before moving on.

Ralph ships with Build and Test scripts out of the box. They're C# classes compiled at runtime with Roslyn:

using Ralph.Core.Abstractions;

namespace Ralph.Scripts;

[VerificationScript("Build", "Verifies solution compiles")]
public class Build : IVerificationScript
{
    public VerificationResult Execute()
    {
        // Spawn dotnet build, capture output, return pass/fail
    }
}

The key insight: Ralph loops until all verification scripts pass. If Build fails, Ralph sees the compiler errors and attempts to fix them. If Test fails, Ralph sees which tests failed and why. This self-correcting loop is what enables hours of autonomous work.

Why custom scripts instead of just telling the AI "run dotnet build"? Context efficiency. A successful build returns "Build succeeded" - not the entire compiler output. Only on failure does Ralph see the errors it needs to fix. This keeps the context window lean and focused on what matters.

Want custom verification? Drop a script in .ralph/scripts/:

[VerificationScript("Lint", "Runs dotnet format to check code style")]
public class Lint : IVerificationScript
{
    public VerificationResult Execute()
    {
        // Run dotnet format --verify-no-changes
        // Return pass/fail based on exit code
    }
}

Now you can use ralph_verify(Lint) passes in your acceptance criteria. Security scans, API tests, whatever you need.

Behind the Scenes

Every AI model has a context window-the amount of text it can "see" at once. Ralph works within these limits by keeping each story self-contained.

A story must fit entirely within a single context window:

The system prompt (Ralph's instructions)
The current story's details and acceptance criteria
Relevant source files Ralph needs to read
Space for Ralph to "think" and generate code

Practical guidance:

Story Size	Files Touched	Recommendation
Small	1-3 files	✅ Ideal
Medium	4-8 files	✅ Good
Large	9-15 files	⚠️ Consider splitting
Too Large	15+ files	❌ Split required

Ralph doesn't have persistent memory across stories. Each time it picks one up, it starts fresh. This isn't a bug-it's a feature that forces clean design. Each story is a complete, verifiable unit of work.

"Add user authentication" becomes:

Create User entity and migration
Implement password hashing service
Create login endpoint
Add JWT token generation
Implement authentication middleware
Create registration endpoint

Each story is small enough to complete in one iteration, yet together they deliver the full feature.

State Management

Ralph maintains state at two levels:

PRD state (persistent) - which stories exist, which have passed, notes from completed work. This file persists across sessions and gets committed to your repo.

Session state (ephemeral) - current working story, in-progress changes, retry attempts. Lives only for one execution.

If Ralph crashes mid-story, that story remains passes: false and will be retried on next run. Completed stories are never redone.

Getting Started

You'll need .NET 10 SDK and GitHub Copilot CLI installed and authenticated.

# Build and pack
dotnet build
dotnet pack src/Ralph/Ralph.csproj

# Install globally
dotnet tool install --global --add-source src/Ralph/nupkg Ralph

Then in your project:

# Option A: Plan and implement in one go
ralph

# Option B: Plan first, then implement separately
ralph plan    # Create the PRD interactively
ralph run     # Implement all stories from the PRD

That's it. Ralph asks "What would you like to accomplish?", creates a PRD from your description, and implements all stories. Go grab coffee.

Why This Works

Traditional AI assistants are designed for conversation. Ralph is designed for execution.

	Traditional AI	Ralph
Duration	Minutes	Hours
Context	Degrades over time	Fresh per story
Verification	You check manually	Scripts verify automatically
Human involvement	Constant supervision	Set and forget

The AI model is the same. The difference is the workflow architecture around it.

The Catch

Stories need to be small enough to fit in a context window. If a story requires understanding 50 files at once, it'll struggle. Keep them focused: 1-5 files per story, one concern each.

Also, this isn't magic. Ralph still needs good acceptance criteria. Vague requirements produce vague results. But that's true of any engineering work.

Summary

AI coding assistants are great at short bursts but fall apart on longer tasks. Ralph fixes that by giving AI what it needs: structure. A PRD breaks work into discrete stories. Verification scripts confirm each one works. The result? An agent that can run for hours without wandering off course.

The shift from "AI assistant" to "AI agent" isn't just semantic. It's the difference between babysitting and delegating.

Next Steps

Watch the demo - See Ralph implement its own features in the YouTube video
Clone the repo - github.com/svnscha/ralph
Try it on something small - Pick a well-defined feature, let Ralph work on it overnight, come back to commits

That moment when you return to working, tested code you didn't write line by line? That's when it clicks.

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. 🚀