Managed Harness Agent Authoring
A Microsoft Foundry Managed Harness Agent is a Prompt Agent configured with the Foundry-managed Copilot harness. This skill uses azd to author and deploy it:
services:
assistant:
host: azure.ai.agent
kind: prompt
name: assistant
model: gpt-5-mini
instructions: Help the user.
harness:
type: microsoft_copilot_previewUse REST field names, normally snake_case, inside tools[]. azd strictly validates the harness and Copilot toolset; most other nested tool fields pass through to Foundry.
Compatibility
- New authoring uses
microsoft_copilot_previewand, when declared,microsoft_copilot_toolset_preview. - Existing
github_copilot_previewandgithub_copilot_toolset_previewvalues remain accepted. - Preserve the exact harness and toolset discriminator values already present, including mixed existing definitions. Do not migrate them during read, edit, save, redeploy, or revision flows.
- Author
defaultConfiginazure.yaml; azd translates it to RESTdefault_configonly at the API boundary. - Both discriminator families use
Foundry-Features: MicrosoftCopilot=V1Preview. Do not retry with the legacyGitHubCopilot=V1Previewheader.
Direct tools
Prefer direct tool definitions unless the user explicitly requests a Toolbox:
tools:
- type: web_search
- type: code_interpreterRead Managed Harness Agent Tools for the supported tools, required fields, connections, and per-tool authoring references.
Toolbox attachment
A Managed Harness Agent prefers direct tools. When the user explicitly requests a Toolbox, manage it separately with azd ai toolbox, create or reuse a matching authenticated project connection, then attach its exact versioned MCP endpoint as a direct tool:
tools:
- type: mcp
server_label: research-tools
server_url: https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox>/versions/<version>/mcp?api-version=v1
project_connection_id: <toolbox-connection>
require_approval: alwaysThe connection must be RemoteTool with UserEntraToken, audience https://ai.azure.com, and target exactly equal to server_url. See Toolbox for creation, reuse, metadata, and validation. Do not use connectionless Toolbox MCP.
Skill attachment
Create and version Skills separately with azd ai skill. Reference an existing Foundry Skill by name and immutable version:
skills:
- name: issue-triage
version: "3"For a local Skill, upload it first:
azd ai skill create issue-triage \
--file ./skills/issue-triage/ \
--project-endpoint "<project-endpoint>" \
--output jsonUse the returned version in azure.yaml. For updates, run azd ai skill update and replace the pinned version.
Do not declare host: azure.ai.skill in this phase: that would make azd deploy manage the Skill lifecycle.
Validation
After deploy, read the published definition and verify:
kindremainsprompt.- New definitions use
microsoft_copilot_preview; existing definitions retain their authored Copilot harness discriminator. - Direct tools retain their authored fields.
- Existing Copilot toolset discriminators remain unchanged.
- The versioned Toolbox MCP endpoint and matching
project_connection_idremain in the directmcptool. - Skill references retain both
nameandversion.
Managed Harness Agents, ordinary Prompt Agents, and Hosted Agents are not converted in place.