One Screen the Architect Can Defend: A Reference Architecture for the .NET Agentic Service

🗓️ Last updated: August 2026

It is the architecture review the Friday before a greenfield It is the architecture review the Friday before a greenfield .NET agentic service ships. The senior architect projects Program.cs onto the meeting room wall: sixty lines of generic host wire up. A staff engineer with three months on the team asks the only question that matters. Where does the prompt template live? The architect points at one line: services.Configure<PromptCatalog>(builder.Configuration.GetSection("Prompts"));. The catalog binds from appsettings.json, overlays from the environment specific file, surfaces through IOptionsMonitor<PromptCatalog> for hot reload, and is read on each invocation by the agent host. The whole answer takes ninety seconds. The architecture is defensible because every question of "where does X live" has exactly one answer the team can point to in the wire up file.

That is the bar a reference architecture clears. The five preceding articles in this series each described a component: the Microsoft Agent Framework substrate, the IChatClient middleware pipeline, structured outputs as a typed contract, hosted service lifecycle, and the streaming surface. The closer assembles them into a single service the architect can defend before the first commit.

What This Article Is Not

This is not a repository you can copy and paste. It is not a vendor scaffold from dotnet new. It is not an Azure deployment recipe; the deployment surface here is generic .NET hosting, and the cloud specific wire up is a wrapper around the same generic host. It is not the only valid layering for a .NET agentic service; it is the layering a senior architect should be able to defend in a review and adjust deliberately when the project's constraints demand a different cut.

The Thesis

A .NET agentic service is a generic host with five seams the architect owns. The layering across Domain, Application, Infrastructure, and Hosting is the same canonical layering ASP.NET Core taught a decade ago. What changes is the lifetime of the IChatClient pipeline, the placement of the AgentSessionStore, the configuration surface for prompt versions and model selection, the OpenTelemetry pipeline that wraps the agent middleware, and the choice between a unified web host or a worker plus gateway split. Get those five seams right and the service is boring to operate. Get one wrong and it surfaces in production at the worst possible moment: a lifetime mismatch that captures stale options into a singleton, an environment variable override that silently changes the model on production traffic, a span graph that explodes when streaming turns chunks into events.

What the Classical .NET Version Looked Like

The pre agentic .NET version of "service that calls an external API and exposes results to a client" was small. A web host. A typed HTTP client through IHttpClientFactory. A Minimal API endpoint. An IOptions<T> block bound from appsettings.json. A logger at a constructor. The layering was implicit because the surface was small and the failure modes were familiar.

An agentic service breaks that pattern. The model client is the substrate of every interesting code path. The conversation has state that outlives the request. The middleware wrapping the model call carries telemetry, function invocation, structured output translation, and cost guardrails. The runtime mixes interactive HTTP and long running background work. The configuration surface needs to allow prompt version rollouts and model swaps without a redeploy. The shape that emerges is recognisably the four layer pattern ASP.NET Core has always supported, but each layer carries weight the classical small API version never had.

The Four Layers

Domain holds the records that describe the service's contract with itself: the ChatMessage and ChatRole from Microsoft.Extensions.AI, the application specific structured output records from Article 3, the session and identity types, and the tool contracts. Domain is dependency free. It compiles without a chat client implementation, without a hosting reference. The test is whether the project builds on its own.

Application holds the use cases: orchestration that takes a user request, resolves the right prompt, calls the agent, runs the tools, validates the structured output, and returns a result. Application depends on Domain and on the abstractions in Microsoft.Extensions.AI, IChatClient, IEmbeddingGenerator, ChatOptions, never on a specific provider. The test is whether the use case can be unit tested with a stub IChatClient that returns a canned ChatResponse.

Infrastructure holds the implementations: the configured OpenAIClient or AzureOpenAIClient wrapped into an IChatClient, the Redis backed AgentSessionStore from Article 4, the distributed cache, the function invocation registrations, and the OpenTelemetry exporter wiring. Infrastructure depends on Application's abstractions. The test is whether a swap from OpenAI to Azure OpenAI changes only the registration line in Program.cs.

Hosting is the composition root: Program.cs itself. It reads configuration, wires the M.E.AI middleware pipeline, registers the agent and session store, configures IHostedService workers from Article 4, maps the streaming endpoints from Article 5, and adds OpenTelemetry. Hosting depends on every other layer. The test is whether a new engineer can read it top to bottom and answer every "where does X live" question without opening another file.

The four layer cut is older than the Microsoft Agent Framework and older than Microsoft.Extensions.AI. The discipline, no chat client implementation leaking into a use case, no Program.cs line bleeding into a domain record, is what keeps the service defensible when the model surface shifts again in eighteen months.

Dependency Injection Lifetimes

The five seams that decide whether the agentic service runs cleanly all sit in the DI container. The lifetimes are not interchangeable.

IChatClient is Singleton. The AddChatClient extension registers the pipeline as a singleton by default, and the framework's own XML doc says exactly that: "The client is registered as a singleton service." Per request state lives in the ChatOptions and IEnumerable<ChatMessage> passed into GetResponseAsync or GetStreamingResponseAsync. The FunctionInvokingChatClient carries instance configuration, AllowConcurrentInvocation, MaximumIterationsPerRequest, but its per invocation context is tracked in an AsyncLocal<FunctionInvocationContext?>, so the singleton lifetime is safe under concurrent requests.

ChatClientAgent is Singleton. The Microsoft.Agents.AI ChatClientAgent from Article 1 is a thin sealed class over IChatClient. Its per conversation state lives in the AgentSession callers pass into RunAsync and RunStreamingAsync, not on the agent instance.

AgentSessionStore is Singleton. The Redis backed or in memory store from Article 4 is a stateless wrapper over a connection multiplexer. The persistence layer is the source of state; the store object itself is not.

AgentSession is per conversation, resolved at runtime, not registered. Sessions live and die with the conversation, not with the request. Application code resolves them from the store using a conversation identifier; they do not have a DI lifetime because they are not DI services. The session is an entity; the store is the service.

Tools registered as AIFunction instances are Singleton when stateless and resolved from scope when they need request scoped dependencies. The wrapper pattern is to register the stateful dependency as Scoped and to construct the function inside the request handler with the scoped service captured.

IOptions<T>, IOptionsSnapshot<T>, and IOptionsMonitor<T> are three lifetimes of the same binding. IOptions<T> resolves once at app start. IOptionsSnapshot<T> is "used to access the value of TOptions for the lifetime of a request", the framework's own XML doc, which makes it Scoped. IOptionsMonitor<T> is Singleton with a hot reload event via OnChange(Action<TOptions, string?>). Prompt catalogs and model selection are IOptionsMonitor<T> so a config change rolls out without a redeploy. Static structural settings, connection strings, maximum iteration counts, are IOptions<T>.

The lifetime mismatch the architect catches at review is a Scoped service captured inside a Singleton's constructor, the classic "captive dependency" the .NET container's scope validation mode flags in Development but not in Production. Turning on scope validation in Production is a defensible decision for an agentic service because the cost of a captured stale options instance is an entire production conversation served against the wrong prompt.

Configuration

The configuration sources the generic host reads are fixed in order, last source wins. The framework loads appsettings.json, then appsettings.{EnvironmentName}.json, then optional {ApplicationName}.settings.json and its environment specific overlay if the application name is set, then User Secrets when EnvironmentName == "Development", then environment variables, then command line arguments. The ordering is implemented in HostingHostBuilderExtensions.ApplyDefaultAppConfiguration and is the canonical pattern for Host.CreateApplicationBuilder and WebApplication.CreateBuilder. The architect's lever is which layer carries which kind of value.

Structural defaults live in appsettings.json and ship in the container image. Per environment overrides live in appsettings.Production.json and friends. Secrets do not live in any of those; they live in the cloud secret store and are pulled in by a configuration provider. builder.Configuration.AddAzureKeyVault(new Uri("https://kv.vault.azure.net/"), new DefaultAzureCredential()) from the Azure.Extensions.AspNetCore.Configuration.Secrets package overlays Key Vault secrets onto the configuration root. The same pattern applies to AWS Secrets Manager and HashiCorp Vault via their providers. The discipline is that the API key is never in source, never in the image, and never typed into a CI variable that is not itself protected.

The prompt catalog and the model selection are the two surfaces that change most often without code. IOptionsMonitor<PromptCatalog> bound to a Prompts section gives the operations team a path to roll a prompt version without a deploy: flip the version pointer, the file watcher fires, OnChange callbacks rebuild dependent caches. The same pattern handles model swaps via a ModelSelection record with Provider, ModelId, and Endpoint. The middleware is wired once at startup; the values it reads are resolved fresh on each invocation.

The trap with hot reload is that not every dependent state recomputes on OnChange. A cache key generator that captures the prompt version at registration time will never see a new version come through, because the key was closed over at startup. The fix is to make the generator a function of IOptionsMonitor<T>.CurrentValue, evaluated per request.

Observability

The OpenTelemetry pipeline for the agentic service has three layers. The M.E.AI middleware emits the GenAI semantic conventions tags through its OpenTelemetryChatClient, model id, prompt token count, completion token count, finish reason, on each call. The application code adds its own activity spans through ActivitySource for the use case layer above the chat client. The OpenTelemetry .NET SDK collects both, batches, and exports through the OTLP exporter to the collector.

The wire up is small. services.AddOpenTelemetry() from the OpenTelemetry.Extensions.Hosting package returns the OTel builder. .ConfigureResource(r => r.AddService("agentic-service")) sets the service identity. .WithTracing(t => t.AddSource("YourApp.UseCases").AddSource("Experimental.Microsoft.Extensions.AI").AddOtlpExporter()) subscribes the tracer to both the application's ActivitySource and the M.E.AI source, and ships the spans to the collector. .WithMetrics(m => m.AddMeter("Experimental.Microsoft.Extensions.AI").AddOtlpExporter()) does the same for metrics; the meter name is identical to the trace source name because the M.E.AI middleware constructs both from OpenTelemetryConsts.DefaultSourceName.

The UseOpenTelemetry() extension on ChatClientBuilder is the M.E.AI hook that turns the middleware on. It is one line in the builder pipeline. The OTel SDK in the host process picks up the activity through AddSource because the middleware writes to a known source name. The two halves of the wire up, middleware on the builder, source on the tracer provider, are deliberately separate so the architect can compose them with whatever resource attributes, samplers, and exporters the deployment demands.

The trap on the OTel pipeline is span explosion under streaming. Article 5 covered why the streaming chat span lifetime spans the entire enumeration. The corollary is that per chunk span events on a high traffic streaming endpoint can blow up the collector's queue. The defence is the sampler, ParentBased(TraceIdRatioBased(0.05)) for production traffic, full sampling in staging, and a per event budget cap on chunk level events.

Deployment

The deployment surface is one of two shapes. The first is the unified web host: a single ASP.NET Core process serving the HTTP API, running the SignalR hub from Article 5, and hosting the background workers from Article 4 in the same process. The second is the worker plus gateway split: a Minimal API gateway running the streaming endpoints and SignalR hub, plus worker processes running the agent loop as BackgroundService. The two shapes share the same composition root pattern.

The decision between them is operational, not architectural. The unified host is simpler to deploy: one container, one set of health probes, one log stream. The split is the right shape when the worker fleet scales independently of the gateway, or when a long running agent loop should not share a pod with traffic serving threads. Either shape uses Host.CreateApplicationBuilder(args) for the worker, WebApplication.CreateBuilder(args) for the web host, and the same Microsoft.Extensions.AI, Microsoft.Agents.AI, and OpenTelemetry packages in both projects.

The composition root for the unified web host fits on one screen.

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddAzureKeyVault(
    new Uri(builder.Configuration["KeyVault:Uri"]!),
    new DefaultAzureCredential());

builder.Services.Configure<PromptCatalog>(
    builder.Configuration.GetSection("Prompts"));
builder.Services.Configure<ModelSelection>(
    builder.Configuration.GetSection("Model"));

builder.Services.AddChatClient(sp =>
{
    var model = sp.GetRequiredService<IOptionsMonitor<ModelSelection>>().CurrentValue;
    return new AzureOpenAIClient(new Uri(model.Endpoint), new DefaultAzureCredential())
        .GetChatClient(model.ModelId)
        .AsIChatClient();
})
.UseOpenTelemetry()
.UseLogging()
.UseDistributedCache()
.UseFunctionInvocation();

builder.Services.AddSingleton<AgentSessionStore, RedisAgentSessionStore>();
builder.Services.AddSingleton<ChatClientAgent>(sp =>
    new ChatClientAgent(sp.GetRequiredService<IChatClient>(),
        new ChatClientAgentOptions { Name = "PlatformCopilot" }));

builder.Services.AddHostedService<OrderInvestigationWorker>();
builder.Services.AddSignalR();

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService("agentic-service"))
    .WithTracing(t => t
        .AddSource("PlatformCopilot.UseCases")
        .AddSource("Experimental.Microsoft.Extensions.AI")
        .AddOtlpExporter())
    .WithMetrics(m => m
        .AddMeter("Experimental.Microsoft.Extensions.AI")
        .AddOtlpExporter());

builder.Services.AddHealthChecks()
    .AddCheck<AgentLivenessCheck>("agent", tags: new[] { "live" });

var app = builder.Build();
app.MapAgentEndpoints();
app.MapHub<ChatHub>("/hub/chat");
app.MapHealthChecks("/health/live",
    new HealthCheckOptions { Predicate = r => r.Tags.Contains("live") });
app.Run();

Every line of that file answers one of the architect's reviewable questions. Where do secrets come from? Key Vault. Where is the prompt catalog? Prompts section, monitored. What is the model? Model section, hot reloadable. What lifetime is the chat client? Singleton, default. Where does session state live? RedisAgentSessionStore, singleton over a Redis multiplexer. What runs in the background? OrderInvestigationWorker from Article 4. What does streaming use? ChatHub from Article 5. The composition root reads like a series of architectural commitments, each one a single line.

The configuration shape that file binds against is equally small.

{
  "KeyVault": { "Uri": "https://kv-platform-prod.vault.azure.net/" },
  "Model": {
    "Provider": "AzureOpenAI",
    "Endpoint": "https://oai-platform.openai.azure.com/",
    "ModelId": "gpt-4o-2024-11-20"
  },
  "Prompts": {
    "Version": "2026-08-15",
    "Catalog": {
      "Triage": "You are an internal platform copilot.",
      "Summary": "Summarise the resolution in three sentences."
    }
  },
  "Otlp": { "Endpoint": "http://otel-collector.observability:4317" }
}

The PromptCatalog and ModelSelection records on the application side are plain C# records with init only setters, bound by name from the matching configuration sections. Adding a prompt is one entry under Prompts:Catalog. Rolling a prompt version is one change to Prompts:Version. Swapping models is one change to Model:ModelId. The deploy artefact does not change.

Failure Modes, Worst First

The well architected version of this surface is invisible. The failure modes are the ones that surface as production incidents.

The first is the captive dependency. A Scoped service captured into a Singleton's constructor, usually IOptionsSnapshot<T> held by a Singleton agent, silently freezes at construction time. Production traffic serves against the wrong prompt for the lifetime of the process. The defence is validateScopes: true on the service provider in Production, not only Development.

The second is the hot reload that does not propagate. IOptionsMonitor<T>.OnChange fires on the source's reload event. A computed value derived from CurrentValue and cached without an OnChange subscription will serve the stale version forever. The defence is to call CurrentValue at the point of use, never at registration time.

The third is the secret in the prompt history. A user prompt that includes an API key or a customer record ends up in the model provider's request log, in the distributed cache, and in the OpenTelemetry span as a tag value. Once the secret is in a third party log the rotation cost is real. The defence is a pre flight redaction pass on the message list before it reaches GetResponseAsync, plus an OTel tag filter to ensure the span does not carry the raw content.

The fourth is the configuration drift between staging and production. The two appsettings.{Environment}.json files diverge over time. A change made to one without the other surfaces as a "works in staging" incident. The defence is a single source of truth for environment specific values, usually a shared store like Azure App Configuration, with the JSON files reserved for genuinely environment local concerns.

The fifth is the OTel span explosion under streaming. Every chunk on a high traffic endpoint emits a chunk level metric and may emit an event on the active span. The collector queue grows, the exporter drops, the application starts blocking when its buffer fills. The defence is a sampler with a low ratio on production traffic and an explicit cap on per event budget on the streaming span.

The sixth is the silent provider swap. A ModelSelection.ModelId change rolled through hot reload swaps the model on next request without an audit trail. The user facing behaviour shifts. The cost surface shifts. The defence is to emit an ActivitySource event whenever the resolved ModelId differs from the previous value, and to gate the configuration source's write surface so only one place can flip the model.

The seventh is the scope validation bypass. The default for WebApplication.CreateBuilder enables scope validation in Development only. Production runs without it. A Scoped service mistakenly registered as a Singleton dependency does not throw; it just captures and freezes. The defence is the explicit builder.Host.UseDefaultServiceProvider(opts => { opts.ValidateScopes = true; opts.ValidateOnBuild = true; }) line in the composition root, applied to every environment.

The Architect's Checklist

🗓️ The four layer cut, Domain, Application, Infrastructure, Hosting, is enforced by project references; no Application project references Microsoft.AspNetCore.*, no Domain project references Microsoft.Extensions.AI.

🗓️ IChatClient is registered as Singleton through services.AddChatClient(...) and the entire ChatClientBuilder middleware pipeline is wired in one place.

🗓️ ChatClientAgent and AgentSessionStore are both Singleton; AgentSession is resolved per conversation from the store, not registered in DI.

🗓️ Prompt versions and model selection bind to IOptionsMonitor<T> and the dependent values are read from CurrentValue on each invocation, not captured at registration.

🗓️ Secrets come from a configuration provider that overlays at runtime, Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault, never from a checked in file or a CI environment variable.

🗓️ Scope validation is enabled in every environment, not only Development, via UseDefaultServiceProvider(opts => opts.ValidateScopes = true) on the host.

🗓️ The OpenTelemetry pipeline subscribes both the application's own ActivitySource and the Microsoft.Extensions.AI source through .AddSource(...) on the tracer provider builder.

🗓️ The OTel sampler ratio is production tuned; streaming endpoints carry an explicit per event budget cap.

🗓️ User content redaction runs before the messages reach GetResponseAsync and before any span tag carries them.

🗓️ The composition root in Program.cs reads top to bottom and answers every "where does X live" question without opening another file.

🗓️ The unified web host versus worker plus gateway decision is documented as an operational choice with a written trigger for when the split becomes worth its operational cost.

🗓️ Every architectural decision in the reference architecture is defensible against the question "what does the code review say if you got this wrong": the answer is a specific failure mode from the list above.

The Architect's Mental Model

The .NET agentic service is a generic host with the four layer cut, the five DI seams, and one composition root the team can read together. The framework choices, Microsoft Agent Framework over Semantic Kernel, Microsoft.Extensions.AI as the substrate, ASP.NET Core for the HTTP surface, IHostedService for background work, OpenTelemetry for observability, are decisions the architect makes once and lives with for a release cycle. The day to day work of operating the service is configuration changes, prompt version rolls, and model swaps, none of which should require a code change.

The well architected reference is not a starter template. It is the smallest set of files a senior architect can defend in a one hour review. The discipline is the same discipline that has carried Microsoft.Extensions.* for a decade: abstract what changes, register what survives, monitor what moves.

Abstract what changes, register what survives, monitor what moves. Everything else is just Program.cs with the lights on.