Chapter 12 · Reference

Cheatsheet & Glossary

Everything you'll need to look up — commands, file locations, acronyms, and concept definitions. Bookmark this one. The other pages explain why; this page tells you what and where.

Build & run commands

What	Command
Build the solution	`dotnet build src/AgenticHarness.slnx`
Run all tests	`dotnet test src/AgenticHarness.slnx`
Tests with coverage	`dotnet test --collect:"XPlat Code Coverage"`
Run a single test class	`dotnet test --filter FullyQualifiedName~MyTestClass`
Run the console UI (interactive)	`dotnet run --project src/Content/Presentation/Presentation.ConsoleUI`
Run a specific example non-interactively	`dotnet run --project <ConsoleUI> -- --example research`
Run the MCP server	`dotnet run --project src/Content/Infrastructure/Infrastructure.AI.MCPServer`
Run the SignalR Agent Hub	`dotnet run --project src/Content/Presentation/Presentation.AgentHub`

Secrets management

What	Command
Set a secret	`dotnet user-secrets set "Key:Path" "value" --project <path>`
List all secrets	`dotnet user-secrets list --project <path>`
Remove a secret	`dotnet user-secrets remove "Key:Path" --project <path>`
Clear all secrets	`dotnet user-secrets clear --project <path>`
Run the setup wizard (Windows)	`setup-secrets.bat`

Project layout cheatsheet

src/ ├── AgenticHarness.slnx └── Content/ ├── Domain/ │ ├── Domain.Common/ // configs, helpers, Result<T> │ └── Domain.AI/ // AgentManifest, SkillDefinition, etc. ├── Application/ │ ├── Application.Common/ // generic behaviors, helpers │ ├── Application.AI.Common/ // AI-specific interfaces, behaviors │ └── Application.Core/ // CQRS commands + handlers ├── Infrastructure/ │ ├── Infrastructure.Common/ │ ├── Infrastructure.AI/ │ ├── Infrastructure.AI.MCP/ │ ├── Infrastructure.AI.MCPServer/ │ ├── Infrastructure.AI.RAG/ │ ├── Infrastructure.AI.Evaluation/ // eval metrics + dataset runner │ ├── Infrastructure.AI.Connectors/ │ ├── Infrastructure.AI.Governance/ │ ├── Infrastructure.AI.KnowledgeGraph/ │ ├── Infrastructure.APIAccess/ │ └── Infrastructure.Observability/ ├── Presentation/ │ ├── Presentation.Common/ // composition root │ ├── Presentation.ConsoleUI/ │ ├── Presentation.AgentHub/ // SignalR agent hub │ ├── Presentation.ExecutionApi/ // REST API for uploaded agent bundles (ch. 17) │ ├── Presentation.WebUI/ // browser chat + generative-UI widgets │ ├── Presentation.Dashboard/ // observability dashboard + acting agent │ ├── Presentation.EvalRunner/ // runs eval datasets │ ├── Presentation.FoundryHost/ // Azure AI Foundry hosted agents │ └── Presentation.LoggerUI/ └── Tests/ // one test project per source project skills/ // SKILL.md files — loaded at runtime agents/ // AGENT.md files — loaded at runtime eval-datasets/ // eval YAML datasets (seed/ has 9) documentation/ // you are here

Where to look for...

If you want to find...	Look here
A config class	`Domain.Common/Config/`
A CQRS command + handler	`Application.Core/CQRS/<feature>/`
A MediatR pipeline behavior	`Application.*.Common/MediatRBehaviors/`
An AI service interface	`Application.AI.Common/Interfaces/`
A built-in tool	`Infrastructure.AI/Tools/`
DI registration for any layer	`<Project>/DependencyInjection.cs`
OTel setup	`Infrastructure.Observability/`
Skill content (runtime)	`skills/<id>/SKILL.md`
Agent manifests (runtime)	`agents/<id>/AGENT.md`
Plugin manifests (runtime)	`plugins/<id>/plugin.json`
Plugin interfaces	`Application.AI.Common/Interfaces/Plugins/`
Tool output compression	`Application.AI.Common/MediatRBehaviors/ToolOutputCompressionBehavior.cs`
Tests	`src/Content/Tests/`

Acronyms & jargon

A2A

Agent-to-Agent protocol — agents publish capabilities at /.well-known/agent.json and delegate tasks over HTTP. Sister to MCP. Implemented in Infrastructure.AI/A2A/.

AGENT.md

A Markdown file with frontmatter describing an agent — its domain, allowed tools, skills, autonomy tier, decision framework. Loaded by the agent metadata registry at startup.

AppConfig

The root configuration class. Bound from the "AppConfig" section of appsettings.json. See Configuration Reference.

Autonomy tier

Permission level assigned to an agent: Restricted, Supervised, or Autonomous. Determines whether tool calls run automatically, prompt for approval, or require explicit allow-listing.

BM25

Classic keyword-based retrieval algorithm. Used alongside vector search in the RAG pipeline's hybrid retrieval. See RAG Pipeline.

Clean Architecture

Architectural style with concentric layers (Domain → Application → Infrastructure → Presentation) and dependencies pointing inward. See Big Picture.

CompletionTool

The tool name declared in a skill's frontmatter whose invocation marks that skill as complete. Used by the prerequisite system — when a skill's CompletionTool is called, the harness records the skill as done, unlocking dependent skills. See Skills System.

.Common projects

The harness itself — reusable, template-level infrastructure (e.g. Application.Common, Application.AI.Common, Infrastructure.AI, Domain.Common). Treat as a library; don't edit unless improving the template for all consumers. See Big Picture.

.Core projects

Your application's specific business logic — the commands, queries, and rules that make this fork different from any other. Currently Application.Core ships with example agent commands. In a fork you'd add domain-specific projects (e.g. Domain.PupWalk, Infrastructure.PupWalk) alongside.

CQRS

Command/Query Responsibility Segregation — commands mutate state, queries read state, each has a dedicated handler. Implemented via MediatR in Application.Core/CQRS/.

CRAG

Corrective RAG — evaluates retrieval confidence and triggers refinement or rejection when confidence is low.

DeniedTools

A list of tool names on a PluginDeclaration that the plugin is never allowed to call. DeniedTools are bypass-immune — they cannot be overridden by auto-approve modes or autonomy tier settings. See Observability & Safety.

Dependency Injection. Microsoft.Extensions.DependencyInjection is the container. See "keyed DI" for the harness's extension of it.

EWMA

Exponentially Weighted Moving Average. Used by DriftDetection to detect quality regressions over time.

FAISS

Facebook AI Similarity Search — vector index library used as one of two vector store options (the other is Azure AI Search).

FluentValidation

C# validation library. Validators live alongside their commands and are run by RequestValidationBehavior.

HyDE

Hypothetical Document Embedding — query transform that generates a fake "ideal answer", embeds it, and retrieves against the fake answer's embedding.

IContextBudgetTracker

Tracks token consumption for a single agent turn against DefaultTokenBudget, so the assembler can stop packing context before the turn overflows. Scoped per turn — distinct from IConversationBudgetTracker.

IConversationBudgetTracker

Enforces a token ceiling across the whole multi-turn conversation, not just one turn. Registered as a singleton so the running total survives across turns; when the ceiling is hit it triggers a graceful break rather than throwing. Introduced by the loop-engineering work as the conversation-lifetime counterpart to the per-turn IContextBudgetTracker.

IOptionsMonitor

.NET pattern for accessing configuration that hot-reloads when the underlying file changes. Always preferred over IOptions. See Patterns.

Injected mode

A SkillMode where the skill receives all MCP tools from its parent plugin automatically, bypassing explicit allowed-tools declarations. Used for plugin-provided skills. See Skills System.

ITool

Internal tool interface. Every tool the agent can call implements this — file system, calculator, MCP wrappers, RAG retrievers.

JSONL

JSON Lines — one JSON object per line. Used for structured logs and meta-harness traces.

JWT

JSON Web Token. Used for authenticating MCP server endpoints via Entra ID.

Keyed DI

.NET 8+ feature allowing multiple implementations of an interface to coexist under string keys. The harness's central extensibility mechanism.

LLM

Large Language Model. The agent's brain — GPT-4o, Claude, etc.

Managed mode

The default SkillMode. Only tools explicitly listed in allowed-tools are resolved and given to the agent. The harness controls the tool surface. See Skills System.

MCP

Model Context Protocol — open standard for tool/prompt/resource exchange between AI agents and tool servers. See MCP Server & Client.

MediatR

C# library implementing the mediator pattern. Used to dispatch commands and apply pipeline behaviors.

Meta-harness

The optimization loop — proposes changes to skill files, evaluates them, keeps the best.

OTel / OpenTelemetry

Open standard for traces, metrics, and logs. See Observability & Safety.

PII

Personally Identifiable Information. Filtered from logs, traces, and tool responses.

Plugin / PluginDeclaration

A local directory declared in appsettings.json containing a plugin.json manifest. The harness reads the manifest, wires the plugin's skills and MCP servers, and applies boundary governance (AllowedTools, DeniedTools, AutonomyLevel). See Tools & Keyed DI and Observability & Safety.

Prerequisites

A list of skill IDs in a skill's frontmatter that must complete before this skill activates. Used for ordered skill composition in multi-skill agents. See Skills System.

Progressive disclosure

The three-tier skill loading model — index card, folder, filing cabinet — that keeps the token budget under control. See Skills System.

RAG

Retrieval-Augmented Generation. Bring relevant chunks from your documents into the agent's context. See RAG Pipeline.

RAPTOR

A hierarchical document-summarization strategy for RAG. Builds a tree of summaries so retrieval can target fine or coarse granularity.

ReDoS

Regular Expression Denial of Service. The MaxSubcommandLimit permission setting guards against this in pattern matching.

Result<T>

The pattern for expected failures. Returns success/failure with optional error details instead of throwing. See Patterns.

RRF

Reciprocal Rank Fusion — algorithm for merging multiple ranked lists into one. Used in hybrid RAG retrieval.

Sandbox

The path-validated restriction on file system access. The agent thinks it has a file system; it actually has a cage.

SKILL.md

A Markdown file with frontmatter that defines what an agent knows for a given role. Parsed by SkillMetadataParser and held in SkillMetadataRegistry at startup.

SkillMode

Enum: Managed (default — harness resolves only declared tools) or Injected (all MCP tools from the parent plugin are passed through). See Skills System.

Span / Trace

OpenTelemetry concepts. A span is one operation; spans nest into traces. We instrument every command, agent turn, tool call, and LLM request.

Tier 1 / 2 / 3

The three skill loading levels — index card (~100 tokens), folder (~5K), filing cabinet (unbounded).

Token budget

Cap on how many tokens an agent turn can consume. Configured via AppConfig:AI:AgentFramework:DefaultTokenBudget (default 200,000); the per-turn ceiling is tracked by IContextBudgetTracker. For the ceiling that spans an entire multi-turn conversation, see IConversationBudgetTracker.

ToolOutputCategory

Enum classifying tool output content type: Default, Diagnostic, DataHeavy, Conversational. Determines which compression strategy is applied. See A Message's Journey.

ToolOutputCompressionBehavior

MediatR pipeline behavior that compresses large tool outputs by content type. Detects the ToolOutputCategory, selects a strategy (FreeText, JSON, XML, Diagnostic), and compresses when the output exceeds configurable thresholds. Reduces token usage significantly for verbose tool responses.

User Secrets

.NET's development-only encrypted-at-rest secret store. Run dotnet user-secrets set to populate.

The 60-second mental model

If you read only this section: this codebase is a Clean Architecture .NET 10 template for AI agents. Skills (Markdown files) tell agents what they know — agents can use multiple skills simultaneously, with prerequisites controlling execution order. Tools (C# classes) tell agents what they can do. Local plugins extend the skill surface by bundling skills and MCP servers from external directories, with boundary governance (AllowedTools/DeniedTools) controlling their blast radius. MediatR pipeline behaviors wrap every request with safety, validation, tool output compression, observability, and audit. The agent loop is owned by Microsoft.Agents.AI. Everything is observable via OpenTelemetry. Configuration lives in strongly-typed classes bound from appsettings.json + User Secrets. Add new tools by implementing ITool and registering them in keyed DI. Add new skills by dropping a SKILL.md in skills/. Test everything. Don't disable the sandbox.

You're done

You've completed the developer onboarding guide. From here:

Re-read A Message's Journey — it'll click differently now.
Browse the skills/ folder for examples of real SKILL.md files.
Open Jaeger and run a few examples to watch the trace timeline.
Pick a small feature to add. Use Extending the Harness as your template.

Found a gap in this guide? That's a bug. File it.

← Previous

11 · Extending the Harness

↑ Back to start

00 · Welcome