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 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:

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:

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:

# 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

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

Equivalent positional form:

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

Dry-run or deploy multiple agents

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

Deploy with automatic build mode

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

Force remote ACR build

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

Resume a failed run

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.