# Discovery Services Agent Deployer

> Deploy Discovery catalog agents end-to-end with one command: discover the agent, build and bind its tool when present, skip tool stages for agents without tools, deploy the agent, and optionally run validation. Use this skill whenever the user asks to deploy a Discovery agent, publish or rebuild an agent tool image, register a Discovery tool from a repo Dockerfile/tool.yaml, resume a failed deployment, or produce a dry-run deployment plan for an agent in this catalog.

- Skill: `microsoft/discovery-services-agent-deployer` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add microsoft/discovery-services-agent-deployer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/discovery-services-agent-deployer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/microsoft/discovery-services-agent-deployer

---


# Discovery Agent Deployer

## Compatibility

Runs on Windows, macOS, and Linux through PowerShell 7+ (`pwsh`). Requires `git`, `python` with `pip`, and Azure CLI (`az`). Docker is optional because the runner can use Azure Container Registry Tasks when local Docker is unavailable.

New configurations default to Discovery GA `2026-06-01`. Explicit preview versions in local configs and saved runs remain unchanged. See [configuration](references/configuration.md) for version-specific validation routes and knowledge-base binding formats.

## What this skill does

Deploy one or more Discovery catalog agents from this repository with a single deterministic runner:

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 <agent-name>
```

The single PowerShell script discovers the agent folder, selects its tool folder when present, builds and pushes the image, creates or updates the `Microsoft.Discovery/tools` resource, patches a run-local copy of `agent.yaml`, deploys the agent, validates it with a temporary investigation, and prints a final summary. If the agent has no tool, it skips `build` and `deploy-tool` and continues with agent deployment. It persists stage status to `stage-todos.json` in the run directory so the invoking assistant can keep native Copilot task tracking in sync without duplicating progress logs.

Agent deployment sets `humanInTheLoop` and every bound tool's `confirmation` to `Disabled`, even if the source YAML enables them. This persists for subsequent uses of the deployed agent, not just validation. The source YAML is unchanged. This does not bypass Supercomputer nodepool confirmation, platform-required actions, or approval requests in agent instructions; unexpected validation approvals still require user input.

## When to use

Use this skill for requests like:

- "/discovery-services-agent-deployer `chembl`"
- "/discovery-services-agent-deployer `chembl` `aizynthfinder`"
- "Deploy the `aizynthfinder` agent"
- "Build and publish the tool image for this Discovery agent"
- "Create the Discovery tool resource from this agent's Dockerfile and tool.yaml"
- "Resume the failed deployment in this run folder"
- "Show me what would be deployed for this agent before running it"

If the user only wants inventory, use the `discovery-catalog` skill instead.

## Customer inputs

The happy path needs only the agent name. Optional parameters reduce rework or make automation explicit:

| Parameter | Purpose |
|---|---|
| `<agent-name> [agent-name...]` or `-AgentName <name>[,<name>...]` | Agent folder name under `agents/`. Positional names are preferred for slash-style use such as `/discovery-services-agent-deployer chembl aizynthfinder`. Required unless resuming. |
| `-PublisherName <name>` | **Deprecated.** Tolerated for backwards compatibility but ignored — agents live in the flat `agents/<agent-name>/` layout with no publisher folder. The deployer prints a one-line deprecation notice when the flag is supplied. |
| `-BuildMode auto\|remote\|local` | Defaults to `auto`; if input is required, ask the customer for `remote` or `local`. Do not store build mode in `config.json`. |
| `-Resume <RunDir>` | Continues from a prior checkpointed run. |
| `-Stage init\|build\|deploy-tool\|deploy-agent\|validate\|summary\|stop` | Runs exactly one stage, allowing Copilot to update native TODOs between terminal commands. |
| `-RunDir <RunDir>` | Required with `-Stage` after `init`. |
| `-ConfirmSupercomputerNodepools` | Run-scoped confirmation that the customer chose Proceed for the current run's tool/SKU plan. Do not store this in `config.json`. |
| `-ValidationPrompt <prompt>` | Run-scoped validation prompt generated by Copilot from the deployed agent/tool context. Overrides config `testPrompt` for this run. |
| `-SkipValidation` | Deploys without the post-deploy investigation test. |
| `-WhatIfPlan` | Prints repo discovery and planned stages without Azure calls. |

Local environment values live in `.github/skills/discovery-services-agent-deployer/config.json`, copied from `config.template.json`. The populated file is intentionally gitignored; never commit it. Never assume the file exists. Stage 1 must verify these required values are present: `subscriptionId`, `resourceGroup`, `acrName`, `location`, `workspaceEndpoint`, `project`, `tenantId`, `chatModel`, and `forceToolImageRebuild`. `acrResourceGroup` is optional and is used when ACR is in a different resource group from Discovery resources. `testPrompt` is optional; when present and non-empty it overrides Copilot-generated validation prompts. For every missing required value, ask the user only for fields listed in `CONFIG_FIELDS_TO_COLLECT`; do not choose from examples or defaults yourself. Do not store `buildMode` or `confirmSupercomputerNodepools` in `config.json`; both are per-run choices.

## Workflow

1. For planning or uncertain agent names, run `-WhatIfPlan` first.
2. Before creating native Copilot TODOs, validate every requested agent exists at `agents/<agent-name>/agent.yaml`.
3. If any requested agent is missing, do not create deployment TODOs; stop and ask the user to fix the name.
4. After validation succeeds and before starting deployment work, create the native Copilot TODO list for every requested agent.
5. For deployment, invoke the single runner from the repo root.
6. If the runner emits `CONFIG_INPUT_REQUIRED=true`, ask the user for the listed values in Copilot chat, write the ignored `config.json`, then rerun the stage. Do not fill missing fields from defaults, examples, or prior assumptions without a user answer.
7. If the runner emits `BUILD_MODE_INPUT_REQUIRED=true`, ask the user to choose `remote` or `local`, then rerun with `-BuildMode <choice>`. Do not write `buildMode` to `config.json`.
8. Before building a tool, show the `TOOL_BUILD_PLAN` with image and `recommendedSkus`. When the runner emits `SUPERCOMPUTER_NODEPOOL_CONFIRMATION_REQUIRED=true`, stop immediately and ask the customer the exact question in the `COPILOT SUPERCOMPUTER NODEPOOL INPUT REQUEST` block through the assistant choice-prompt UI, not as plain text. In this CLI, use the `ask_user` tool with exactly these choices: `Proceed - I have Supercomputer nodepool capacity for at least one listed SKU.` and `Stop - I do not have the required Supercomputer nodepool capacity.` Do not continue, do not infer Proceed, and do not run with `-ConfirmSupercomputerNodepools` until the customer explicitly chooses Proceed. If Proceed, rerun the build with `-ConfirmSupercomputerNodepools`; if Stop, run `-Stage stop -RunDir <RunDir>`.
9. Before validation for tool-backed agents, use this priority order for the validation prompt: explicit `-ValidationPrompt`, then non-empty config `testPrompt`, then Copilot-generated prompt. If the runner emits `VALIDATION_PROMPT_INPUT_REQUIRED=true`, do not ask the user; generate the prompt yourself from the `COPILOT VALIDATION PROMPT REQUEST` block and rerun `-Stage validate -ValidationPrompt "<generated prompt>"`.
10. If validation fails or semantically reports blocked/failed output, mark `validate` failed and `summary` stopped. Read `validation-result.json` when available.
11. If a stage fails, fix the reported issue and rerun with `-Resume <RunDir>`, except for nodepool Stop where the user should rerun the skill later after capacity is available.
12. Report the final summary printed by the runner; do not invent status from partial logs.

For slash-style requests like `/discovery-services-agent-deployer chembl aizynthfinder`, treat the words after the skill name as positional agent names and invoke the runner as:

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 chembl aizynthfinder
```

## Copilot task tracking

When running in VS Code GitHub Copilot or any environment that exposes a task/TODO UI above the prompt, the native TODO list is required for deployments. Create the TODOs only after all requested agent names pass preflight validation, but create them before invoking the long-running deployment path.

For agents with a tool, create the six-stage TODO list:

1. `init` - discover agent, validate prerequisites, collect config, create run directory
2. `build` - build and push the tool image
3. `deploy-tool` - create or update the Discovery tool resource
4. `deploy-agent` - patch the run-local agent YAML and deploy the agent
5. `validate` - run the post-deployment investigation test, unless `-SkipValidation` is set
6. `summary` - print and report final deployment summary

For agents without a tool, create only the four relevant TODOs: `init`, `deploy-agent`, `validate`, and `summary`. Do not create native TODO items for `build` or `deploy-tool`; the runner skips those stages internally.

To keep the native TODO UI accurate, use stage-at-a-time execution instead of one long end-to-end command whenever the TODO UI is visible. Mark the matching TODO `in_progress`, run exactly one stage, then mark it `done` only after the command exits successfully or emits `TASK_STATUS=<stage>:done`. If the runner emits `TASK_STATUS=<stage>:input_required`, collect the requested input in Copilot chat and rerun the same stage rather than marking it failed. For nodepool input, present the Proceed/Stop question through the available choice-prompt mechanism (`ask_user` in this CLI), never as a plain-text “reply with Proceed or Stop” message, and never self-confirm by immediately rerunning with `-ConfirmSupercomputerNodepools`. Do not start the next stage command until the native TODO state visibly reflects the completed stage. If the command output shows `TASK_STATUS=deploy-agent:done`, update `deploy-agent` to done before running `validate`; if it shows `TASK_STATUS=validate:done`, update `validate` to done before running `summary`. The runner also emits `TASK_PLAN=<agent>/<stage>` lines immediately after preflight succeeds; use these as a final prompt to create any missing native TODOs before stage work begins. Mark the active TODO `failed` if the stage command fails, then report the `-Resume <RunDir>` command.

Before sending the final success response, reconcile the native TODO list with the runner output. If validation and summary succeeded, the visible TODOs for `deploy-agent`, `validate`, and `summary` must be marked done. Never report "all stages succeeded" while any visible deployment TODO remains in progress or pending.

For two or more agents, create a separate TODO set per agent and include the agent name in each TODO label, for example `chembl / build` and `online-researcher / deploy-agent`. Use six TODOs for tool-backed agents and four TODOs for agents without tools. Run stages sequentially per agent using `-Stage`; this gives Copilot a chance to update `chembl / build` before starting `chembl / deploy-tool`. The end-to-end multi-agent runner remains available for automation, but it should not be used when the user expects the native Copilot TODO UI to advance during the run.

If no task/TODO UI is available, use the concise `[runner] START/DONE/SKIP` lines and `stage-todos.json` as the progress record.

### Stage-at-a-time command sequence

Use this pattern when native Copilot TODOs are visible:

```powershell
# init emits RUN_DIR=<path>; capture it for later stages
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 chembl -Stage init
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -RunDir <RunDir> -Stage build
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -RunDir <RunDir> -Stage deploy-tool
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -RunDir <RunDir> -Stage deploy-agent
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -RunDir <RunDir> -Stage validate -ValidationPrompt "<Copilot-generated validation prompt>"
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -RunDir <RunDir> -Stage summary
```

After each command returns, update the matching native TODO before issuing the next command. This pause is part of the workflow, not optional; Copilot cannot reliably update the TODO UI after several stages have already been run in one uninterrupted sequence.

## Commands

### Dry-run plan

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -AgentName aizynthfinder -WhatIfPlan
```

Equivalent positional form:

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 aizynthfinder -WhatIfPlan
```

### Dry-run or deploy multiple agents

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 chembl aizynthfinder -WhatIfPlan
```

### Deploy with automatic build mode

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -AgentName aizynthfinder
```

### Force remote ACR build

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -AgentName aizynthfinder -BuildMode remote
```

### Resume a failed run

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .github/skills/discovery-services-agent-deployer/scripts/deploy-discovery-agent.ps1 -Resume agents/tmp/aizynthfinder/20260508-172700
```

## Reporting contract

When the runner completes, summarize:

- `RUN_DIR`
- `IMAGE_REF`
- `TOOL_RESOURCE_ID` if available
- stage TODO statuses from native Copilot task tracking or `stage-todos.json`
- stage statuses from `SUMMARY_STAGE_*`
- validation status (`passed`, `pending`, or skipped)

If the runner fails, report the failed stage, the action required from the script output, and the exact `-Resume <RunDir>` command when a run directory exists.

## References

- `references/configuration.md` - local config fields and Copilot-style input behavior
- `references/operations.md` - runner behavior, checkpoints, and resume model
- `references/troubleshooting.md` - common failures and recovery steps

Keep `SKILL.md` lean. Prefer the single public runner and references over ad-hoc scripts or long manual instructions. The deployer implementation is intentionally consolidated into `scripts/deploy-discovery-agent.ps1` so there is only one executable script to maintain.

