Welcome to the Agentic Harness.
You've cloned the repo. Maybe your tech lead pointed you here, maybe you're just curious. Either way — this guide takes you from "what am I looking at?" to "I just added a new tool to the agent and it works" in a few focused sittings. We'll skip nothing. We define every acronym. We walk through real code line by line.
One concept up front: this is a template
Before you start, the most important framing: this codebase is a template, not a finished application. The expectation is that you (or your team) will fork it and build something specific — a dog-walking scheduler, an internal IT helpdesk, a code review bot. Whatever your "thing" is.
Because of that, every layer is divided into two kinds of projects:
-
.Commonprojects — the harness itself. The pipeline behaviors, the agent runtime, RAG, MCP, governance, observability. Treat these like a library. You'll read them; you usually won't edit them. -
.Core(and your domain-specific projects) — your actual application's business logic. If you're building "PupWalk," your booking command, dog profile entity, and walker matching service live here.
Knowing which side of that line a piece of code lives on tells you whether to read-and-respect it (Common) or freely modify it (Core). We come back to this distinction often — most prominently on The Big Picture.
Who this guide is for
You're a developer — possibly junior, possibly senior but new to AI agents, possibly somewhere in between — who needs to understand and extend this codebase. You're not looking for marketing copy. You're not looking for a conceptual overview (we have a separate course for that). You're not looking for Azure deployment topology (that's the Architecture Guide). You want to know where things live, why they're built that way, and how to change them safely.
We assume you can read C#, you've used dependency injection before, and you've seen a unit test. We don't assume you know what MediatR is, what an "agent" actually means in this codebase, what MCP is, or how Clean Architecture works in practice. Those get explained the first time they come up.
Skim the "Get Running" page, then jump to A Message's Journey — that's the single most useful page for understanding how the codebase actually runs at runtime.
What you'll be able to do
By the end of this guide, you'll be comfortable doing the following without asking for help:
- Clone the repo, wire up your credentials, and have an agent answer a question.
- Trace a single user prompt from the console all the way through validation, the agent factory, the LLM call, tool execution, and back to the screen.
- Add a new tool the agent can call (a function it can execute).
- Add a new skill — a Markdown file that teaches the agent what it knows and when to use which tools.
- Add a new agent type that uses a different combination of skills and tools.
- Read traces in Jaeger to debug a failed conversation.
- Understand the meta-harness loop well enough to add a new evaluation task.
How this guide is organized
Each page below answers one specific question. They build on each other, but you can also skip around once you've finished "Get Running." The pages with a ★ are the ones we recommend reading in order on your first pass.
Clone, install prerequisites, configure secrets, build, and run your first agent conversation. Includes troubleshooting for the errors you'll actually hit.
02 ★
Every knob in appsettings.json — what it does, when to change it, and the
recipes for the most common adjustments. Your constant companion.
Clean Architecture in this codebase — what each layer owns, what depends on what, and a "where does X live?" map you'll come back to often.
04 ★Follow one user prompt from keystroke to LLM response. The single most important page in this guide.
05
Three-tier progressive disclosure, how SKILL.md files work, and how the
agent decides what to load into context.
How tools register with the DI container, how the LLM finds them, and the sandboxing that keeps them safe.
07Retrieval-Augmented Generation — ingestion, hybrid search, reranking, assembly. Each stage explained with the actual classes.
08The Model Context Protocol — how this harness exposes its tools to other agents, and how it discovers tools from external servers.
16Tools that render interface, not text — inline images, forms, tables, and charts in the AgentHub WebUI, plus the acting Dashboard agent. One transport, two front-ends.
17Calling the harness from outside: upload an agent bundle, submit and run a workflow, or discover which tools your credential may invoke — each under a per-caller capability grant, polled or streamed. The integration guide, with an OpenAPI spec.
09 ★
Result<T>, the MediatR pipeline, factories, immutability, and the
rules-of-thumb that keep the code consistent.
OpenTelemetry, content safety middleware, governance policies, and how to read a Jaeger trace when an agent goes off the rails.
11 ★Three concrete recipes: add a tool, add a skill, add a new agent. Copy-paste friendly, with the test patterns to match.
12Every command you'll need, every config key that matters, every acronym defined in one place. Bookmark this one.
How to use the page layout
A few visual conventions you'll see throughout. They're worth learning once so they don't slow you down later.
When you see a purple box like this, we're about to define a term that's not obvious. You can read it now or skip and come back. Example: MediatR — a C# library that decouples "the thing that wants to happen" (a command) from "the code that actually makes it happen" (a handler). Both sides depend on a shared interface, not on each other.
Green boxes are quick wins, idiomatic patterns, or shortcuts that make a task faster. Read them — they're the fastest way to learn the local conventions.
Yellow boxes flag things that look simple but have a gotcha. Pay attention to these — they're usually the things that take an afternoon to debug.
Red boxes mark anti-patterns or footguns. If the instinct is to do the thing in the red box, stop and read the suggested alternative.
Annotated code blocks
When code is doing something non-obvious, we'll show it as a two-column block — the actual code on the left, plain-English explanation on the right. Like this:
"file_system". When a skill says it needs file_system, the
harness will resolve this instance. Different agents can have different tools
under the same key — that's the point of keyed DI.
Code block headers
Code blocks have a header showing the file path and a copy button. The path is clickable in the
repo — if you see src/Content/Application/Application.Core/CQRS/..., that's where
you'll find the real file.
# Build the entire solution
dotnet build src/AgenticHarness.slnx
# Run the console UI in interactive mode
dotnet run --project src/Content/Presentation/Presentation.ConsoleUIOne important note before you start
This codebase is a template. The expectation is that you (or your team) will clone it and modify it to build something specific. The patterns are opinionated on purpose. Before you change one, read the corresponding page in this guide — most of the choices that look weird have a reason that's not obvious from the code alone.
If you find a place where a pattern looks wrong and the guide doesn't explain why, that's a bug in the guide. Flag it.
Ready? Start with "Get Running in 10 Minutes" — by the end of that page, you'll have the harness running on your machine.