feat(azure.ai.agents): agent-driven init pre-flow + --from-code routing by therealjohn · Pull Request #8376 · Azure/azure-dev

therealjohn · 2026-05-26T19:30:09Z

What this adds

Reshape azd ai agent init so the opening prompts hand the developer's coding agent everything it needs to drive the rest of setup, then get out of the way. The new pre-flow asks five short questions:

Which coding agent are you using? (Copilot CLI, Claude Code, etc.)
Should I install the azd-ai-skill pack into your agent?
Copy the starter prompt to your clipboard?
Pick (or create) a Foundry project.
Pick (or create) a model deployment.

From there, the developer pastes the starter prompt into their coding agent and the agent drives init / provision / deploy from inside their editor, using the installed SKILL.md as its instruction set. The starter prompt already carries the chosen Foundry project ID and model deployment, so the agent has the right context before its first command.

The pre-flow also adds a --from-code flag for the "I already have agent source, just wire it up" case (brownfield repos with hand-written agent code) and detects bootstrap-only directories so it can short-circuit cleanly when the cwd has no manifest yet.

Why it matters

azd ai agent init today assumes a human is sitting at the terminal answering prompts. Developers who want their coding agent to drive setup have to copy-paste sample commands, screen-share, or guess at the right flag combinations. There's no in-the-box affordance for handing setup off to an AI assistant.

This PR turns "let my coding agent set this up for me" into a first-class option. Two short questions in, the developer is back in their editor and the agent is running the show -- with the right skill pack installed, the right starter prompt loaded, and the right Foundry resources already chosen.

Together with the azure.ai.docs extension (separate PR), this is the developer-facing half of an agent-driveable azure.ai.* surface.

Dependencies

The pre-flow dispatches into azure.ai.docs for the skill install step via the extension framework -- no compile-time dependency. The branch builds and tests standalone.
One new external Go dependency: github.com/atotto/clipboard (cross-platform clipboard with graceful fallback in CI / SSH / TERM=dumb environments).

Scope

Touches azd ai agent init and its supporting helpers; no other commands change here.
Includes a new shared internal/helpformat package (used by init's styled --help); the rest of the agents commands will be migrated to it in a follow-up PR.
--output json / confirmation-envelope migration on write commands is explicitly out of scope and will land separately.

Helps fix #6819

Reshape `azd ai agent init` so the opening prompts are a five-question pre-flow that hands the developer's coding agent everything it needs to drive the rest of setup: 1. Which coding agent are you using? (Copilot CLI, Claude Code, etc.) 2. Should I install the `azd-ai-skill` pack into your agent? (dispatches to `azd ai doc skills install --target <tool>` via the extension framework -- no compile-time dependency on `azure.ai.docs`). 3. Copy the starter prompt to your clipboard so you can paste it into your agent. 4. Pick (or create) a Foundry project -- prompts for subscription and location when creating, and propagates the tenant ID for model catalog access. 5. Pick (or create) a model deployment -- shows the AI model catalog with quota and capacity checks when creating new. The agent then drives `init` / `provision` / `deploy` from inside the developer's editor by reading the installed `SKILL.md`, with the selected Foundry project ID and model deployment name already woven into the starter prompt. ## Key additions * `init_preflow.go` + tests -- the five-question pre-flow, idempotent detection of an existing setup, clipboard handoff, tagline banner, and preflow-specific subscription/location/catalog helpers (`promptSubscriptionAndLocationPreflow`, `selectModelCatalogPreflow`) that stay lightweight by NOT writing to the azd environment until after the flow completes. * `ext_lookup.go` + tests -- cross-extension lookup/dispatch helpers built on `azdext` gRPC. Used to detect `azure.ai.docs` and call its `skills install` command without importing it. * `starter_prompt.go` + `starter_prompts/agent_init.md` + tests -- embedded starter prompt template (`go:embed`), brief by design (under 100 words, enforced by `TestRenderStarterPrompt_IsBrief`), with cross-platform clipboard support (`github.com/atotto/clipboard`) and headless-environment detection (CI, SSH, `TERM=dumb`). Conditionally emits Foundry project ID and model deployment hints when supplied. * `--from-code` flag on `init` (`init.go` + `init_from_templates_helpers.go`) -- skip manifest discovery when the cwd already has hand-written agent source. Detects "bootstrap-only" directory state (housekeeping files only) and routes through the from-code path so the pre-flow can short-circuit cleanly. * `init_foundry_resources_helpers.go` -- new helpers reused by the pre-flow: `FoundryProjectInfo` now carries `TenantId` for model catalog access, and the catalog-loading hang under guest-user contexts is fixed by including the tenant ID in `AzureContext`. * Styled `--help` for `init` via the new `internal/helpformat` package (`Description` / `Note` / `Command` / `Flag` builders), shared with the future `azure.ai.docs` extension. Suppresses the banner in `init --no-prompt` so scripted output stays clean. ## Dependencies * `azure.ai.docs` is referenced as an **extension ID string only** (`"azure.ai.docs"`); the pre-flow uses `azdext` gRPC to install the skill pack at runtime. This branch builds and tests standalone off `upstream/main`. * New external dependency: `github.com/atotto/clipboard v0.1.4` (cross-platform clipboard, ~150 LOC; falls back gracefully in headless environments). * `internal/helpformat` package is included here because `init.go` uses it for styled help; the same package will be wired into the rest of the agents extension and into `azure.ai.docs` in follow-up PRs. ## Testing * `go build ./...` and `go test ./internal/cmd/... -short` pass. * New tests: `init_preflow_test.go` (preflow structural + behavior tests), `init_prompt_mode_test.go`, `ext_lookup_test.go`, `starter_prompt_test.go` (Foundry-project-ID + model-deployment substitution + brevity cap + clipboard outcomes), `ensure_project_helpers_test.go`, plus the existing `init_test.go` extended for the new flags. `helpformat_test.go` covers the help builders. * `cspell` clean with new agent-pre-flow / helpformat identifiers added to the extension's local `cspell.yaml` (`helpformat`, `cmdhelp`, `preflow`, `scaffolder`, `atotto`, `xclip`). ## Out of scope (deferred to follow-up PRs) * Styled `--help` for every other agents command (wired only on `init` here). * Bulk migration of `--output json` flags / confirmation envelope on write commands. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR reshapes azd ai agent init in the azure.ai.agents extension to support an agent-driven interactive “pre-flow” that installs an AI skill pack (via azure.ai.docs), prints/copies a starter prompt, and then hands control to a coding agent; it also adds --from-code routing and introduces a shared help-output styling package for consistent --help formatting.

Changes:

Add a new interactive init pre-flow (InitPreflowAction) that can install the AZD AI skill (cross-extension), select Foundry project + model deployment, render a starter prompt, and optionally copy it to the clipboard.
Add --from-code and deterministic init-mode validation/routing improvements, including “bootstrap-only directory” handling via minimal azure.yaml creation in non-empty directories.
Introduce internal/helpformat to render styled Cobra help output (plus unit tests), and migrate init help content into styled Description/Examples builders.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
cli/azd/extensions/azure.ai.agents/internal/helpformat/helpformat.go	New shared helper to render styled Cobra `--help` output (usage/flags/commands/examples).
cli/azd/extensions/azure.ai.agents/internal/helpformat/helpformat_test.go	Unit tests for help styling behaviors and template safety regressions.
cli/azd/extensions/azure.ai.agents/internal/cmd/starter_prompts/agent_init.md	Embedded starter prompt template used by the init pre-flow.
cli/azd/extensions/azure.ai.agents/internal/cmd/starter_prompt.go	Starter prompt rendering + clipboard copy helper with headless/CI heuristics.
cli/azd/extensions/azure.ai.agents/internal/cmd/starter_prompt_test.go	Unit tests for prompt rendering and clipboard outcome handling.
cli/azd/extensions/azure.ai.agents/internal/cmd/init.go	Wires pre-flow into `init`, adds `--from-code`, validates flag combinations, improves bootstrap handling, and installs styled help.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_test.go	Adds tests for `--from-code` flag registration and init-mode flag conflict validation.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_prompt_mode_test.go	New tests pinning init-mode routing behavior (from-code wins, empty dir => template, no-prompt => suggestion).
cli/azd/extensions/azure.ai.agents/internal/cmd/init_preflow.go	Implements the interactive agent-driven pre-flow (skill install, clipboard, Foundry project + model selection).
cli/azd/extensions/azure.ai.agents/internal/cmd/init_preflow_test.go	Structural/unit tests for pre-flow targets and ready-to-go messaging.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_from_templates_helpers.go	Updates init-mode selection logic to incorporate `--from-code` and deterministic non-interactive behavior.
cli/azd/extensions/azure.ai.agents/internal/cmd/init_foundry_resources_helpers.go	Adds pre-flow helpers for subscription/location/model catalog selection without env writes; extends FoundryProjectInfo with TenantId.
cli/azd/extensions/azure.ai.agents/internal/cmd/ext_lookup.go	Adds `azd ext list/install` shell-out helpers to support cross-extension dispatch safely.
cli/azd/extensions/azure.ai.agents/internal/cmd/ext_lookup_test.go	Unit tests for extension lookup/install shell-out behavior.
cli/azd/extensions/azure.ai.agents/internal/cmd/ensure_project_helpers_test.go	Tests for empty-dir detection and minimal `azure.yaml` creation behavior.
cli/azd/extensions/azure.ai.agents/internal/cmd/banner.go	Adds `printTagline` to show the extension one-liner after the banner in interactive flows.
cli/azd/extensions/azure.ai.agents/go.mod	Adds clipboard dependency (currently marked indirect).
cli/azd/extensions/azure.ai.agents/go.sum	Adds checksum entries for the clipboard dependency.
cli/azd/extensions/azure.ai.agents/cspell.yaml	Adds new terms related to pre-flow/helpformat/clipboard to spell-check allowlist.

…s-init-preflow # Conflicts: # cli/azd/extensions/azure.ai.agents/internal/cmd/init.go

* init_preflow.go(installSkill): forward child stderr to a.out so failures from �zd ai doc skills install are visible (passing nil to exec.Cmd.Stderr discards stderr instead of inheriting). * starter_prompt.go(isHeadlessEnv): match azdext.isCIEnv with presence-based detection across CI/GITHUB_ACTIONS/TF_BUILD/JENKINS_URL/GITLAB_CI/CIRCLECI/TRAVIS/BUILDKITE/CODEBUILD_BUILD_ID. * init_preflow.go(askFoundryProject): when no Foundry projects are found, prompt for location and return a minimal FoundryProjectInfo{Sub,Tenant,Location} so Q5 (model deployment) keeps hasAzureContext=true and can browse the model catalog. * init_from_templates_helpers.go(promptInitMode): drop unused out io.Writer parameter; update call sites and comments. * go.mod: promote github.com/atotto/clipboard to a direct require (it is imported by production code in starter_prompt.go). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… unused) - init.go: use errors.Is(err, io.EOF) instead of err != io.EOF (errorlint). - starter_prompt_test.go: drop stray blank line (gofmt). - ext_lookup.go: annotate intentional `exec.CommandContext("azd", args...)` calls with #nosec G204. - ext_lookup_test.go: remove unused stdout/stderr fields from runCall. - helpformat_test.go: annotate documentation example with #nosec G101 (not a real credential). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The agent-driven onboarding preflow previously ran on every interactive `azd ai agent init` invocation. It is a high-touch flow that only makes sense for a true greenfield start, so running it for re-init or when the caller has scripted intent created a confusing detour. Add shouldRunPreflow() which suppresses the preflow when: * --no-prompt / AZD_NO_PROMPT is set (scripted) * any explicit init-mode or downstream config flag is set (--manifest, --from-code, --src, --project-id, --model-deployment, --model, --agent-name, --protocol, --deploy-mode, --runtime, --entry-point, --dep-resolution) * an agent manifest or bare agent.yaml already exists in the source directory (the downstream reuse flow handles that case) * the current directory already has azd configuration (azure.yaml / azure.yml / .azure) --force and --env are deliberately excluded because they only signal overwrite consent and environment binding, not authoring intent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Signed-off-by: trangevi <trangevi@microsoft.com>

… tests

…g started, environment variables, and documentation

Copilot AI review requested due to automatic review settings May 26, 2026 19:30

therealjohn requested review from JeffreyCA, trangevi and trrwilson as code owners May 26, 2026 19:30

Copilot started reviewing on behalf of therealjohn May 26, 2026 19:30 View session

microsoft-github-policy-service Bot assigned therealjohn May 26, 2026

Copilot AI reviewed May 26, 2026

View reviewed changes

github-actions Bot added the ext-agents azure.ai.{agents,connections,inspector,projects,routines,skills,toolboxes} extensions label May 26, 2026

therealjohn and others added 3 commits May 26, 2026 18:17

Merge remote-tracking branch 'upstream/main' into feat/azure-ai-agent…

1e79032

…s-init-preflow # Conflicts: # cli/azd/extensions/azure.ai.agents/internal/cmd/init.go

therealjohn marked this pull request as draft May 26, 2026 23:09

therealjohn marked this pull request as ready for review May 26, 2026 23:31

trangevi approved these changes May 27, 2026

View reviewed changes

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/ext_lookup.go

Comment thread cli/azd/extensions/azure.ai.agents/internal/cmd/init_preflow.go

trangevi added 2 commits May 27, 2026 17:13

Merge branch 'main' into therealjohn/feat/azure-ai-agents-init-preflow

0969539

Signed-off-by: trangevi <trangevi@microsoft.com>

linter

ee44911

Signed-off-by: trangevi <trangevi@microsoft.com>

trrwilson approved these changes May 28, 2026

View reviewed changes

therealjohn added 2 commits May 27, 2026 20:52

fix: update command syntax for installing skills in init pre-flow and…

b4b58fd

… tests

feat(help): add custom help output for agents with sections on gettin…

d44aea3

…g started, environment variables, and documentation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(azure.ai.agents): agent-driven init pre-flow + --from-code routing#8376

feat(azure.ai.agents): agent-driven init pre-flow + --from-code routing#8376
therealjohn wants to merge 9 commits into
Azure:mainfrom
therealjohn:feat/azure-ai-agents-init-preflow

therealjohn commented May 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

therealjohn commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Why it matters

Dependencies

Scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

therealjohn commented May 26, 2026 •

edited

Loading