Part 3 of Build your own claw and harness with Microsoft Agent Framework.
In Part 2 our personal finance assistant learned to work with your data safely: it reads your portfolio, asks before it trades, and remembers what matters across sessions. It’s useful – but everything it knows is baked into one prompt, it does its work one step at a time, and it can’t reach past the file-access tools to actually reorganize anything.
This part makes the claw more capable along four axes:
- Skills – package know-how (valuation, risk-scoring) as discoverable files the agent loads on demand, including centrally-managed Foundry skills.
- Shell – shell tools, to tidy and restructure files.
- CodeAct – let the agent write and run code to compute answers it can’t just look up.
- Background agents – fan work out to sub-agents that run concurrently, then aggregate.
As before, we only supply what makes our agent ours; the harness provides the machinery. Let’s take them in turn.
Teach it on demand: skills
Stuffing every instruction the assistant might ever need into its system prompt doesn’t scale – it bloats the context and dilutes its focus. Skills solve this: each skill is a small SKILL.md file with a name, a one-line description, and instructions (plus optional reference docs and scripts). The agent sees only the names and descriptions up front, and progressively loads a skill’s full content only when a request matches it.
Our claw gets two file-based skills under the skills/ folder. The skills instruct the agent in how to do risk scoring and valuations.
For more information on skills see Give Your Agents Domain Expertise with Agent Skills in Microsoft Agent Framework and What’s New in Agent Skills: Code Skills, Script Execution, and Approval for Python
Usage
The harness turns a skills provider on by default (it discovers SKILL.md files from the working directory). Here we build our own provider so we can point it at this sample’s skills/ folder and run the skills’ scripts.
In .NET, compose a provider with AgentSkillsProviderBuilder and turn the default one off:
var skillsProvider = new AgentSkillsProviderBuilder()
// File-based skills; SubprocessScriptRunner runs their Python scripts.
.UseFileSkills([skillsDir], scriptRunner: SubprocessScriptRunner.RunAsync)
.Build();
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
DisableAgentSkillsProvider = true, // we supply our own
AIContextProviders = [skillsProvider],
// … file access, tools …
});
In Python, build a SkillsProvider from the same folder and pass it in:
from agent_framework import SkillsProvider
skills_provider = SkillsProvider.from_paths(
skill_paths=[str(skills_dir)],
script_runner=subprocess_script_runner, # lets the skills' scripts run
)
agent = create_harness_agent(
client=client,
skills_provider=skills_provider,
# … file access, tools …
)
Now “Value MSFT for me” makes the agent load the valuation skill, read its guide, run its script, and report a fair-value estimate – and “How risky is my portfolio?” pulls in risk-scoring instead. Nothing about valuation or risk was in the system prompt.
Skills you manage centrally: Foundry skills
File-based skills ship with the agent – to change one, you redeploy. Foundry skills flip that around: skills are published and updated centrally in your Foundry project, and the agent picks them up at runtime. The valuation method can evolve without anyone touching the claw.
Because it needs a Foundry endpoint, we make it opt-in – the sample runs fine on the local skills alone.
For how to publish and manage Foundry skills, see the Foundry skills docs.
In .NET, Foundry skills are discovered live from a Foundry Toolbox MCP endpoint; just add an MCP source to the same builder:
// Opt-in: only when a Toolbox endpoint is configured.
if (!string.IsNullOrWhiteSpace(toolboxUrl))
{
var (mcpClient, _) = await FoundrySkills.ConnectAsync(toolboxUrl, credential);
skillsBuilder.UseMcpSkills(mcpClient); // fold them into the same provider
}
In Python, it’s the same story: connect to the Foundry Toolbox MCP endpoint and add an MCPSkillsSource alongside the local FileSkillsSource:
from agent_framework import (
AggregatingSkillsSource, DeduplicatingSkillsSource,
FileSkillsSource, MCPSkillsSource, SkillsProvider,
)
sources = [FileSkillsSource(str(skills_dir), script_runner=subprocess_script_runner)]
# Opt-in: only when a Toolbox endpoint is configured.
if toolbox_url:
session = await _connect_foundry_toolbox(stack, toolbox_url)
sources.append(MCPSkillsSource(client=session))
source = sources[0] if len(sources) == 1 else AggregatingSkillsSource(sources)
skills_provider = SkillsProvider(DeduplicatingSkillsSource(source))
Either way the agent sees one unified set of skills; it neither knows nor cares which ones came from disk and which were managed in Foundry.
Skills aren’t only for domain how-tos – a skill can just as easily carry general rules about how the agent should behave. Because Foundry skills update centrally, governance rules like this are exactly the kind of thing you’d manage there: tighten the policy once and every running claw picks it up, no redeploy. To try it, publish a skill named financial-agent-rules to your Foundry toolbox:
---
name: financial-agent-rules
description: General rules about how you should behave as a financial agent. Use this skill for all requests.
---
You should politely refuse to answer any questions unrelated to finance, managing portfolios or managing confirmations.
Because its description says “Use this skill for all requests”, the agent loads it on every turn. Once it’s published and Foundry skills are enabled (set FOUNDRY_TOOLBOX_MCP_SERVER_URL), ask the claw something off-topic like “What’s the capital of France?” and it will politely decline and steer you back to finance.
Reach into the file system: shell
File access lets the claw read and write individual files, but reorganizing a messy folder – moving, renaming, batching – is exactly what a shell is for. The user’s trade confirmations pile up as a flat heap of inconsistently-named files:
working/confirmations/
trade confirmation 1.txt
conf_AAPL.txt
copy of trade 3.txt
SPY sell.txt
…
The harness can expose a shell as an (approval-gated) run_shell tool. Letting an agent run shell commands is powerful and dangerous, so we hem it in two ways: a confined working directory (every command is re-anchored to the confirmations vault and can’t escape it) and a deny-list policy that pre-filters obviously destructive commands.
In .NET, configure a LocalShellExecutor and pass it as the ShellExecutor:
await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
WorkingDirectory = vaultDir,
ConfineWorkingDirectory = true, // can't escape the vault
Policy = new ShellPolicy(denyList:
[
@"\brm\s+-rf\b", @"\bsudo\b", @":\(\)\s*\{", @"\bmkfs\b", @">\s*/dev/sd",
]),
Timeout = TimeSpan.FromSeconds(15),
});
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
ShellExecutor = shell, // exposed as the approval-gated run_shell tool
// … skills, file access, tools …
});
In Python, a LocalShellTool plays the same role:
from agent_framework_tools.shell import LocalShellTool, ShellPolicy
shell = LocalShellTool(
workdir=str(vault_dir),
confine_workdir=True, # can't escape the vault
policy=ShellPolicy(denylist=[
r"\brm\s+-rf\b", r"\bsudo\b", r":\(\)\s*\{", r"\bmkfs\b", r">\s*/dev/sd",
]),
timeout=15,
)
agent = create_harness_agent(
client=client,
shell_executor=shell, # exposed as the approval-gated run_shell tool
# … skills, file access, tools …
)
The policy is a UX guardrail, not a security boundary. A deny-list catches obvious mistakes, but it won’t stop a determined or cleverly-worded command. Real isolation comes from the confined working directory and the approval prompt – and for untrusted input, a sandboxed executor like DockerShellExecutor (.NET) or DockerShellTool (Python).
Now “Tidy up my trade confirmations” lets the agent inspect the folder, propose a plan, and (with your approval on each command) move the files into a year/month layout renamed to YYYY-MM-DD_TICKER_BUY|SELL.txt.
Let it compute: CodeAct
Some questions aren’t a lookup – they’re a calculation. “What’s my portfolio worth?” or “what was my return on this position?” are better answered by running a little code than by asking the model to do arithmetic in its head. CodeAct gives the agent a sandboxed interpreter it can write and run code in.
CodeAct runs model-authored code in a sandbox, and we wire it in as a context provider in both languages.
In .NET, CodeAct uses Hyperlight (a micro-VM, so it needs hardware virtualization). The guest module path is resolved automatically from the Hyperlight.HyperlightSandbox.Guest.Python NuGet package:
using HyperlightSandbox.Guest.Python;
using Microsoft.Agents.AI.Hyperlight;
var codeAct = new HyperlightCodeActProvider(
HyperlightCodeActProviderOptions.CreateForWasm(PythonGuestModule.GetModulePath()));
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
AIContextProviders = [skillsProvider, codeAct],
// … shell, file access, tools …
});
In Python, Monty is a pure, cross-platform interpreter – no hypervisor required – added as a context provider:
from agent_framework_monty import MontyCodeActProvider
context_providers = [skills_provider, MontyCodeActProvider(approval_mode="never_require")]
agent = create_harness_agent(
client=client,
context_providers=context_providers,
# … shell, file access, tools …
)
With CodeAct on, “Work out the total value of my portfolio” lets the agent read the holdings, write a few lines of Python to multiply shares by price and sum them, run it, and report the result – arithmetic it can show its working for, rather than guess.
For more ideas on how to use CodeAct, read CodeAct in Agent Framework: Faster Agents with Fewer Model Turns
Do many things at once: background agents
Asking “Research MSFT, NVDA and SPY” one ticker at a time is slow, and folding all that web searching into the main agent muddies its context. The harness supports background agents: sub-agents you hand to the claw so it can delegate units of work that run concurrently and report back.
We build a lean, web-search-only research agent – a plain chat-client agent with just the web search tool (no harness machinery needed):
// ResearchAgent.Create(...)
AIAgent research = chatClient.AsAIAgent(
name: "TickerResearchAgent",
description: "Searches the web for recent news about a single stock ticker.",
instructions: "You research a single ticker and return 3-4 factual bullet points.",
tools: [new HostedWebSearchTool()]); // the only tool it needs
Then we hand it to the main claw via BackgroundAgents:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
BackgroundAgents = [research], // exposes the background_agents_* tools
// … skills, shell, file access, tools …
});
In Python it’s the background_agents argument:
research_agent = Agent(
client,
name="TickerResearchAgent",
description="Searches the web for recent news about a single stock ticker.",
instructions="You research a single ticker and return 3-4 factual bullet points.",
tools=[client.get_web_search_tool()], # the only tool it needs
)
agent = create_harness_agent(
client=client,
background_agents=[research_agent], # exposes the background_agents_* tools
# … skills, shell, file access, tools …
)
This gives the main agent a set of background_agents_* tools: it can start a research task per ticker, let them run in parallel, check on them, and collect the results – then summarize all three together. The fan-out is the agent’s decision; the harness handles the plumbing.
Run it
.NET
cd dotnet
dotnet run --project samples/02-agents/Harness/BuildYourOwnClaw/Claw_Step03_ScalingCapabilities
Python
uv run python/samples/02-agents/harness/build_your_own_claw/claw_step03_scaling_capabilities.py
Then try these in order (the sample starts in execute mode – quick lookups don’t need a plan):
Value MSFT for me. – the agent loads the valuation skill, runs its script, and reports a
fair-value estimate.
How risky is my portfolio? – it reads portfolio.csv and loads the risk-scoring skill./mode plan, then Tidy up my trade confirmations. – switching to plan mode first makes the agent inspect working/confirmations/ and propose a reorganization plan before touching anything; once you approve it switches to execute and uses the shell to move and rename the files, prompting you to approve each command.
Work out the total value of my portfolio. – it writes and runs Python to compute the answer.
Research MSFT, NVDA and SPY and summarize the latest news. – it fans the tickers out to the background research agent and aggregates the findings.
What's the capital of France? – with the financial-agent-rules Foundry skill published and enabled (see below), the agent loads it, recognizes the question is off-topic, and politely declines, steering you back to finance.
To enable the opt-in Foundry skills: set FOUNDRY_TOOLBOX_MCP_SERVER_URL.
The runnable samples
Use these building blocks in your own agent
As always, none of this is locked inside the harness. Each capability is a plain context provider or an executor/tool you can pick up on its own. Here’s where to find them:
| Feature |
.NET (type — namespace) |
Python (import) |
| Skills |
AgentSkillsProvider / AgentSkillsProviderBuilder — Microsoft.Agents.AI (MCP skills via Microsoft.Agents.AI.Mcp) |
from agent_framework import SkillsProvider, MCPSkillsSource |
| Shell |
LocalShellExecutor / ShellPolicy — Microsoft.Agents.AI.Tools.Shell |
from agent_framework_tools.shell import LocalShellTool, ShellPolicy |
| CodeAct |
HyperlightCodeActProvider — Microsoft.Agents.AI.Hyperlight |
from agent_framework_monty import MontyCodeActProvider |
| Background agents |
BackgroundAgentsProvider — Microsoft.Agents.AI |
from agent_framework import BackgroundAgentsProvider |
In .NET, skills and background agents ship in the Microsoft.Agents.AI package, the shell in Microsoft.Agents.AI.Tools.Shell, and Hyperlight CodeAct in Microsoft.Agents.AI.Hyperlight. In Python, skills and background agents come from agent-framework, the shell from agent-framework-tools, and Monty CodeAct from agent-framework-monty. The providers plug in through an agent’s context providers (and the shell as an executor) – the same wiring the harness does on your behalf.
What’s next
Our claw can now teach itself new skills, restructure files, compute answers it writes itself, and work in parallel. In the final part we make it production-ready: observability with traces and logs, governance and data protection, evaluation, and deployment as a hosted Foundry agent.
The series
Part of Build your own claw with Microsoft Agent Framework:
The post Agent Harness: Scaling the claw or harness capabilities appeared first on Microsoft Agent Framework.
Log in
