AI Agent - Aug 3, 2026

Microsoft Agent Framework Harness: Python and .NET Guide

Q: How do I create a Harness agent in Python and .NET?

Python uses create_harness_agent(client=..., agent_instructions=..., tools=...). .NET wraps an IChatClient with AsHarnessAgent(new HarnessAgentOptions { ... }). Pin and test the exact packages because optional capabilities and install flags can have different lifecycle states.

Quick answer

Use the Microsoft Agent Framework Harness when one Python or .NET agent must carry a long task across many model calls and needs a coordinated runtime for history, planning, memory, skills, approvals, and tracing. Microsoft released the stable Harness core on July 22, 2026.

The shortest current entry points are:

agent = create_harness_agent(
    client=client,
    agent_instructions="Work only inside the approved repository.",
    tools=[read_file, run_tests],
)

var agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Instructions = "Work only inside the approved repository.",
    Tools = [readFile, runTests]
});

That API surface does not make every optional capability production-ready. Microsoft’s release post said background agents, file access, looping, and shell tools were not part of the fully released set and could emit lifecycle warnings. Current Learn pages expose configuration for those features. Pin the exact dependency, review its warnings, and treat each optional tool as a separate deployment decision.

For the wider product architecture, start with the Microsoft Agent Framework guide.

What the Harness adds

The Harness wraps a model client with an opinionated set of components for long-running work:

Capability	What it does	Boundary to verify
Function invocation	Runs registered tools through the agent loop	Tool schema and authorization remain yours
Service-call history	Persists context across calls	Choose storage, retention, tenant isolation, and deletion
Compaction	Summarizes history when a configured token budget or custom strategy activates	A compacted summary can omit evidence; test recovery and auditability
Todo and mode	Tracks work and operating state	A plan is not proof that an action completed
File memory and skills	Loads reusable context or procedures	File access, script execution, and tool authority stay separate
Web search	Adds provider-backed search when the inference service supports it	Source trust, retrieval logs, data egress, and prompt injection
Tool approval	Pauses or auto-approves eligible calls	Disable broad auto-approval for consequential tools
OpenTelemetry	Emits runtime traces	Redact secrets and sensitive prompts before export

Compaction is not universally active merely because the Harness is present. Configure a token budget or a custom compaction strategy, then test what remains available after compaction. Likewise, web search can appear in the Harness configuration but only works when the selected inference service supports it.

A safer setup sequence

Pin a reviewed Python or .NET package set and record its lifecycle warnings.
Begin with no shell, file-write, URL-fetch, background, or looping capability.
Add one read-only tool with a narrow schema and an isolated test workspace.
Disable heuristic or standing auto-approval for tools that can change state.
Set model-call, tool-call, token, time, and loop ceilings outside the model.
Add storage with tenant boundaries, encryption, retention, and deletion tests.
Enable OpenTelemetry with secret and personal-data redaction.
Test cancellation, retry, duplicate calls, partial failures, and resume behavior.

Tool approval can offer a standing “do not ask again” choice and heuristic auto-approval. Those are convenience features, not authorization substitutes. Keep approval scoped to an exact tool, resource, identity, environment, and time window; require a new decision when scope changes.

Shell, files, and looping

Shell and file tools create an operating-system boundary, not only a prompt boundary. If they are necessary:

run the agent in a disposable container or restricted service identity;
mount only the required working directory;
default to read-only and allow writes to explicit paths;
deny outbound network access unless a destination is required;
validate command arguments outside the model;
log requested and executed operations separately;
require human approval for deletion, deployment, credentials, and external messages.

Microsoft’s Learn documentation explicitly warns that a command deny list is not a security boundary. It can reduce accidental use, but it cannot replace process isolation, filesystem permissions, network policy, and a narrow service identity.

Looping and background work also need hard ceilings. Set iteration, elapsed-time, token, and cost budgets in code, and make cancellation effective between tool calls. The agent’s todo list or “done” message should never be the only completion signal; verify the target system and persist a result receipt.

Validate before production

Build a fixed evaluation set covering normal completion, tool rejection, missing files, malicious instructions in retrieved content, compaction, interrupted work, duplicate tool delivery, and revoked credentials. Assert not just the final answer but also which tools were called, with what scope, and whether the resulting state matches the receipt.

Use declarative workflows when the sequence is known and reviewers need a YAML representation. Use the Harness versus Squad decision guide when the real question is one configurable runtime versus a coordinator with persistent specialists.

Frequently asked questions

What is the Microsoft Agent Framework Harness?

The Harness is an opinionated Agent Framework runtime for long, multi-step work. Its stable Python and .NET core combines tool invocation, service-call history, optional compaction, task planning, file memory, skills, approvals, and OpenTelemetry around a chat client.

How do I create a Harness agent in Python and .NET?

Python uses create_harness_agent(client=…, agent_instructions=…, tools=…). .NET wraps an IChatClient with AsHarnessAgent(new HarnessAgentOptions { … }). Pin and test the exact packages because optional capabilities and install flags can have different lifecycle states.

Are shell and file tools safe by default in the Agent Framework Harness?

No. Keep them disabled unless required, confine file and shell access to an isolated working directory, use explicit approvals and operating-system sandboxing, and treat command deny lists only as a user-experience filter—not as a security boundary.

Official sources

Source check: August 3, 2026. Verify the current package versions, warnings, provider support, optional-feature lifecycle, storage, tools, approvals, telemetry, and isolation before deployment.