Use the Microsoft Copilot harness with prompt agents

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

The Copilot harness is an optional managed runtime for prompt agents. Foundry operates the harness and its execution environment. Your resource remains a prompt agent, and you continue to invoke it through the Responses API. You don't deploy or maintain harness code.

Use the Copilot harness when your prompt agent needs supported multi-step tool, skill, file, or command workflows and you want Foundry to operate the runtime. Use a hosted agent when you need to own the framework, orchestration, middleware, runtime policy, dependencies, or process model.

Prerequisites

  • A Microsoft Foundry project in a region supported by the Copilot harness.
  • A model that supports reasoning and tool calling and is available to prompt agents in your project region. See Copilot harness model requirements. Bring your own model (BYOM) isn't currently supported with the Copilot harness.
  • The Foundry User role on the project for the identity that you use to create and invoke the agent.
  • To call a Toolbox or return generated files, the Foundry User role on the same project for the agent's instance_identity.principal_id. This role assignment is separate from your user role and can be made only after the agent exists. You or an administrator needs permission to create role assignments at the project scope. See Return generated files.
  • A new prompt agent. You select the harness during agent creation and can't switch an existing agent during the initial public preview.
  • To use a skill, create it in the same Foundry project. See Use skills in Foundry.
  • For connection-backed tools, use an existing project connection or create one with the Foundry Project Manager role on the project. This role is also needed when azd creates a connection to attach a Toolbox. Grant only the permissions the tool needs. See MCP prerequisites.

Enable the Copilot harness preview in your current shell before running the agent commands:

export AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true

Set this environment variable in each new shell or CI job. For PowerShell syntax, see Enable the Copilot harness preview.

pip install "azure-ai-projects>=2.9.0" azure-identity

Understand what the harness changes

The harness choice selects the managed runtime that coordinates the model and supported capabilities. It doesn't change these parts of the resource:

  • Agent type: The resource remains a prompt agent with a different harness.
  • Definition: You still configure a model, instructions, tools, and other supported prompt agent fields.
  • Invocation: Applications use the agent's Responses endpoint.
  • Identity and governance: Foundry project roles, agent identity, connections, and policies continue to control access to supported resources.
  • Operations: Foundry operates the harness environment. You don't manage it as a separate resource.

The initial public preview supports harness selection only when you create the agent. Creating another agent version doesn't change the harness.

Understand conversations, workspaces, and sandboxes

A conversation preserves interaction history across turns. The harness uses a separate workspace for each conversation to hold files and execution state. Foundry provides a service-managed, isolated execution environment, called a sandbox, for operations such as processing files and running commands.

Foundry can idle, resume, or replace the sandbox without changing the conversation. Workspace state survives normal idle, resume, and replacement operations. A sandbox isn't a customer-managed resource or durable output store. Store important outputs in Foundry Files or another durable service. A new conversation starts with separate history and a separate workspace.

Create an agent

Create a new prompt agent and select the Copilot harness as its runtime. The harness selection is fixed for the agent during the initial public preview.

Before you create the agent, confirm that the project has a deployed model. If it doesn't, deploy a model.

  1. Open Microsoft Foundry, ensure the New Foundry toggle is on, and select a project in a supported region. These steps apply to the new Microsoft Foundry experience, not Foundry (classic).
  2. On the project home page, under Build an agent, select Create an agent.
  3. Enter a unique agent name.
  4. Keep interaction mode set to Text.
  5. Select Use the Microsoft Copilot harness.
  6. Select Create to open the playground.

After you change the model, instructions, tools, or skills, select Save and start new chat, and then wait for the new active version before testing it.

Set values for a unique agent name and a supported model:

AGENT_NAME="my-harness-agent-<unique-suffix>"
MODEL="<supported-model-name>"

To create a Foundry project, initialize the prompt agent interactively:

azd ai agent init "$AGENT_NAME" \
  --kind prompt \
  --agent-name "$AGENT_NAME" \
  --model "$MODEL"

When prompted, select Create a new Foundry project, and then choose a supported region and model deployment options.

To reuse an existing Foundry project and model deployment instead, set the project's full Azure resource ID and the deployment name. Initialize noninteractively:

PROJECT_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
MODEL_DEPLOYMENT="<model-deployment-name>"

azd ai agent init "$AGENT_NAME" \
  --no-prompt \
  --kind prompt \
  --agent-name "$AGENT_NAME" \
  --project-id "$PROJECT_ID" \
  --model-deployment "$MODEL_DEPLOYMENT"

After either initialization path finishes, open the generated directory:

cd "$AGENT_NAME"

In the generated azure.yaml, add the harness selection to the azure.ai.agent service. Keep the generated project, model, name, and other fields:

services:
  <agent-service-name>:
    host: azure.ai.agent
    # Keep the generated agent fields.
    harness:
      type: microsoft_copilot_preview

Deploy the agent, and then inspect its persisted definition:

azd up --no-prompt
azd ai agent show --output json

Confirm that the agent is active and its definition contains kind: prompt and harness.type: microsoft_copilot_preview before you add tools or skills.

For an end-to-end scenario that adds web search and a reusable skill, see Quickstart: Create a web research agent.

Use a new agent name and a model that supports reasoning and tool calling and is available to prompt agents in your project region. During the initial public preview, you can't add the Copilot harness to an existing prompt agent that uses the default runtime.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MicrosoftCopilotHarness, PromptAgentDefinition
from azure.identity import DefaultAzureCredential

FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your-agent-name"
FOUNDRY_MODEL = "your-model-name"

project = AIProjectClient(
  endpoint=FOUNDRY_PROJECT_ENDPOINT,
  credential=DefaultAzureCredential(),
  allow_preview=True,
)
agent = project.agents.create_version(
  agent_name=FOUNDRY_AGENT_NAME,
  definition=PromptAgentDefinition(
    model=FOUNDRY_MODEL,
    instructions="You are a helpful assistant.",
    harness=MicrosoftCopilotHarness(),
  ),
)
print(f"Agent created: {agent.name}, version: {agent.version}")

The SDK selects the harness on the agent definition.

Invoke and verify the agent

Start a new conversation, invoke the agent, and confirm that it returns a completed response. Each response request to an agent that uses the Copilot harness requires a conversation.

  1. In the playground, enter What can you help me do?, and then submit the message.
  2. Confirm that the agent returns a completed response.
  3. Open the response trace and confirm that it records the model activity for the request.

Start a new conversation and invoke the deployed agent:

azd ai agent invoke --new-conversation --no-prompt \
  "What can you help me do?"

Confirm that the command returns a completed text response.

Use an agent-scoped Responses client and an explicit conversation.

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your-agent-name"

project = AIProjectClient(
  endpoint=FOUNDRY_PROJECT_ENDPOINT,
  credential=DefaultAzureCredential(),
  allow_preview=True,
)
openai = project.get_openai_client(agent_name=FOUNDRY_AGENT_NAME)
conversation = openai.conversations.create()
response = openai.responses.create(
  conversation=conversation.id,
  input="What can you help me do?",
)
print(response.output_text)

Omit store or set it to true. Don't use previous_response_id; continue by sending the next response in the same conversation.

Configure tools and skills

The Copilot harness supports:

  • Harness tools for reading files, writing files, running shell commands, fetching web content, and delegating to subagents. New agents have all five tools enabled unless you configure the harness tools.
  • Skills referenced at the top level of the prompt agent definition.
  • Function tools that your application executes and returns outputs for. See Use function calling with Microsoft Foundry agents.
  • Foundry web search added directly to the prompt agent definition without a project connection. The Web harness tool is separate and fetches content from a URL.
  • Compatible declared tools that Foundry supplies through a managed toolbox. For the current list and each tool's configuration guidance, see Create and manage a toolbox.

Tool availability can also depend on the project's region and model. A tool's existing authentication, connection, approval, and regional requirements still apply.

In azure.yaml, the prompt agent uses separate fields to attach capabilities and order their deployment:

Agent field What it does
tools Configures harness tools and directly attached declared tools.
skills Attaches skills to the prompt agent.
toolboxes Attaches shared toolboxes to the prompt agent.
uses Orders sibling services for deployment. Adding a service to uses doesn't attach it to the agent by itself.

Declare skills, connections, and toolboxes as sibling entries under services. Then reference their service keys from the agent's skills, toolboxes, and uses lists as shown in the following sections.

Configure harness tools

The managed runtime includes built-in harness tools. These tools aren't tools that the agent calls through a project connection. The service and your organization's policy can restrict their availability.

During public preview, the service manages the approval policy for harness tools. The require_approval setting applies to customer-configured MCP tools, not harness tools.

Harness tool What it enables
File system read Read and search files in the harness workspace.
File system write Create and modify files in the harness workspace.
Shell Execute operating-system commands.
Web Fetch web content from a URL.
Subagents Delegate work to additional agents.
  1. In the agent's Tools section, select Harness tools.
  2. Select or clear File system read, File system write, Web, Shell, and Subagents.
  3. Select Done.
  4. Select Save and start new chat, and then wait for the new active version before testing it.

In azure.yaml, use one microsoft_copilot_toolset_preview settings block in the prompt agent's top-level tools list. The configuration names map to harness tools as follows:

Harness tool Configuration name What it enables
File system read filesystem_read Read and search files in the harness workspace.
File system write filesystem_write Create and modify files in the harness workspace.
Shell shell Execute operating-system commands.
Web web Fetch web content from a URL.
Subagents subagents Delegate work to additional agents.

To disable one capability, add one settings block to the prompt agent's top-level tools list. This example disables built-in shell commands:

services:
  <agent-service-name>:
    host: azure.ai.agent
    # Keep the existing agent fields.
    tools:
      - type: microsoft_copilot_toolset_preview
        configs:
          - name: shell
            enabled: false

To allow only selected capabilities, disable capabilities by default and enable each exception explicitly. This example allows file reading and harness-native web fetching:

services:
  <agent-service-name>:
    host: azure.ai.agent
    # Keep the existing agent fields.
    tools:
      - type: microsoft_copilot_toolset_preview
        defaultConfig:
          enabled: false
        configs:
          - name: filesystem_read
            enabled: true
          - name: web
            enabled: true

You can include at most one microsoft_copilot_toolset_preview entry. Unknown or duplicate capability names cause agent-version creation to fail.

Deploy the new agent version, and then inspect its persisted definition:

azd deploy
azd ai agent show --output json

Confirm that the latest version is active and contains one microsoft_copilot_toolset_preview entry with the settings you selected.

Harness tools are enabled by default. To change them:

  1. Add one MicrosoftCopilotToolsetPreview object to the prompt agent definition's top-level tools collection.
  2. Set the default enablement, and then add per-tool overrides by using MicrosoftCopilotToolsetConfig objects. The configuration names are filesystem_read, filesystem_write, shell, web, and subagents.
  3. Create a new agent version, retrieve its definition, and confirm that the toolset contains the settings you selected.

Include at most one harness toolset. Unknown or duplicate capability names cause agent-version creation to fail.

Important

Shell is the broadest harness tool. Shell commands can read or write files and access network resources that the environment permits. Disabling File system read, File system write, or Web while leaving Shell enabled isn't a strict security boundary. A separately declared shell or Code Interpreter tool is also independent of the harness tool settings.

Use the Foundry web search tool when your agent needs to search the web. It doesn't require a project connection and is separate from the Web harness tool, which fetches content from a URL.

  1. In the agent's Tools section, select Add > Add tools.
  2. On the Configured tab, select Web search, and then select Add tool.
  3. Keep Search the web with Bing Search selected, and then select Add.
  4. Select Save and start new chat, and then wait for the new active version before testing it.

In azure.yaml, add the tool to the tools list of the azure.ai.agent service:

services:
  <agent-service-name>:
    host: azure.ai.agent
    # Keep the existing agent fields.
    tools:
      - type: web_search

Deploy the agent before testing the tool.

  1. Follow the SDK setup in Web search tool to construct the Foundry web search tool.
  2. Add the tool to the prompt agent definition's top-level tools collection alongside the harness selection.
  3. Create a new agent version, start a new conversation, and invoke a request that requires current web information.

After you invoke the agent, open it in Microsoft Foundry with the New Foundry toggle on and inspect its response trace to confirm that it called web search. Don't put secrets, credentials, or other sensitive data in search queries. For data handling, pricing, administrator controls, and other requirements, see Web search tool.

Add another supported tool

When you attach a Toolbox to a prompt agent, assign the Foundry User role at project scope to the agent's instance_identity.principal_id. Follow the role-assignment procedure in Return generated files before you invoke the Toolbox.

Choose a tool from the toolbox feature support table, follow its linked setup instructions, and add it to the prompt agent definition through the portal, an SDK, REST API, Toolkit, or azd.

For connection-backed tools:

  1. Create a project connection for the external service.
  2. Choose the narrowest supported authentication method and permissions.
  3. Add the tool to the prompt agent definition.
  4. Create or deploy the agent version.
  5. Invoke a request that requires the tool, and confirm the expected tool call in Foundry tracing.

Choose a tool from the toolbox feature support table, and follow the linked article for its required connection and tool-specific fields. Directly attached tools go in the agent's tools list. For example, this entry attaches an MCP server through an existing project connection. In the following examples, replace <project-service-name> with the generated azure.ai.project service key. Preserve existing uses entries and add any new dependencies:

services:
  <agent-service-name>:
    host: azure.ai.agent
    # Keep the existing agent fields.
    uses:
      - <project-service-name>
    tools:
      - type: mcp
        server_label: support
        server_url: ${MCP_SERVER_URL}
        project_connection_id: <project-connection-name>
        require_approval: always

Set MCP_SERVER_URL in the active environment by running azd env set MCP_SERVER_URL <mcp-server-url>. Don't store credentials in azure.yaml. For MCP authentication and approval options, see Use Model Context Protocol tools.

To create and attach a Toolbox in the same project, declare it as a sibling service. This example puts web search in a Toolbox. Add the Toolbox service key to both the agent's toolboxes list and its uses list:

services:
  <toolbox-service-name>:
    host: azure.ai.toolbox
    uses:
      - <project-service-name>
    tools:
      - type: web_search

  <agent-service-name>:
    host: azure.ai.agent
    # Keep the existing agent fields.
    uses:
      - <project-service-name>
      - <toolbox-service-name>
    toolboxes:
      - <toolbox-service-name>

For a connection-backed Toolbox tool, declare the connection as another sibling service, add its service key to the Toolbox's uses list, and reference it from the tool's connection field. Follow the selected tool's setup article for its exact fields and authentication requirements.

Deploy all sibling services, and then inspect the persisted agent definition:

azd deploy --all --no-prompt
azd ai agent show --output json

Confirm that the latest agent version is active and contains the direct tool or the attached Toolbox as an MCP tool with a versioned Toolbox server URL.

  1. Choose a tool from the toolbox feature support table, and follow its linked SDK setup instructions.
  2. Add the tool model to the prompt agent definition's top-level tools collection.
  3. Create a new agent version, invoke a request that requires the tool, and confirm the expected tool call in Foundry tracing.

Add a skill

Skills are versioned Foundry resources. You can add them directly to the prompt agent definition or through a compatible toolbox. The following steps use the direct path. Create the skill in the same project, and then reference it from the prompt agent definition. Each agent version stores an immutable skill version.

  1. In the left navigation, select Tools, and then open Skills (Preview).
  2. Select New skill > Create skill.
  3. Enter the skill name, description, and instructions, and then select Create.
  4. Return to the agent. In the Tools section, select Add > Add skills.
  5. Select the skill, and then select Add.
  6. Select Save and start new chat, and then wait for the new active version before testing it.

In azure.yaml, declare the skill as its own service and add that service to the prompt agent's skills and uses lists. The skills entry attaches the skill. The uses entry ensures that azd deploys the skill before the agent. Keep the generated project, model, name, and other fields. Replace <project-service-name> with the generated azure.ai.project service key, and preserve existing uses entries:

services:
  # Keep the generated azure.ai.project service.

  support-skill:
    host: azure.ai.skill
    uses:
      - <project-service-name>
    archive: ./skills/support-skill

  <agent-service-name>:
    host: azure.ai.agent
    uses:
      - <project-service-name>
      - support-skill
    kind: prompt
    harness:
      type: microsoft_copilot_preview
    skills:
      - support-skill

The string shorthand in skills refers to the matching local azure.ai.skill service. During azd deploy --all, azd publishes that skill and attaches its immutable version. To attach an existing published skill instead, specify its version explicitly and omit it from uses unless the same manifest also declares that skill service:

skills:
  - name: published-skill
    version: "<published-version>"

The azd extension doesn't automatically resolve the default version of an existing published skill.

The archive field accepts a ZIP file or a directory with SKILL.md at its root. azd resolves operating-system-native paths, including backslash paths on Windows. During deployment, azd packages the directory, creates or updates the skill first, and stores the immutable skill version as a skills reference in the agent version.

Deploy the skill and agent, and then inspect the persisted agent definition:

azd deploy --all --no-prompt
azd ai agent show --output json

Confirm that the latest version is active and contains a top-level reference to the immutable skill version.

  1. Create the skill in the same Foundry project as the prompt agent.
  2. Create a SkillReference with the skill name and immutable version.
  3. Add the reference to the prompt agent definition's top-level skills collection.
  4. Create a new agent version, retrieve its definition, and confirm that it contains the skill reference.

The harness can also discover skills attached to a compatible toolbox. For skill package structure, versioning, and toolbox setup, see Use skills in Foundry.

Exchange files with the agent

Use the conversation-scoped harness workspace to process request files and create outputs. Treat workspace files as session state, not durable outputs.

Use input files

  1. In Foundry chat, attach the file to the message. For a Responses API request, add an input_file item that uses a Foundry file ID or inline file data.
  2. Ask the agent to inspect or process the attached file.
  3. Verify that the response uses the file's contents before you rely on its result.

The harness stages the file in its workspace before the model starts. The agent can use File system read or Shell to work with the file. You don't need to add File Search or ask the agent to stage a normal request attachment. Use File Search when you need indexed retrieval across a collection of files.

A new conversation starts a separate workspace. Upload important outputs to Foundry Files or another durable service.

Input staging is best effort. An invalid file ID, an oversized file, or a transient download failure can cause the harness to skip the file while the text portion of the request continues. Verify that the response used the attached content before you rely on its result.

Return generated files

The File system write harness tool creates and modifies files only in the harness workspace. To return a generated output as a downloadable file, the harness uploads it to Foundry Files by using the agent identity. The agent identity must have the Foundry User role at the Foundry project scope.

After you create the agent, use Azure Cloud Shell or Azure CLI to retrieve its instance_identity.principal_id and assign the role. Set the agent's project endpoint, name, and full Azure project resource ID:

Note

Because the Foundry RBAC roles were recently renamed, use the role definition ID (GUID) instead of the role name in your code to avoid issues during the rename rollout:

  • Foundry User: 53ca6127-db72-4b80-b1b0-d745d6d5456d
  • Foundry Owner: c883944f-8b7b-4483-af10-35834be79c4a
  • Foundry Account Owner: e47c6f54-e4a2-4754-9501-8e0985b135e1
  • Foundry Project Manager: eadc314b-1a2d-4efa-be10-5d325db5065e
PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
AGENT_NAME="<agent-name>"

AGENT_IDENTITY_ID=$(az rest --method GET \
  --url "$PROJECT_ENDPOINT/agents/$AGENT_NAME?api-version=v1" \
  --resource "https://ai.azure.com" \
  --query "instance_identity.principal_id" \
  --output tsv)

az role assignment create \
  --assignee-object-id "$AGENT_IDENTITY_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
  --scope "$PROJECT_ID"

Don't assign the role to the project managed identity. Allow up to five minutes for the role assignment to propagate, and then test from a new chat. A missing or not-yet-propagated assignment can return HTTP 403 during the upload even when model calls, shell commands, and workspace-file operations succeed.

  1. Start a new conversation and ask the agent to create an output file.
  2. Confirm that the response includes the uploaded Foundry file ID.
  3. In Microsoft Foundry, ensure the New Foundry toggle is on, and select Data > Datasets.
  4. Find the row whose name matches the file ID, and select Actions > View details.
  5. Select the file in the Files tree, and then select Download.

Secure tools and data

Foundry operates the harness and execution environment. Data can leave Foundry when you configure an external tool, connection, or endpoint, according to that service's terms and data-handling practices.

Apply these controls:

  • Use Microsoft Entra identity, managed identity, or supported OAuth flows instead of embedding credentials in instructions, skills, or files.
  • Grant least-privilege access to the agent identity and each project connection.
  • Review the data sent to every external tool and the data that tool returns.
  • Treat skill instructions, scripts, and assets as code. Review and version them before attaching them to an agent.
  • For a customer-configured MCP tool, use require_approval and handle any returned mcp_approval_request by submitting an mcp_approval_response in the same conversation. See Use Model Context Protocol tools.
  • For private networking, follow Set up private networking for Foundry Agent Service.

Control network egress

Network egress controls (preview) govern direct outbound requests from the Foundry-managed harness execution environment. They apply to prompt agents with the Copilot harness, but not to other prompt agents or model deployments.

Create a Network control in a Responsible AI (RAI) policy, and then attach the policy's full Azure Resource Manager (ARM) resource ID to the prompt agent. Start in Audit mode to discover the destinations that the agent needs before you enforce the policy.

The policy governs direct traffic from the harness environment, including shell commands and the harness Web tool. Declared Foundry tools such as Code Interpreter and web search run behind their own service boundaries and retain their documented network behavior.

Rules are evaluated in order, and the first matching host rule wins. Set the default action to Deny for an allow list of customer-directed traffic or Allow for a deny list. Foundry preserves the required platform connectivity that the harness needs to operate. In Audit mode, requests that would be denied are logged instead of blocked. In Enforce mode, denied requests return HTTP 403 to the harness environment. This guidance covers host-based Allow and Deny rules.

  1. In the Foundry portal, select Build > Guardrails, and then select Create.
  2. Under Network, configure Egress rules. Under Outbound requests, choose the default action for requests that don't match a rule.
  3. Select Add rules. Choose Audit or Enforce, enter a Host match, choose an Action, and then select Add. Select Create when you finish adding rules.
  4. Select Next, select the prompt agent that uses the Copilot harness, and then select Next again.
  5. Enter a guardrail name, review the controls and agent assignment, and then select Create. The portal creates a new agent version with the guardrail attached.
  6. Open the new agent version and start a new chat. Ask the agent to use Shell and curl to test one allowed host and one denied host.

If saving the agent returns a generic processing error, confirm that the selected guardrail still exists on the same Foundry resource as the project. A deleted guardrail or a policy resource ID from another resource can't be resolved by the agent runtime.

Add a policies entry to the agent service in azure.yaml:

services:
  <agent-service-name>:
    host: azure.ai.agent
    kind: prompt
    harness:
      type: microsoft_copilot_preview
    policies:
      - type: rai_policy
        raiPolicyName: ${RAI_POLICY_ID}

Set RAI_POLICY_ID to the policy's full ARM resource ID, and then deploy the agent. To create an egress-only policy programmatically, see Create an egress-only policy with REST.

azd env set RAI_POLICY_ID "<rai-policy-resource-id>"
azd deploy --no-prompt
azd ai agent show --output json

Confirm that the persisted definition contains the same resource ID in rai_config.rai_policy_name.

Add the RAI configuration to the Prompt Agent definition in the earlier Create an agent sample. Set the policy variable to the full ARM resource ID. To create an egress-only policy programmatically, see Create an egress-only policy with REST.

from azure.ai.projects.models import (
    MicrosoftCopilotHarness,
    PromptAgentDefinition,
    RaiConfig,
)

RAI_POLICY_ID = "<rai-policy-resource-id>"

definition = PromptAgentDefinition(
    model=FOUNDRY_MODEL,
    instructions="You are a helpful assistant.",
    harness=MicrosoftCopilotHarness(),
    rai_config=RaiConfig(rai_policy_name=RAI_POLICY_ID),
)

Create an egress-only policy with REST

Use the Azure Resource Manager RAI Policies - Create Or Update operation with API version 2026-05-15-preview. This example allows *.contoso.com and denies other direct traffic:

TOKEN=$(az account get-access-token --resource "https://management.azure.com" --query accessToken -o tsv)

curl -X PUT \
  "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>?api-version=2026-05-15-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "mode": "Blocking",
      "basePolicyName": "Microsoft.DefaultV2",
      "contentFilters": [],
      "egressPolicy": {
        "mode": "Enforced",
        "defaultAction": "Deny",
        "rules": [{
          "name": "allow-contoso",
          "ruleType": "Fqdn",
          "match": { "host": "*.contoso.com" },
          "action": { "actionType": "Allow" }
        }]
      }
    }
  }'

Use the resulting policy's full ARM resource ID in the authoring method you select.

Create a new agent version when you attach a policy or change the policy reference. Editing rules in the referenced policy doesn't require a new agent version, but a running harness execution environment doesn't reload policy changes. Start a new conversation before you test the current rules. Use Shell and curl to send direct requests to one allowed and one denied host. During this preview, verify the network result directly; a separate Network egress decision span might not appear in the harness response trace.

For general connection guidance, see Identity and authentication for tools.

Review limits and availability

Before deploying, use Copilot harness limits and availability to verify that:

  • The Foundry project is in a supported region.
  • The selected model and tools are available in that region.
  • The agent definition and response requests don't use unsupported fields or operations.

Unsupported fields and operations return an error instead of being ignored.

Troubleshoot harness availability

Confirm that the project region, selected model, subscription, portal or client version, and your role meet the public preview requirements. If the project predates the preview, create a new prompt agent rather than attempting to change an existing agent's harness.

Related content

Use these articles to build a complete harness workflow:

  • Last updated on