What Microsoft actually shipped
The harness is not a new kind of agent. Microsoft's documentation describes it as an optional managed runtime for prompt agents. Foundry operates the harness and its execution environment. Applications still invoke the agent through the Responses API, and developers don't deploy or maintain harness code.
Microsoft describes a harness as the layer around the model. It covers the instructions, context, execution environment and controls an agent needs to do work, and it supports open standards such as the Model Context Protocol (MCP), agent skills and agent plugins. Daily.dev's summary of the Foundry post says the managed system handles the agent loop, sandbox, model and tool call coordination, working context and file management.
Foundry's default prompt-agent runtime coordinates the model and the tools declared in the agent definition. The Copilot harness is an alternative runtime for multi-step work involving tools, skills, files or commands. It can provide built-in tools for reading files, writing files, running shell commands, fetching web content and delegating to subagents. It also works with compatible declared tools and skills.
Some early coverage said the harness supports Copilot Code, Copilot Studio, GitHub Copilot, the CLI and VS Code. Daily.dev's write-up says it now backs those products. I treat that as secondary reporting, because the Microsoft documentation I reviewed doesn't list those products.
The catch: the choice is permanent
This is the most important limit for architects. During the initial preview, you select the harness only when you create a new prompt agent. You can't add it to an existing agent on the default runtime. You can't switch it later, and creating a new version doesn't change it. If the choice turns out wrong, you have to build another agent. Treat it as an architectural decision, not a toggle.
Other documented requirements and limits:
- You need a Foundry project in a supported region. The Back Room Tech notes that Microsoft Learn lists nine supported regions for the harness, separate from general Agent Service availability.
- The model must support reasoning and tool calling and be available to prompt agents in your region.
- Bring your own model (BYOM) isn't currently supported.
- Foundry Memory isn't supported by the harness preview, according to Microsoft's documentation.
- Every response request needs a conversation. Don't use
previous_response_id. Continue by sending the next response in the same conversation. - The preview has no service-level agreement, and Microsoft doesn't recommend it for production workloads.
Prompt agent, harness or hosted agent?
Microsoft's guidance is straightforward:
| Need | Best fit |
|---|---|
| Simple instructions, model calls and supported Foundry tools | Default prompt agent |
| Managed multi-step workflows with files, commands, skills and subagents | Prompt agent with the Copilot harness |
| Your own framework, orchestration, middleware, dependencies or process model | Hosted agent |
| An app that owns the agent definition per request and needs no saved resource | Direct Responses API call (doesn't support the harness) |
The trade-off is control for convenience. Foundry controls the runtime's CPU, memory and idle settings. If you want to change the agent loop itself, Microsoft points you to hosted agents.
Setting it up
Prerequisites
- The Foundry User role on the project for the identity that creates and invokes the agent.
- A deployed model in the project.
- For Azure Developer CLI work,
azd1.37.0 or later and theazure.ai.agentsextension 1.0.0-beta.22 or later. - The preview flag set in each shell or CI job:
AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true. - Minimum SDK versions. Python needs
azure-ai-projects2.9.0 or later. TypeScript needs@azure/ai-projects2.9.0 and Node.js 22 or later. .NET needsAzure.AI.Projects.AgentsandAzure.AI.Extensions.OpenAI3.0.0-beta.5. Java is also documented, withazure-ai-agents2.8.0.
Portal steps
- Turn on the New Foundry toggle and open a project in a supported region.
- Under Build an agent, select Create an agent.
- Enter a unique agent name and select the Copilot harness option.
- Create the agent, then test it in the playground.
- After changing the model, instructions, tools or skills, select Save and start new chat. Wait for the new active version before testing.
azd steps
- The harness appears in
azure.yamlasharness.type: microsoft_copilot_preview. - After
azd up, runazd ai agent show --output json. Confirm the agent is active, withkind: promptand the harness value, before you add tools or skills.
Permissions and common failure points
The most likely snag is a missing role assignment. To call a Toolbox or return generated files, the agent's own identity needs the Foundry User role at project scope. You can only assign it after the agent exists. It is separate from your user role. Don't assign it to the project managed identity.
If that assignment is missing or hasn't propagated, you can get HTTP 403 errors on file upload. Other operations such as model calls, shell commands and workspace file operations can still succeed, which makes the failure confusing. Microsoft says to allow up to five minutes for propagation, then test from a new chat. It also advises using the role definition GUID rather than the role name, because the Foundry roles were recently renamed.
Other pitfalls:
- Unknown or duplicate harness tool names make agent-version creation fail. You can include at most one harness toolset entry.
- Input file staging is best effort. A bad file ID, an oversized file or a transient download failure can cause the file to be skipped while the text of the request continues. Verify the response actually used the attachment.
- Unsupported fields and operations return errors rather than being ignored.
Sandbox, security and data boundaries
Each conversation gets its own workspace for files and execution state. Foundry runs commands and file processing in an isolated, service-managed sandbox. It can idle, resume or replace the sandbox without changing the conversation, and workspace state survives those operations. The sandbox is not a durable output store. Save important results to Foundry Files or another durable service.
Shell is the broadest built-in tool. Shell commands can read and write files and reach network resources the environment permits. Microsoft states that disabling file or web tools while leaving Shell on isn't a strict security boundary. A separately declared shell or Code Interpreter tool is also independent of the harness tool settings.
Microsoft also documents preview network egress controls. You create a Network control in a Responsible AI policy and attach it to the agent. Microsoft recommends starting in Audit mode to discover which destinations the agent needs. Enforce mode returns HTTP 403 for denied requests. These controls apply to the harness environment, including shell commands and the harness Web tool. Declared tools such as Code Interpreter and Foundry web search keep their own network behavior.
Managed execution does not make everything Foundry's responsibility. Data can leave Foundry when you configure an external tool, connection or endpoint, and that service's terms then apply. Use Entra identity or managed identity rather than embedded credentials, grant least privilege, and review skill scripts as code.
What it will cost
On pricing, Microsoft's primary documentation I reviewed didn't confirm the rates, so I'm attributing them. Daily.dev's summary of the Foundry announcement says runtime usage is free before December 1, 2026. After that, sandbox compute and memory are billed at $0.0994 per vCPU-hour and $0.0118 per GiB-hour, with model inference and separately billed tools charged on top. Unite.ai also reports that billing starts December 1, 2026 on a consumption basis. TechGig adds that rates vary by region and customer agreement. Confirm current figures in your own Azure pricing view before budgeting.
Analysis: who should care
Developers already building on Foundry get the clearest benefit. They can offload the agent loop and sandbox and keep agent definitions in source control. The preview documentation shows no custom-model path, no switching and thin production guarantees. Teams that need fine-grained control over runtime behavior will likely prefer hosted agents. Teams that want speed may accept the lock-in.
One note of caution: the testimonials in Microsoft's launch material are vendor-supplied. Confluence Technologies' CTO said a solution was running in under a week. That is one customer's account, not a benchmark.
A sensible evaluation path:
- Create a throwaway agent in a supported region.
- Disable Shell unless you need it.
- Run egress controls in Audit mode first.
- Persist outputs outside the sandbox.
- Estimate sandbox cost before December 1.
Don't plan production on it until Microsoft moves it past preview.
Update: Additional details (November 5, 2026)
Microsoft’s October Foundry roundup says the Azure Developer CLI agents extension added a --harness option to azd ai agent init in version 1.0.0-beta.23, released October 29. The extension remains in beta.
Microsoft also says Foundry Toolkit 1.6.18, released October 28, added preview Copilot harness support to Agent Builder in VS Code.
References
- Microsoft opens GitHub Copilot agent harness to developers through Foundry TechGig · 2026-10-31T04:20:40+00:00
- Microsoft Makes Copilot Harness Available Through Foundry unite.ai
- Microsoft opens GitHub Copilot agent harness to developers through Foundry - TechGig TechGig · Sat, 31 Oct 2026 05:29:26 GMT