Create Managed Harness

Use 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.yaml as 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:

Follow 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: prompt and harness.type: microsoft_copilot_preview or legacy github_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:

For an existing project/model deployment, use:

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.agent
• kind: prompt
• New definitions use harness.type: microsoft_copilot_preview.
• Existing definitions retain their authored microsoft_copilot_preview or legacy github_copilot_preview value.
• 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:

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