What if you could build a fully functional AI agent — one that plans, searches the web, calls your own custom tools, and remembers context across sessions — without wiring together a dozen different libraries? That’s the promise of Microsoft Agent Framework’s harness model, and this post walks through exactly how it works.

This is Part 1 of the Build Your Own Claw series. The guiding example is a personal finance assistant, and by the end you’ll have an interactive terminal agent that can look up stock prices, pull in live market news, and build a step-by-step investment plan on request.

What Is a “Harness” and What Is a “Claw”?

The terminology is deliberately visual. A claw is an agent loop — the thing that wraps a language model, connects it to tools, and keeps the conversation going. A harness is the scaffolding Microsoft Agent Framework provides around that loop: function invocation, conversation history, planning, web search, and file memory are all bundled in by default. You supply the two things that make your agent unique — its purpose (instructions) and its domain-specific tools — and the framework handles everything else.

Step 1: Connect to a Model

Every agent starts with a chat client — the component that communicates with an underlying language model. The framework treats this as a standard interface (IChatClient in .NET), so you can point it at Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic, Google Gemini, Ollama, or any other supported provider without changing the agent code.

For the finance assistant, the setup reads two environment variables — FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL — and authenticates using Azure’s DefaultAzureCredential. Run az login locally and it just works; in production, swap in a ManagedIdentityCredential for tighter security.

The key insight here: the harness is provider-agnostic. Switching from Foundry to OpenAI is a one-line change in the client setup — the rest of the agent stays the same.

Step 2: Wrap the Client in the Harness

This is where the framework’s value becomes obvious. A single call — AsHarnessAgent() in .NET or create_harness_agent() in Python — transforms the bare chat client into a full agent. You pass in two things:

• Instructions — a natural language description of what the agent does and how it behaves. For the finance assistant this includes guidance on always verifying numbers with tools, citing sources, and maintaining a watchlist in a watchlist.md memory file.
• A custom tool — a plain function (get_stock_price) that the model can invoke when it needs live data. The framework automatically generates the JSON schema from the function’s signature and parameter descriptions.

In return, the harness activates everything else automatically:

• Web search is added as a hosted tool — ask “Any recent news on NVDA?” and it works out of the box, no extra code required.
• Planning is enabled via a built-in TodoProvider and AgentModeProvider — so a vague request like “Review my watchlist and recommend some stocks to add” becomes a structured, step-by-step plan.
• File memory is wired up so the agent can persist information (like your watchlist) across sessions.
• History persistence is handled per service call.

Nothing about web search or planning required any custom implementation — those capabilities came free the moment the harness was created.

Step 3: Run the Interactive Console

Microsoft Agent Framework ships a ready-made terminal UI — the harness console — designed to be copied and adapted as a starting point for any interface (web app, chat surface, IDE extension, etc.). It outputs in colour by mode: cyan for planning, green for execution, and includes built-in commands like /todos, /mode, and /exit.

A typical interactive session with the finance assistant might look like:

1. Switch to execute mode: /mode execute
2. Ask for a price: “What’s the price of MSFT?” — the agent calls get_stock_price
3. Ask for news: “Any recent news on NVDA?” — the agent uses web search
4. Build a watchlist: “Add MSFT, NVDA and SPY to my watch list” — saved to watchlist.md
5. Switch to plan mode: /mode plan
6. Request analysis: “Review my watchlist and recommend some stocks to add” — the agent plans, asks clarifying questions, then executes

Sessions can be saved to disk with /session-export and restored later with /session-import, preserving conversation history, the watchlist, and all context-provider state.

How Plan Mode Actually Works

Plan mode isn’t magic — it’s structured output. When the agent is in plan mode, the console’s planning observer overrides the response format to request a JSON schema-constrained reply instead of free-form text. The model is forced into one of exactly two shapes:

• Clarification — the model needs more information. It returns one or more questions, each optionally accompanied by suggested choices that the console renders as selectable options.
• Approval — the model has a complete plan. It returns a single summary and the console prompts you to approve before anything executes.

This design makes agent behaviour feel deliberate and safe: the agent gathers what it needs, presents a plan, and only switches to execute mode after you sign off. The PlanningResponse schema ships with the console sample in both .NET and Python, so you can extend or reshape it to match your own UX requirements.

Toggling Features On and Off

Everything the harness enables — todos, planning modes, web search, file memory, file access, and tool approval — is on by default and individually toggleable. If your use case doesn’t need planning or web search, you disable them with a single option flag:

• .NET: DisableTodoProvider, DisableAgentModeProvider, DisableWebSearch, DisableFileMemory, DisableFileAccess, DisableToolApproval
• Python: disable_todo, disable_mode, disable_memory, disable_web_search

The recommended approach is to start with everything enabled and trim to taste once you understand what your agent actually needs.

You Don’t Have to Use the Full Harness

The harness is a convenience layer, not a mandatory container. All of the underlying pieces — web search (a plain tool), planning modes (a context provider), and todos (another context provider) — are individually accessible. You can cherry-pick exactly what you need and plug them into any agent architecture, even one that doesn’t use the harness at all. In .NET, the mode and todo providers live in the Microsoft.Agents.AI package; in Python, everything ships in the agent-framework package.

Try It Yourself

Both the .NET and Python runnable samples are available on GitHub:

• .NET: Claw_Step01_MeetYourClaw
• Python: build_your_own_claw

What Comes Next

The finance assistant can now look things up, search the web, and produce structured plans. But it can’t touch your files directly, and there’s nothing yet preventing it from taking a sensitive action without asking. Part 2 of the series addresses both: granting file access, gating risky operations behind explicit approvals, and adding durable memory so the agent remembers your preferences between sessions.

Source: Microsoft Dev Blogs — Meet your agent harness and claw by Wes Steyn, Principal Software Engineer