Create Managed Harness Agent
Create or continue developing a Microsoft Foundry Managed Harness Agent with azd. A Managed Harness Agent is a Prompt Agent running on the Foundry-managed Copilot harness:
kind: prompt
harness:
type: microsoft_copilot_previewUse this workflow only when the user explicitly says Managed Harness Agent, Copilot harness agent, or Prompt Agent with Copilot harness. Ordinary Prompt Agents use create-prompt.md; Hosted Agents use create-hosted.md.
Boundaries
- Use azd and
azure.yamlas the source of truth. - Do not use Hosted samples, local runtime, sessions, files, or monitor commands.
- Do not convert an existing Prompt, Hosted, or Managed Harness Agent to another type. Create a new Agent instead.
- New authoring uses the Microsoft discriminator family. Existing Microsoft, legacy GitHub, or mixed discriminator families are preserved exactly as authored during ordinary edits and redeploys.
- Prefer direct tools. Use a Toolbox only when the user explicitly requests one.
- Consume a connection, Toolbox, or Skill supplied by the user or already referenced in the project. Create one only when explicitly requested.
- Supported direct tools: Copilot built-ins, Code Interpreter, File Search, Web Search, MCP, Azure AI Search, OpenAPI, Agent-to-Agent, Work IQ, and Fabric IQ.
- Do not generate an evaluation suite in this workflow.
Read Managed Harness Agent Authoring and Managed Harness Agent Tools before editing azure.yaml.
Workflow
Step 1: Verify the environment
Run the bundled preflight and verification scripts:
./scripts/check-copilot-app-entry.sh
./scripts/verify-environment.sh./scripts/check-copilot-app-entry.ps1
./scripts/verify-environment.ps1Follow their [ACTION] output. Never run az login or azd auth login for the user. Before any azd command, follow azd guidance.
Step 2: Select new or existing project
Inspect azure.yaml:
- One service with
kind: promptandharness.type: microsoft_copilot_previewor legacygithub_copilot_preview-> continue development. - Multiple Managed Harness Agent services -> ask the user to select one.
- Existing non-Managed Harness Agent service -> do not convert it; add a new service only when the user wants a new Managed Harness Agent.
- No azd project -> initialize a new Managed Harness Agent.
Do not fetch a remote Managed Harness Agent and synthesize azure.yaml.
Step 3: Collect unresolved values
Resolve values from the request, azure.yaml, and azd env get-values before asking:
- Agent and project name.
- New or existing Foundry project.
- Existing project ARM ID when applicable.
- Subscription and region for new infrastructure.
- Model name for a new deployment, or existing model deployment name.
- Instructions and requested tools.
A Managed Harness Agent does not need language, runtime, entry point, deploy mode, Docker, or ACR.
Step 4: Initialize or update
For a new Managed Harness Agent, run non-interactively:
azd ai agent init --no-prompt \
--kind prompt \
--harness microsoft_copilot_preview \
--agent-name "<agent-name>" \
--model "<model-name>"For an existing project/model deployment, use:
azd ai agent init --no-prompt \
--kind prompt \
--harness microsoft_copilot_preview \
--agent-name "<agent-name>" \
--project-id "<project-arm-id>" \
--model-deployment "<deployment-name>"The preview --harness flag may be hidden from help. If rejected, verify the installed azure.ai.agents extension version; do not replace it with a Hosted manifest.
After init completes, enter the generated project directory before running azd env set. For a new project set subscription, location, and project name. Do not chain these commands to init.
For an existing Managed Harness Agent, edit azure.yaml in place. Rerunning init can create a suffixed duplicate service.
Step 5: Validate the definition
Confirm:
host: azure.ai.agentkind: prompt- New definitions use
harness.type: microsoft_copilot_preview. - Existing definitions retain their authored
microsoft_copilot_previewor legacygithub_copilot_previewvalue. - Existing Copilot toolset discriminators are preserved rather than normalized.
- Model and instructions match the request.
- No Hosted-only
codeConfiguration, Docker, container, runtime, or protocol fields.
Preserve unrelated services and unknown user-authored fields.
Step 6: Add capabilities
Read the matching Managed Harness Agent reference before editing:
| Capability | Reference |
|---|---|
| Copilot built-ins | Copilot Toolset |
| Web Search | Web Search |
| Code Interpreter | Code Interpreter |
| File Search | File Search |
| MCP server | MCP |
| Azure AI Search | Azure AI Search |
| OpenAPI | OpenAPI |
| Agent-to-Agent | Agent-to-Agent |
| Work IQ | Work IQ |
| Fabric IQ | Fabric IQ |
| Toolbox | Toolbox |
For connection-backed tools, use only a connection supplied by the user or already present in the Managed Harness Agent configuration. If missing, leave a clear placeholder or stop and request the value. Create it only when explicitly requested.
If the user explicitly requests a Toolbox, follow the Managed Harness Agent Toolbox workflow. Create or reuse the Toolbox and its matching authenticated project connection separately, then attach the exact versioned endpoint as a direct MCP tool.
For Foundry Skills, follow Managed Harness Agent Skills. Manage the Skill separately with azd ai skill, then pin its existing version in the Agent's top-level skills list.
Step 7: Deploy and invoke
Continue with the independent Managed Harness Agent branches in deploy and invoke. There is no local harness runtime gate.
Error Handling
| Error | Resolution |
|---|---|
--harness rejected |
Update/verify azure.ai.agents; the flag is preview and hidden |
| Prompt init requires a model | Supply --model, or --project-id plus --model-deployment |
Duplicate <agent>-2 service |
Remove the unintended duplicate and edit the original Managed Harness Agent in place |
| Deploy succeeds without harness | Treat as failure; verify kind and harness in the published definition |
| Tool rejected by Foundry | Compare the REST-shaped fields with the Managed Harness Agent tool reference |