Building the Harness: A Production-Minded AI Agent Architecture in .NET

Steve Kaschimer — Tue, 29 Sep 2026 16:22:53 +0000

This is the implementation companion to the LinkedIn article The Model Isn’t Your Agent. The Harness Is. That article makes the architectural argument that a production agent is much more than the model providing its reasoning.

Here, we’re going to build that idea.

Most introductory agent examples begin with the model.

Create a client, send it a prompt, give it a function or two, and start looping until the model stops requesting tools.

That is useful for learning an SDK. It is not the architecture I would want governing an agent capable of doing real work.

Instead, let’s start from the outside and work inward.

The system we’re going to build has a simple rule:

The model can decide what it wants to do. The harness determines what it can do.

That means identity, policy, budgets, tools, evidence, and verification belong outside the model.

Our first architecture looks like this:

There is deliberately no arrow that goes directly from the model to an external system.

That boundary is the architecture.

Start With the Contract

Let’s resist the temptation to create an OpenAI, Anthropic, or Azure client.

Our application should not begin by caring which model performs the work. It should begin with the contract for performing agent work.

public interface IAgentHarness
{
    Task<AgentResult> ExecuteAsync(
        AgentRequest request,
        AgentIdentity identity,
        CancellationToken cancellationToken = default);
}

The request can stay simple:

public sealed record AgentRequest(
    string Goal,
    IReadOnlyDictionary<string, object>? Context = null);

And our result should tell us more than whatever text the model happened to generate:

public sealed record AgentResult(
    bool Succeeded,
    string Summary,
    IReadOnlyList<Evidence> Evidence,
    AgentExecutionMetrics Metrics);

Already, we have made an architectural decision.

The output of our agent is not just text.

It includes evidence and execution metrics because we eventually want to answer two different questions:

What did the agent conclude?
Why should we trust what happened?

That distinction will matter later.

Give the Agent an Identity

Before the harness does anything, we need to know who is acting.

public sealed record AgentIdentity(
    string AgentId,
    string SubjectId,
    IReadOnlySet<string> Roles);

AgentId identifies the agent performing the work.

SubjectId identifies the human or workload on whose behalf the work is occurring.

Those identities are deliberately separate.

An enterprise implementation might eventually map them to Entra identities, workload identities, claims, delegated authorization, or another identity provider. For now, the important thing is that identity is part of the execution contract rather than hidden somewhere inside configuration.

Next we define authority.

public sealed record AgentPolicy(
    IReadOnlySet<string> AllowedTools,
    IReadOnlySet<string> AllowedResources,
    bool NetworkAccessAllowed,
    bool RequiresApprovalForWrites);

Now the agent’s permissions exist independently of anything the model was told in its prompt.

That is important enough to make explicit.

Instructions describe desired behavior. Policy defines permitted behavior.

The model may receive both, but only one should decide whether an action actually occurs.

Build an Execution Context

Every agent invocation needs a bounded environment describing what is true for that particular execution.

public sealed record ExecutionBudget(
    int MaxModelCalls,
    int MaxToolCalls,
    TimeSpan MaxDuration,
    decimal MaxEstimatedCost);

Then we can assemble the information governing one execution:

public sealed record AgentExecutionContext(
    AgentIdentity Identity,
    AgentPolicy Policy,
    ExecutionBudget Budget,
    string TraceId,
    DateTimeOffset StartedAt);

Notice what we’re doing.

The model isn’t receiving unlimited execution and being asked to behave responsibly. The harness is creating a finite envelope in which reasoning can occur.

That gives us another useful principle:

Autonomy should be expressed as a budget, not an absence of limits.

A production implementation could make these budgets considerably richer. Token limits, wall-clock deadlines, network requests, compute consumption, model spend, delegated-agent count, retry count, or resource-specific quotas could all belong here.

The mechanism matters less than making the boundary explicit.

Put the Model Behind an Interface

Now we can finally introduce a model.

But instead of coupling the harness to a particular provider, we’ll define what we need from one.

public interface IReasoningModel
{
    Task<ModelDecision> DecideAsync(
        AgentState state,
        AgentExecutionContext context,
        CancellationToken cancellationToken);
}

A model decision can produce one of several outcomes:

public abstract record ModelDecision;

public sealed record Complete(string Summary)
    : ModelDecision;

public sealed record InvokeTool(
    string ToolName,
    IReadOnlyDictionary<string, object> Arguments)
    : ModelDecision;

public sealed record CannotComplete(string Reason)
    : ModelDecision;

This is intentionally provider-neutral.

An OpenAI implementation might translate a tool call into InvokeTool. An Anthropic implementation could do the same. A local model could satisfy the same contract.

Eventually, we could introduce a router:

public interface IModelRouter
{
    Task<IReasoningModel> SelectAsync(
        AgentState state,
        AgentExecutionContext context,
        CancellationToken cancellationToken);
}

Now model selection becomes policy.

A cheap model might handle classification. A stronger model might handle complex planning. A failed verification step might cause the router to escalate.

The rest of the application does not need to know.

The model becomes an execution dependency rather than the architecture itself.

That is exactly where I want it.

Tools Need Contracts Too

Now we reach the boundary where reasoning becomes action.

Let’s define a tool:

public interface IAgentTool
{
    string Name { get; }

    Task<ToolResult> ExecuteAsync(
        IReadOnlyDictionary<string, object> arguments,
        AgentExecutionContext context,
        CancellationToken cancellationToken);
}

And a result:

public sealed record ToolResult(
    bool Succeeded,
    object? Value,
    IReadOnlyList<Evidence> Evidence);

The harness owns a registry of available tools:

public interface IToolRegistry
{
    IAgentTool GetRequiredTool(string name);
}

Here is where the architecture becomes interesting.

Suppose the model requests:

Tool: deploy-production
Environment: production
Version: 2.4.1

The model has made a decision, but nothing has happened yet.

Before execution, the harness evaluates policy.

public sealed class ToolAuthorizer
{
    public bool IsAllowed(
        string toolName,
        AgentExecutionContext context)
    {
        return context.Policy.AllowedTools.Contains(toolName);
    }
}

If deploy-production is not in the allowed set, the answer is no.

Not “please reconsider.”

Not another prompt telling the model that production is dangerous.

No.

The tool does not execute.

A denied action should fail at the authority boundary, not depend on the model agreeing that it was denied.

That difference is the heart of the harness.

Assemble the Execution Loop

Now we have enough pieces to create a simplified implementation.

public sealed class AgentHarness : IAgentHarness
{
    private readonly IModelRouter _models;
    private readonly IToolRegistry _tools;
    private readonly ToolAuthorizer _authorizer;
    private readonly IAgentPolicyProvider _policies;

    public AgentHarness(
        IModelRouter models,
        IToolRegistry tools,
        ToolAuthorizer authorizer,
        IAgentPolicyProvider policies)
    {
        _models = models;
        _tools = tools;
        _authorizer = authorizer;
        _policies = policies;
    }

    public async Task<AgentResult> ExecuteAsync(
        AgentRequest request,
        AgentIdentity identity,
        CancellationToken cancellationToken = default)
    {
        var policy = await _policies.GetPolicyAsync(
            identity,
            cancellationToken);

        var context = new AgentExecutionContext(
            identity,
            policy,
            new ExecutionBudget(
                MaxModelCalls: 10,
                MaxToolCalls: 5,
                MaxDuration: TimeSpan.FromMinutes(2),
                MaxEstimatedCost: 1.00m),
            Activity.Current?.TraceId.ToString()
                ?? Guid.NewGuid().ToString("N"),
            DateTimeOffset.UtcNow);

        var state = AgentState.Start(request);
        var evidence = new List<Evidence>();

        while (!state.IsComplete)
        {
            cancellationToken.ThrowIfCancellationRequested();

            EnsureWithinBudget(state, context);

            var model = await _models.SelectAsync(
                state,
                context,
                cancellationToken);

            var decision = await model.DecideAsync(
                state,
                context,
                cancellationToken);

            switch (decision)
            {
                case Complete complete:
                    state.Complete(complete.Summary);
                    break;

                case CannotComplete failed:
                    state.Fail(failed.Reason);
                    break;

                case InvokeTool invocation:
                    await ExecuteToolAsync(
                        invocation,
                        state,
                        context,
                        evidence,
                        cancellationToken);
                    break;
            }
        }

        return CreateResult(state, evidence, context);
    }
}

There is nothing particularly magical here.

That is intentional.

The harness is orchestration code.

Its job is not to be intelligent. Its job is to make intelligence governable.

Prove That the Boundary Works

Let’s create an identity for a coding agent.

var identity = new AgentIdentity(
    AgentId: "coding-agent-01",
    SubjectId: "developer-123",
    Roles: new HashSet<string>
    {
        "RepositoryContributor"
    });

Its policy allows repository operations:

var policy = new AgentPolicy(
    AllowedTools: new HashSet<string>
    {
        "read-file",
        "write-file",
        "run-tests"
    },
    AllowedResources: new HashSet<string>
    {
        "repository:current"
    },
    NetworkAccessAllowed: false,
    RequiresApprovalForWrites: false);

The model receives a task:

Fix the failing integration test and verify the solution.

During reasoning, it decides that deploying the application would be useful and requests:

deploy-production

Our authorization check runs:

if (!_authorizer.IsAllowed(
        invocation.ToolName,
        context))
{
    state.RecordDeniedAction(
        invocation.ToolName,
        "Tool is not permitted by execution policy.");

    return;
}

The model requested the action, but the action did not happen.

That is not an alignment success.

It is an architecture success.

We did not need the model to behave correctly for the system to remain within its authority boundary.

That is the property we want.

Add Observability

Once the harness controls the execution path, observability becomes much easier.

.NET already gives us a natural abstraction through ActivitySource.

private static readonly ActivitySource ActivitySource =
    new("Example.AgentHarness");

Each execution gets an activity:

using var activity =
    ActivitySource.StartActivity("agent.execute");

activity?.SetTag(
    "agent.id",
    context.Identity.AgentId);

activity?.SetTag(
    "agent.subject_id",
    context.Identity.SubjectId);

Model calls become child activities:

using var modelActivity =
    ActivitySource.StartActivity("agent.model");

modelActivity?.SetTag(
    "agent.model.provider",
    model.Provider);

modelActivity?.SetTag(
    "agent.model.name",
    model.Name);

Tool calls do the same:

using var toolActivity =
    ActivitySource.StartActivity("agent.tool");

toolActivity?.SetTag(
    "agent.tool.name",
    invocation.ToolName);

toolActivity?.SetTag(
    "agent.tool.allowed",
    allowed);

With an OpenTelemetry exporter configured, the execution starts looking like any other distributed workload:

agent.execute
 ├── agent.model
 ├── agent.tool:read-file
 ├── agent.model
 ├── agent.tool:write-file
 ├── agent.tool:run-tests
 ├── agent.model
 └── agent.complete

Now imagine the agent delegates work to another agent.

That should not create a separate mystery.

It should create another span.

agent.execute
 ├── agent.model
 ├── agent.delegate
 │    └── agent.execute
 │         ├── agent.model
 │         └── agent.tool
 ├── agent.verify
 └── agent.complete

Every consequential agent task should have a trace ID.

Once agents become distributed systems, distributed tracing becomes one of the most obvious tools we already know how to use.

Evidence Is Different from Telemetry

Tracing tells us what happened. Evidence tells us why we should trust the result.

Let’s make that explicit:

public sealed record Evidence(
    string Type,
    string Source,
    string Description,
    DateTimeOffset ObservedAt,
    string? ArtifactReference = null);

Our coding agent might return:

Evidence
├── source-change
│   └── src/Orders/OrderValidator.cs
├── test-result
│   └── 147 passed, 0 failed
└── build-result
    └── succeeded, 0 warnings

That is much more useful than:

I fixed the problem.

The model’s confidence is not our evidence. But, the build result is, the test result is, the artifact is.

When deterministic evidence exists, prefer it over the model’s opinion about its own work.

That principle applies far beyond coding agents.

An infrastructure agent can return deployment state.
A data agent can return query results and source lineage.
A security agent can return scanner output.
A business-process agent can return transaction identifiers.

The model explains what happened.

The system proves what it can.

Verification Comes After Execution

Evidence also gives us somewhere to attach verification.

public interface IAgentVerifier
{
    Task<VerificationResult> VerifyAsync(
        AgentResult result,
        CancellationToken cancellationToken);
}

For our coding agent, a verifier might require:

public sealed class CodingAgentVerifier : IAgentVerifier
{
    public Task<VerificationResult> VerifyAsync(
        AgentResult result,
        CancellationToken cancellationToken)
    {
        var testsPassed = result.Evidence.Any(
            e => e.Type == "test-result"
              && e.Description.Contains("0 failed"));

        var buildPassed = result.Evidence.Any(
            e => e.Type == "build-result"
              && e.Description.Contains("succeeded"));

        return Task.FromResult(
            testsPassed && buildPassed
                ? VerificationResult.Passed()
                : VerificationResult.Failed(
                    "Required execution evidence is missing."));
    }
}

Notice who is not performing this verification.

The model that wrote the code.

That separation is deliberate.

**The component producing the work should not be the only component deciding whether the work is correct.**

Independent verification is one of the easiest ways to turn agent confidence into system confidence.

What About the Sandbox?

So far we have controlled which tools may execute, but production agents need another boundary underneath that.

Suppose run-tests eventually invokes a shell command.

Policy might authorize the tool, but the resulting process still needs constraints. Filesystem scope, network access, credentials, environment variables, process lifetime, memory, CPU, and potentially container or VM isolation all become relevant.

That boundary belongs beneath the tool:

The sandbox is where logical authority becomes physical enforcement.

A complete implementation could use containers, OS sandboxing, ephemeral VMs, cloud-hosted execution environments, or another isolation mechanism depending on the workload.

The important architectural rule is simpler:

**Never make the prompt your sandbox.**

If a coding agent should not reach the public Internet, the network boundary should enforce that.

If it should only modify one repository, the filesystem boundary should enforce that.

If it should not see production credentials, those credentials should never enter its environment.

We want constraints that remain true even when the model behaves unexpectedly.

The Harness We Have Built

Our small example now has most of the pieces from the original architecture.

There is plenty more we could add.

Durable memory.
Human approvals.
Delegated agents.
MCP servers.
A2A communication.
Retry policies.
Circuit breakers.
Persistent state.
Cost-aware model routing.
Recovery and compensation.
Production evaluation.

None of those additions require us to abandon the architecture.

They fit inside it. That is the point.

Questions I Would Ask Before Shipping an Agent

Before giving an agent meaningful authority, I would want clear answers to a handful of questions.

Who is acting?
Can I distinguish the user, the agent, and any delegated agents involved in the execution?
What can it do?
Is authority enforced by infrastructure, or am I relying on instructions in a prompt?
Where can it execute?
What constrains its filesystem, network, credentials, processes, and external resources?
What can it spend?
Are model calls, tool calls, execution time, retries, and money bounded?
What evidence does it produce?
Can the system demonstrate what actually happened rather than merely report the model’s interpretation?
Can I trace it?
Can I follow one task across models, tools, agents, and external systems?
Who verifies the result?
Is there independent verification where deterministic evidence is available?
How do I stop it?
Can execution be cancelled cleanly?
How do I recover?
If the agent succeeds halfway through a multi-step operation and then fails, what happens next?

If those questions do not have good answers, improving the prompt is probably not the highest-priority engineering task.

The Model Is Still Important

None of this means the model does not matter.

Of course it matters.

Better reasoning can improve planning, tool selection, recovery, interpretation, and the quality of the final result. Different models have different capabilities, economics, latency, and failure modes.

But the model should be allowed to improve without forcing us to redesign the entire application around it.

The harness gives us that separation.
A stronger model can replace the current one.
A router can choose among several.
A local model can handle one workload while a frontier model handles another.

The surrounding contracts remain. Identity remains. Policy remains. Evidence remains. Tracing remains. Verification remains.

A mature agent architecture lets the intelligence change without rebuilding the control system around it.

That is the architecture I want when an AI system moves beyond answering questions and starts doing real work.

Because at that point, the hardest engineering problem is no longer making the model capable of acting.

It is making sure the system around it knows exactly what happens when it does.

DEV Community: Steve Kaschimer