An agent that can reason, run commands and produce files needs more than a good model. Since October 28, 2026, the Microsoft Copilot harness brings this managed execution loop to Microsoft Foundry prompt agents, with architecture and security constraints to build in from the moment you create them.
Why the harness changes how a prompt agent behaves
The Microsoft Copilot harness is an optional, managed runtime in Microsoft Foundry (formerly Azure AI Foundry) for prompt agents. It wraps the model with an agent loop, context management, tools, skills and the ability to delegate certain operations to subagents.
Without this orchestration, a complex request can stop after a first unsuccessful attempt. With the harness, the agent can plan the steps, act, observe the result, correct its approach and carry on until it produces an answer or a usable artifact.
The agent is still called through the Responses API. The change therefore concerns its execution environment, not the general way the client application consumes it. Microsoft announced this public preview on October 28, 2026.
An existing agent cannot be converted
The harness can only be selected at creation time. A new version of an existing agent cannot enable it: you must create a new prompt agent, then carry over and retest its configuration.
Three architectures address different needs
The harness replaces neither the default prompt runtime nor hosted agents. The choice depends mainly on the level of control you want over the execution loop and the middleware.
| Architecture | Agent loop | Code control | Recommended case |
|---|---|---|---|
| Prompt agent with default runtime | Managed behavior without the Copilot harness | Configured instructions and tools | Targeted interaction and limited orchestration |
| Prompt agent with Microsoft Copilot harness | Managed loop with tools, skills and subagents | Configuration rather than a custom framework | Complex tasks without maintaining your own runtime |
| Hosted agent | Loop provided by the team | Framework, middleware and tools under your control | Specific needs or a proprietary runtime |
A hosted agent is preferable when the team wants to own its framework, loop or middleware. The harness suits teams that accept managed orchestration in exchange for simpler operations.
To position these options within a broader architecture, see our comparison of Copilot Studio and Microsoft Foundry. The Foundry harness should also not be confused with the capabilities described for Copilot Studio and the GitHub Copilot harness.
Prerequisites must be validated before creation
The preview is only available in a subset of the regions that support prompt agents. The documentation notably cites East US, Sweden Central, West Europe, France Central and UK South, but this list must be checked before each deployment on the Foundry Agent Service limits, quotas and regions page.
The model must support reasoning and tool calling. Bringing your own model, or BYOM (Bring Your Own Model), is not supported with the harness.
Checks before creating the agent
- Confirm that the project's region supports the harness.
- Select a model compatible with reasoning and tool calling.
- Create a new prompt agent rather than a version of an existing agent.
- Plan a conversation for each request sent to the agent.
- Use only the agent's endpoint, not a direct ephemeral call to the Responses API.
- List the tools that are really needed before enabling production.
- Decide where important outputs will be stored durably.
The exact Azure role depends on the access model applied to the project and the connected resources. Following the principle of least privilege, the operator should only be granted permission to create and configure the agent in the project, plus the permissions needed for the sources it must actually query.
No fixed propagation delay is given in the documentation provided. A configuration should therefore only be considered active after a successful call to the endpoint and verification of its trace.
Context, conversation and memory are not equivalent
The harness loop keeps relevant information in the model's working context and can prioritize data as execution progresses. However, each request requires a conversation, and the associated workspace is specific to that conversation.
Foundry Memory is not supported with the harness. Conversation history and workspace files remain available, but they do not constitute durable memory across all exchanges and sessions.
Reports, transformed datasets and other outputs that must outlive the conversation should be copied to Foundry Files or another durable service. This separation avoids building a business process on a temporary workspace.
Consider a financial agent tasked with analyzing expenses, calculating a quarterly forecast and generating a PDF. The workspace can hold the intermediate data and the document during execution; the validated report must then be saved to durable storage provided by the organization.
Reducing tools is the first security control
A new agent enables the built-in tools filesystem_read, filesystem_write, shell, web and subagents by default. This configuration eases testing, but it grants too broad an action surface for many production scenarios.
All built-in tools are enabled by default
Disable every unnecessary tool with MicrosoftCopilotToolsetPreview before exposing the agent to real data or users. An internal reporting agent, for example, has no reason to keep the web tool if all its sources are private.
An RAI policy containing network rules can be attached to the agent to limit the sandbox's outbound traffic. This capability is itself in preview. Traces then let you confirm that an attempt to reach an unauthorized destination was blocked.
Skills use the open Agent Skills format: a folder containing a SKILL.md file. They are versioned in Foundry and limited to 50 references per agent. Explicitly pinning a version provides an immutable snapshot and prevents a later change from silently altering production behavior.
A prompt agent running on the default runtime does not automatically load a toolbox's skills. Attachment must therefore be explicitly checked during a migration test.
> 60 %
Announced token reduction with search across 50 tools
Microsoft evaluation
> 97 %
Announced reduction with a catalog of 1,000 tools
Microsoft evaluation
These gains come from tool search, which injects only the relevant descriptions into the context. Simply creating a toolbox is not enough to obtain them.
Implementation
Creation must be done in Microsoft Foundry by selecting the harness from the start. Since no complete API syntax is provided here, the PowerShell script below does not attempt to invent an endpoint: it locally checks the JSON that a pipeline plans to use and blocks the known incompatible settings.
Create a new prompt agent
Open the project in Microsoft Foundry, then create a prompt agent. Do not simply duplicate a version of the existing agent if it used the default runtime.
Select the Microsoft Copilot harness
Choose the harness during creation, then select a compatible region and model. This choice cannot be added to this agent later.
Reduce tools and attach skills
Disable the built-in tools that are not required. Attach only the necessary skills and pin their version before regression testing.
Test through the agent endpoint
Create a conversation, run a representative scenario and check the trace. Verify tool calls, denied network accesses and the creation of the expected artifacts.
Troubleshoot, then optimize on real traces
| Symptom | Likely cause | Resolution |
|---|---|---|
| The harness option is missing | Incompatible region or model, or use of BYOM | Choose a supported region and a model with reasoning and tool calling |
| Cannot enable the harness on an existing agent | The runtime is fixed at creation | Create a new prompt agent and replay the tests |
| The request is rejected | Parameter managed by the harness, or missing conversation | Remove the forbidden parameters and create a conversation for the request |
| A toolbox skill is not loaded | The runtime in use does not load it automatically | Explicitly attach the skill and pin its version |
| A file disappears between two conversations | Workspace specific to each conversation and Foundry Memory not supported | Copy the output to Foundry Files or durable storage |
| Web access fails | Network rule or web tool disabled | Examine the trace and allow only the justified destination |
Once things are stable, the Agent optimizer, also in preview, can suggest new instructions, skills, tool descriptions or a different model choice. Its candidates must be evaluated on a private, representative task set, then compared on quality, latency and token consumption.
Each score must remain linked to its trace. An average improvement does not justify a deployment if it hides a regression on a critical scenario or an unwanted new tool call.
Where to start
First create a separate agent in a non-production environment, with a single business scenario and the minimum set of tools. If your team needs to control the loop or run its own middleware, go for a hosted agent instead; otherwise, the harness reduces the amount of infrastructure to maintain.
Validation before production
- Run a test set representing the expected tasks and failures.
- Verify every tool call and every network denial in the traces.
- Confirm that no secret or durable file remains in the temporary workspace.
- Test the agent identity's permissions according to least privilege.
- Version the skills and keep the validated configuration.
- Replay the checks after every change of model, tool or instruction.
Going further
- Use the Microsoft Copilot harness with prompt agents — creation, tools, skills and outbound traffic control.
- Foundry Agent Service limits, quotas and regions — regional compatibility, memory and forbidden parameters.
- Prompt agents in Foundry Agent Service — choosing between default runtime, harness and hosted agent.
- Use skills with Foundry agents —
SKILL.mdstructure, versioning and attachment. - What's new in Microsoft Foundry, October 2026 — preview announcement and product context.



