Microsoft Agent Framework Harness Guide

Direct answer: Microsoft Agent Framework is now more than an agent SDK. Its Harness Agent supplies a runtime for long-running, tool-using work, including planning, todo tracking, context compaction, file access, memory, approvals, and telemetry. The framework also provides explicit workflows, MCP integrations, and model-provider adapters. For teams moving from ad hoc agent loops to production systems, the main value is a common execution and governance layer—not another prompt wrapper.

Key takeaways

• Microsoft Agent Framework combines agent APIs, a batteries-included Harness Agent, graph or functional workflows, and provider integrations.
• The official documentation supports Python, .NET, and a Go public preview, but feature parity is not complete across languages.
• Python 1.9.0 added tool approval middleware, shell integration, loop middleware, MCP sampling guardrails, and safer FileAccess behavior; verify breaking changes before upgrading.
• The Harness Agent is useful for multi-step work, but shell access, background agents, and autonomous looping should remain opt-in and bounded.
• MCP tools need explicit approval and data-flow review. A framework does not make third-party tools trustworthy by default.

What Microsoft Agent Framework actually is

Microsoft positions Agent Framework as the successor to AutoGen and Semantic Kernel. It keeps simple agent abstractions while adding session state, middleware, telemetry, model clients, context providers, MCP clients, and explicit workflow composition.

The important distinction is between an agent and a harness. An agent calls a model, interprets the result, and may invoke tools. A harness coordinates the repeated execution around that model: it maintains state, records tool activity, compacts context, asks for approval, handles files, and decides when a run should continue or stop.

That division matters because production failures often happen outside the model call. A tool may receive the wrong arguments, a loop may run too long, a file may contain sensitive data, or a resumed session may use stale state. Centralizing those controls gives a team one place to inspect and test them.

Microsoft’s current overview groups the framework into four areas:

1. Agents for model-backed conversations and tool use.
2. Harness Agents for long, multi-step tasks with built-in operational capabilities.
3. Workflows for explicit execution paths between agents and functions.
4. Integrations for models, hosted agents, tools, context, middleware, evaluations, and UI layers.

Architecture: where the harness fits

The model remains responsible for interpreting instructions and proposing actions. The surrounding runtime should enforce boundaries that a prompt cannot reliably enforce: which tools are visible, which calls require approval, how many rounds are allowed, what is persisted, and where traces are sent.

This is the same architectural concern that appears in MCP’s stateless transport changes: application state, authorization, and resumable work need explicit boundaries instead of being hidden in a connection or an implicit session.

Install the Python package

For a first Python experiment, install the package in a clean virtual environment and authenticate to the model provider you intend to use:

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4pip install agent-framework

Microsoft’s documentation notes that Agent Framework does not automatically load .env files. Load them yourself or set environment variables in the shell or IDE. Keep provider keys out of source control and use a secret manager in shared environments.

A minimal agent using Microsoft Foundry looks like this:

1import asyncio
2from azure.identity import AzureCliCredential
3from agent_framework import Agent
4from agent_framework.foundry import FoundryChatClient
5
6async def main() -> None:
7    client = FoundryChatClient(
8        project_endpoint="https://your-foundry-service.services.ai.azure.com/api/projects/your-project",
9        model="gpt-5.4-mini",
10        credential=AzureCliCredential(),
11    )
12    agent = Agent(
13        client=client,
14        name="ReleaseAssistant",
15        instructions="Give concise, evidence-based release summaries.",
16    )
17    result = await agent.run("Explain why a release checklist needs rollback steps.")
18    print(result)
19
20if __name__ == "__main__":
21    asyncio.run(main())

The exact client and model depend on your provider. The framework overview lists support for Microsoft Foundry, Anthropic, Azure OpenAI, OpenAI, Ollama, and others. Test the provider adapter independently before adding tools; otherwise a credential or endpoint problem can look like an agent bug.

When to use a Harness Agent instead of a plain agent

Use a plain agent when one model call, possibly with a small set of tools, is enough. Use a Harness Agent when the task needs repeated execution and operational state:

• Planning and todo tracking for a long task.
• File access and file-backed memory.
• Context compaction across many tool results.
• Human approval before selected actions.
• Shell or web tools with explicit policy.
• Background sub-agents or controlled loops.
• OpenTelemetry traces for debugging and operations.

Use a workflow instead when the process is known in advance. For example, “extract requirements, validate schema, run tests, then request approval” is usually safer as an explicit workflow than as an unconstrained agent loop. The framework supports sequential, concurrent, handoff, and other orchestration patterns, so the execution path can be visible in code.

A practical rule is simple: if you can write the process as deterministic functions, do that first. Give the model the narrow decision points that genuinely need language or vision reasoning.

Tool approvals and MCP security

Python 1.9.0 introduced or integrated several relevant controls, including tool approval middleware and MCP sampling guardrails. The release notes say server-initiated MCP sampling is denied by default unless the application supplies an approval path and limits such as maximum tokens and requests.

That default is important. An MCP server should not silently turn one tool call into additional model requests with an independent cost, data-flow, or policy boundary. Review:

• Which tools can read files, invoke shells, or make network requests.
• Whether an MCP server can request sampling or call back into a model.
• Which calls are automatically approved and which require a person.
• Whether approval decisions are scoped to a tool, argument pattern, session, or user.
• How tool results are redacted before entering traces or long-term memory.

The approval layer is not a substitute for least privilege. Give a tool a narrow working directory, restricted credentials, network egress limits, and timeouts. For a useful comparison, Hermes Agent 0.20’s approval and recovery design shows the same principle from a self-hosted workbench perspective: autonomy becomes safer when approvals, loop limits, and recovery behavior are explicit.

Upgrade notes for Python 1.9.0

The official Python 1.9.0 release was published on June 18, 2026. It included:

• AgentLoopMiddleware for rerunning agents in a loop.
• Tool approval middleware and Harness Agent integration.
• Shell-tool integration into the Harness Agent.
• Opt-in AG-UI thread snapshot persistence and hydration.
• Stable orchestration package promotion.
• MCP sampling guardrails that deny server-initiated sampling by default.
• FileAccess alignment with .NET, including directory discovery and recursive search.
• Fixes for structured MCP tool results, empty allowed_tools, declarative workflows, and streamed tool-call rendering.

Several changes are marked breaking. In a staging upgrade, test file discovery, recursive searches, declarative workflows, MCP sampling, and any code that supplies tool approval callbacks. Pin the package set used by production, record the framework version in telemetry, and roll forward only after a representative task suite passes.

The companion .NET release line also added or changed approval behavior, FileAccess integration, durable workflow hosting, MCP authentication samples, and loop integration. Do not assume that a Python example maps one-to-one to .NET or Go. The official overview currently labels Go as public preview and explicitly says declarative agents, RAG, CodeAct, and functional workflows are not yet available there.

Performance, cost, and observability

A harness adds useful work around every model call: state management, tool schemas, approval checks, telemetry, and sometimes compaction. That can increase latency and token usage. Measure at least:

OpenTelemetry is valuable only when spans connect the user request, model call, tool invocation, approval decision, and final outcome. Avoid logging raw secrets or entire private documents just because a trace collector makes it convenient.

For hosted deployments, separate the cost of model inference from the cost of agent execution and tool infrastructure. A cheap model with an uncontrolled loop can cost more than a stronger model that finishes in fewer rounds.

Common errors and debugging checklist

The package imports but the agent cannot run. Verify the provider endpoint, credential chain, deployment name, and required environment variables. Run the smallest no-tool prompt first.

A tool is never called. Check that it was registered, that the model supports tool calling, and that the instruction makes the tool’s purpose unambiguous. Inspect the trace for the tool schema rather than guessing from the final response.

An MCP call is rejected. Check protocol compatibility, server authentication, allowed tools, and approval middleware. If the server requests sampling, verify that your callback deliberately permits it and enforces token and request limits.

A loop never finishes. Set a maximum round count, add a completion evaluator, make the stop condition observable, and test failure paths with a fake tool. Never rely on “the model will know when it is done.”

The upgrade breaks file behavior. Review the 1.9.0 FileAccess changes, especially directory discovery and recursive search. Test path containment and symlink handling in a disposable workspace.

The context becomes expensive. Capture tool output sizes, compact earlier, return structured summaries instead of raw logs, and keep large artifacts outside the prompt with authenticated references.

A safe adoption plan

Start with a read-only assistant and two or three narrow tools. Add traces before adding autonomy. Then introduce approvals for writes, shell commands, network access, and external side effects. Only after those controls are tested should you enable loops, background agents, or durable hosting.

Teams already working with agent infrastructure can pair this framework with verified AI model and developer-tool coverage on essamamdani.com and use agent-plugin packaging patterns when they need portable skills across clients. Keep the tool contract stable and treat each provider adapter as an independently tested component.

FAQ

Is Microsoft Agent Framework the same as AutoGen?

No. Microsoft describes it as the direct successor that combines AutoGen-style agent abstractions with Semantic Kernel’s enterprise features and adds explicit workflows. Migration still requires testing because APIs, state behavior, and package boundaries differ.

Does the Harness Agent make an AI agent safe automatically?

No. It provides useful control points—approvals, limits, telemetry, memory, and context handling—but the application owner must configure permissions, isolation, data retention, and responsible-AI safeguards.

Should I choose Python, .NET, or Go?

Choose Python for the broadest experimentation surface, .NET when your production stack is strongly aligned with Azure and Microsoft services, and Go only after checking its public-preview feature gaps. Validate the exact integrations you need rather than choosing by language preference alone.

Is MCP support included?

MCP clients and integrations are part of the framework, and recent releases added stronger approval and sampling controls. You still need to review each server’s implementation, permissions, authentication, and data handling.

Conclusion

Microsoft Agent Framework’s meaningful contribution is the runtime around the model. The Harness Agent, workflows, MCP controls, approvals, and telemetry address the unglamorous parts that determine whether an agent can be operated safely for more than one demo.

The best production design is not “give the model every tool.” It is a small set of typed capabilities, explicit execution paths, bounded autonomy, reviewable approvals, and traces that explain what happened. Start narrow, pin versions, test breaking changes, and expand only when the evidence from your own task suite supports it.

Sources

• Microsoft Agent Framework overview
• Python 1.9.0 release notes
• .NET 1.11.0 release notes
• InfoQ: Microsoft Agent Framework Harness and Hosted Agents Reach General Availability

Visual credit: Original Mermaid architecture diagram by Essa Mamdani, based on the framework’s documented agent, harness, workflow, integration, approval, and telemetry components.