{"id":5579,"date":"2026-07-09T06:23:11","date_gmt":"2026-07-09T13:23:11","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/agent-framework\/?p=5579"},"modified":"2026-07-09T07:11:50","modified_gmt":"2026-07-09T14:11:50","slug":"agent-harness-scaling-the-claw-or-harness-capabilities","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/agent-harness-scaling-the-claw-or-harness-capabilities\/","title":{"rendered":"Agent Harness: Scaling the claw or harness capabilities"},"content":{"rendered":"

Part 3 of Build your own claw and harness with Microsoft Agent Framework<\/a>.<\/em><\/p>\n

In Part 2<\/a> our personal finance assistant learned to work with your<\/em> 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<\/em> anything.<\/p>\n

This part makes the claw more capable<\/em> along four axes:<\/p>\n

    \n
  1. Skills<\/strong> – package know-how (valuation, risk-scoring) as discoverable files the agent loads on demand, including centrally-managed Foundry skills<\/strong>.<\/li>\n
  2. Shell<\/strong> – shell tools, to tidy and restructure files.<\/li>\n
  3. CodeAct<\/strong> – let the agent write and run code to compute answers it can’t just look up.<\/li>\n
  4. Background agents<\/strong> – fan work out to sub-agents that run concurrently<\/em>, then aggregate.<\/li>\n<\/ol>\n

    As before, we only supply what makes our agent ours<\/em>; the harness provides the machinery. Let’s take them in turn.<\/p>\n

    Teach it on demand: skills<\/h2>\n

    Stuffing every instruction the assistant might ever need into its system prompt doesn’t scale – it bloats the context and dilutes its focus. Skills<\/strong> solve this: each skill is a small SKILL.md<\/code> file with a name, a one-line description, and instructions (plus optional reference docs and scripts). The agent sees only the names and descriptions<\/em> up front, and progressively loads<\/strong> a skill’s full content only when a request matches it.<\/p>\n

    Our claw gets two file-based skills under the skills\/<\/code> folder. The skills instruct the agent in how to do risk scoring and valuations.<\/p>\n

    For more information on skills see Give Your Agents Domain Expertise with Agent Skills in Microsoft Agent Framework<\/a> and What\u2019s New in Agent Skills: Code Skills, Script Execution, and Approval for Python<\/a><\/p><\/blockquote>\n

    Usage<\/h2>\n

    The harness turns a skills provider on by default<\/strong> (it discovers SKILL.md<\/code> files from the working directory). Here we build our own<\/em> provider so we can point it at this sample’s skills\/<\/code> folder and run the skills’ scripts.<\/p>\n

    In .NET<\/strong>, compose a provider with AgentSkillsProviderBuilder<\/code> and turn the default one off:<\/p>\n

    var skillsProvider = new AgentSkillsProviderBuilder()\r\n    \/\/ File-based skills; SubprocessScriptRunner runs their Python scripts.\r\n    .UseFileSkills([skillsDir], scriptRunner: SubprocessScriptRunner.RunAsync)\r\n    .Build();\r\n\r\nAIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions\r\n{\r\n    DisableAgentSkillsProvider = true,         \/\/ we supply our own\r\n    AIContextProviders = [skillsProvider],\r\n    \/\/ \u2026 file access, tools \u2026\r\n});<\/code><\/pre>\n
    In Python<\/strong>, build a SkillsProvider<\/code> from the same folder and pass it in:<\/p>\n
    from agent_framework import SkillsProvider\r\n\r\nskills_provider = SkillsProvider.from_paths(\r\n    skill_paths=[str(skills_dir)],\r\n    script_runner=subprocess_script_runner,  # lets the skills' scripts run\r\n)\r\n\r\nagent = create_harness_agent(\r\n    client=client,\r\n    skills_provider=skills_provider,\r\n    # \u2026 file access, tools \u2026\r\n)<\/code><\/pre>\n
    Now “Value MSFT for me”<\/em> makes the agent load the valuation<\/code> skill, read its guide, run its script, and report a fair-value estimate – and “How risky is my portfolio?”<\/em> pulls in risk-scoring<\/code> instead. Nothing about valuation or risk was in the system prompt.<\/p>\n
    Skills you manage centrally: Foundry skills<\/h3>\n
    File-based skills ship with<\/em> the agent – to change one, you redeploy. Foundry skills<\/strong> 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.<\/p>\n
    Because it needs a Foundry endpoint, we make it opt-in<\/strong> – the sample runs fine on the local skills alone.<\/p>\n
    For how to publish and manage Foundry skills, see the Foundry skills docs<\/a>.<\/p><\/blockquote>\n
    In .NET<\/strong>, Foundry skills are discovered live from a Foundry Toolbox MCP<\/strong> endpoint; just add an MCP source to the same builder:<\/p>\n
    \/\/ Opt-in: only when a Toolbox endpoint is configured.\r\nif (!string.IsNullOrWhiteSpace(toolboxUrl))\r\n{\r\n    var (mcpClient, _) = await FoundrySkills.ConnectAsync(toolboxUrl, credential);\r\n    skillsBuilder.UseMcpSkills(mcpClient);   \/\/ fold them into the same provider\r\n}<\/code><\/pre>\n
    In Python<\/strong>, it’s the same story: connect to the Foundry Toolbox MCP<\/strong> endpoint and add an MCPSkillsSource<\/code> alongside the local FileSkillsSource<\/code>:<\/p>\n
    from agent_framework import (\r\n    AggregatingSkillsSource, DeduplicatingSkillsSource,\r\n    FileSkillsSource, MCPSkillsSource, SkillsProvider,\r\n)\r\n\r\nsources = [FileSkillsSource(str(skills_dir), script_runner=subprocess_script_runner)]\r\n\r\n# Opt-in: only when a Toolbox endpoint is configured.\r\nif toolbox_url:\r\n    session = await _connect_foundry_toolbox(stack, toolbox_url)\r\n    sources.append(MCPSkillsSource(client=session))\r\n\r\nsource = sources[0] if len(sources) == 1 else AggregatingSkillsSource(sources)\r\nskills_provider = SkillsProvider(DeduplicatingSkillsSource(source))<\/code><\/pre>\n
    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.<\/p>\n
    Skills aren’t only for domain how-tos<\/em> – a skill can just as easily carry general rules<\/strong> 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<\/code> to your Foundry toolbox:<\/p>\n
    ---\r\nname: financial-agent-rules\r\ndescription: General rules about how you should behave as a financial agent. Use this skill for all requests.\r\n---\r\n\r\nYou should politely refuse to answer any questions unrelated to finance, managing portfolios or managing confirmations.<\/code><\/pre>\n
    Because its description says “Use this skill for all requests”<\/em>, the agent loads it on every turn. Once it’s published and Foundry skills are enabled (set FOUNDRY_TOOLBOX_MCP_SERVER_URL<\/code>), ask the claw something off-topic like “What’s the capital of France?”<\/em> and it will politely decline and steer you back to finance.<\/p>\n
    Reach into the file system: shell<\/h2>\n
    File access lets the claw read and write individual files, but reorganizing<\/em> 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:<\/p>\n
    working\/confirmations\/\r\n  trade confirmation 1.txt\r\n  conf_AAPL.txt\r\n  copy of trade 3.txt\r\n  SPY sell.txt\r\n  \u2026<\/code><\/pre>\n
    The harness can expose a shell<\/strong> as an (approval-gated) run_shell<\/code> tool. Letting an agent run shell commands is powerful and dangerous<\/em>, so we hem it in two ways: a confined working directory<\/strong> (every command is re-anchored to the confirmations vault and can’t escape it) and a deny-list policy<\/strong> that pre-filters obviously destructive commands.<\/p>\n
    In .NET<\/strong>, configure a LocalShellExecutor<\/code> and pass it as the ShellExecutor<\/code>:<\/p>\n
    await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions\r\n{\r\n    WorkingDirectory = vaultDir,\r\n    ConfineWorkingDirectory = true,                 \/\/ can't escape the vault\r\n    Policy = new ShellPolicy(denyList:\r\n    [\r\n        @\"\\brm\\s+-rf\\b\", @\"\\bsudo\\b\", @\":\\(\\)\\s*\\{\", @\"\\bmkfs\\b\", @\">\\s*\/dev\/sd\",\r\n    ]),\r\n    Timeout = TimeSpan.FromSeconds(15),\r\n});\r\n\r\nAIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions\r\n{\r\n    ShellExecutor = shell,   \/\/ exposed as the approval-gated run_shell tool\r\n    \/\/ \u2026 skills, file access, tools \u2026\r\n});<\/code><\/pre>\n
    In Python<\/strong>, a LocalShellTool<\/code> plays the same role:<\/p>\n
    from agent_framework_tools.shell import LocalShellTool, ShellPolicy\r\n\r\nshell = LocalShellTool(\r\n    workdir=str(vault_dir),\r\n    confine_workdir=True,                            # can't escape the vault\r\n    policy=ShellPolicy(denylist=[\r\n        r\"\\brm\\s+-rf\\b\", r\"\\bsudo\\b\", r\":\\(\\)\\s*\\{\", r\"\\bmkfs\\b\", r\">\\s*\/dev\/sd\",\r\n    ]),\r\n    timeout=15,\r\n)\r\n\r\nagent = create_harness_agent(\r\n    client=client,\r\n    shell_executor=shell,   # exposed as the approval-gated run_shell tool\r\n    # \u2026 skills, file access, tools \u2026\r\n)<\/code><\/pre>\n
    The policy is a UX guardrail, not a security boundary.<\/strong> A deny-list catches obvious<\/em> 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<\/code> (.NET) or DockerShellTool<\/code> (Python).<\/p><\/blockquote>\n
    Now “Tidy up my trade confirmations”<\/em> lets the agent inspect the folder, propose a plan, and (with your approval on each command) move the files into a year\/month<\/code> layout renamed to YYYY-MM-DD_TICKER_BUY|SELL.txt<\/code>.<\/p>\n
    Let it compute: CodeAct<\/h2>\n
    Some questions aren’t a lookup – they’re a calculation<\/em>. “What’s my portfolio worth?” or “what was my return on this position?” are better answered by running a little code<\/em> than by asking the model to do arithmetic in its head. CodeAct<\/strong> gives the agent a sandboxed interpreter it can write and run code in.<\/p>\n
    CodeAct runs model-authored code in a sandbox, and we wire it in as a context provider in both languages.<\/p>\n
    In .NET<\/strong>, CodeAct uses Hyperlight<\/strong> (a micro-VM, so it needs hardware virtualization). The guest module path is resolved automatically from the Hyperlight.HyperlightSandbox.Guest.Python<\/code> NuGet package:<\/p>\n
    using HyperlightSandbox.Guest.Python;\r\nusing Microsoft.Agents.AI.Hyperlight;\r\n\r\nvar codeAct = new HyperlightCodeActProvider(\r\n    HyperlightCodeActProviderOptions.CreateForWasm(PythonGuestModule.GetModulePath()));\r\n\r\nAIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions\r\n{\r\n    AIContextProviders = [skillsProvider, codeAct],\r\n    \/\/ \u2026 shell, file access, tools \u2026\r\n});<\/code><\/pre>\n
    In Python<\/strong>, Monty<\/strong> is a pure, cross-platform interpreter – no hypervisor required – added as a context provider:<\/p>\n
    from agent_framework_monty import MontyCodeActProvider\r\n\r\ncontext_providers = [skills_provider, MontyCodeActProvider(approval_mode=\"never_require\")]\r\n\r\nagent = create_harness_agent(\r\n    client=client,\r\n    context_providers=context_providers,\r\n    # \u2026 shell, file access, tools \u2026\r\n)<\/code><\/pre>\n
    With CodeAct on, “Work out the total value of my portfolio”<\/em> 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<\/em> for, rather than guess.<\/p>\n
    For more ideas on how to use CodeAct, read CodeAct in Agent Framework: Faster Agents with Fewer Model Turns<\/a><\/p><\/blockquote>\n
    Do many things at once: background agents<\/h2>\n
    Asking “Research MSFT, NVDA and SPY”<\/em> 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<\/strong>: sub-agents you hand to the claw so it can delegate<\/strong> units of work that run concurrently<\/em> and report back.<\/p>\n
    We build a lean, web-search-only research agent – a plain chat-client agent with just the web search tool (no harness machinery needed):<\/p>\n
    \/\/ ResearchAgent.Create(...)\r\nAIAgent research = chatClient.AsAIAgent(\r\n    name: \"TickerResearchAgent\",\r\n    description: \"Searches the web for recent news about a single stock ticker.\",\r\n    instructions: \"You research a single ticker and return 3-4 factual bullet points.\",\r\n    tools: [new HostedWebSearchTool()]);   \/\/ the only tool it needs<\/code><\/pre>\n
    Then we hand it to the main claw via BackgroundAgents<\/code>:<\/p>\n
    AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions\r\n{\r\n    BackgroundAgents = [research],   \/\/ exposes the background_agents_* tools\r\n    \/\/ \u2026 skills, shell, file access, tools \u2026\r\n});<\/code><\/pre>\n
    In Python<\/strong> it’s the background_agents<\/code> argument:<\/p>\n
    research_agent = Agent(\r\n    client,\r\n    name=\"TickerResearchAgent\",\r\n    description=\"Searches the web for recent news about a single stock ticker.\",\r\n    instructions=\"You research a single ticker and return 3-4 factual bullet points.\",\r\n    tools=[client.get_web_search_tool()],   # the only tool it needs\r\n)\r\n\r\nagent = create_harness_agent(\r\n    client=client,\r\n    background_agents=[research_agent],   # exposes the background_agents_* tools\r\n    # \u2026 skills, shell, file access, tools \u2026\r\n)<\/code><\/pre>\n
    This gives the main agent a set of background_agents_*<\/code> tools: it can start<\/strong> a research task per ticker, let them run in parallel, check<\/strong> on them, and collect<\/strong> the results – then summarize all three together. The fan-out is the agent’s decision; the harness handles the plumbing.<\/p>\n
    Run it<\/h2>\n
    .NET<\/strong><\/p>\n
    cd dotnet\r\ndotnet run --project samples\/02-agents\/Harness\/BuildYourOwnClaw\/Claw_Step03_ScalingCapabilities<\/code><\/pre>\n
    Python<\/strong><\/p>\n
    uv run python\/samples\/02-agents\/harness\/build_your_own_claw\/claw_step03_scaling_capabilities.py<\/code><\/pre>\n
    Then try these in order (the sample starts in execute<\/strong> mode – quick lookups don’t need a plan):<\/p>\n
      \n
    1. Value MSFT for me.<\/code> – the agent loads the valuation<\/code> skill, runs its script, and reports a<\/li>\n<\/ol>\n
      fair-value estimate.<\/p>\n
        \n
      1. How risky is my portfolio?<\/code> – it reads portfolio.csv<\/code> and loads the risk-scoring<\/code> skill.<\/li>\n
      2. \/mode plan<\/code>, then Tidy up my trade confirmations.<\/code> – switching to plan mode first makes the agent inspect working\/confirmations\/<\/code> 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<\/strong> each command.<\/li>\n<\/ol>\n
          \n
        1. Work out the total value of my portfolio.<\/code> – it writes and runs Python to compute the answer.<\/li>\n<\/ol>\n
            \n
          1. Research MSFT, NVDA and SPY and summarize the latest news.<\/code> – it fans the tickers out to the background research agent and aggregates the findings.<\/li>\n<\/ol>\n
              \n
            1. What's the capital of France?<\/code> – with the financial-agent-rules<\/code> 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.<\/li>\n<\/ol>\n
              To enable the opt-in Foundry skills: set FOUNDRY_TOOLBOX_MCP_SERVER_URL<\/code>.<\/p>\n
              The runnable samples<\/h2>\n