Azure / Azure/azure-dev

[ext-agents]: no Next: guidance after core `azd provision` (and only partial after `azd deploy`)

Open
#8,804 0 comments 0 reactions 1 assignee Claimed by @huimiu View on GitHub
area/core-cli area/ux enhancement ext-agents
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Summary

The `azd ai agent` extension subcommands (`init`, `run`, `invoke`, `show`,
`doctor`) end with a state-aware `Next:` guidance block. But the two core
commands that sit in the middle of the Foundry agent dev journey --
`azd provision` and `azd deploy` -- do not surface equivalent next-step
guidance:

* After `azd provision` there is NO `Next:` block at all (e.g. nudging the user
toward `azd deploy`, `azd ai agent run`, or `azd ai agent invoke`).
* After `azd deploy`, next-step guidance is only embedded inside the per-service
deploy artifact note; there is no consolidated top-level post-deploy `Next:`
summary equivalent to what the subcommands print.

Because `provision` and `deploy` are core azd commands (not extension
subcommands), the extension cannot print to stdout the same way it does for its
own subcommands. This issue tracks how to bring next-step guidance to that part
of the journey. Filing per discussion; may be parked pending core-framework
support.

## Current behavior / where guidance comes from

Extension subcommands write the block directly to stdout via
`printNextIfTerminal` / `printAllNextIfTerminal`
(`internal/cmd/nextstep_output.go`):

* init: `internal/cmd/init.go` (~L2714), `internal/cmd/init_from_code.go`
(~L181)
* run: `internal/cmd/run.go` (~L850)
* invoke: `internal/cmd/invoke.go` (~L409, ~L441)
* show: `internal/cmd/show.go` (~L371)
* doctor: `internal/cmd/doctor.go` (~L185)

For the core commands, the extension hooks project lifecycle events in
`internal/cmd/listen.go`:

```go
WithProjectEventHandler("postprovision", ...postprovisionHandler...) // listen.go ~L45
WithProjectEventHandler("postdeploy", ...postdeployHandler...) // listen.go ~L51
```

* `postprovisionHandler` (listen.go ~L75) provisions toolboxes and clears the
`AI_AGENT_PENDING_PROVISION` signal. It emits no `Next:` block, and there is
no `ResolveAfterProvision` resolver in the `nextstep` package.
* `postdeployHandler` (listen.go ~L201) does agent-identity RBAC work, not
next-step rendering.
* Post-deploy guidance that DOES exist is rendered into the per-service deploy
artifact note by the service target:
`internal/project/service_target_agent.go` (~L1994-1999) calls
`nextstep.ResolveAfterDeploy` + `nextstep.FormatNextForNote`. There is no
`ResolveAfterProvision` analog and no top-level post-deploy summary.

## Why this matters

The intended Foundry agent journey is roughly: `azd ai agent init` ->
`azd provision` -> `azd deploy` -> `azd ai agent invoke`. The extension guides
the user at the init bookend and the invoke bookend, but goes quiet across the
two core steps in the middle -- exactly where a first-time user is most likely
to wonder "what now?". After `azd provision` completes, nothing points them to
`azd deploy`; after `azd deploy`, the only hint is buried in an artifact note.

## Open questions / core-framework dependency

* Lifecycle event handlers (`postprovision` / `postdeploy`) run inside core's
provision/deploy progress UI and return only `error` -- they have no
documented contract for writing a clean `Next:` block to the user's terminal
at the right place relative to core's own command summary. Printing directly
from a handler risks interleaving with core output.
* Does core expose (or should it expose) a supported way for an extension to
contribute a post-command "next steps" block to `azd provision` /
`azd deploy` output? If yes, the extension can add a `ResolveAfterProvision`
resolver and route both provision and deploy through it.
* Decide whether deploy's per-service artifact note is sufficient or whether a
consolidated top-level post-deploy block is also wanted.

## Suggested direction

1. Add a `ResolveAfterProvision` resolver in `internal/cmd/nextstep` that, given
the post-provision `State`, suggests the next action (`azd deploy`, or
`azd ai agent run` / `invoke` as appropriate).
2. Render it from `postprovisionHandler` IF core supports clean terminal output
from lifecycle handlers; otherwise track the core enhancement needed to
support extension-contributed next-step blocks for core commands.
3. Reconcile the deploy path so post-deploy guidance is consistent (artifact
note vs. top-level summary).

This likely needs a core-framework change; reasonable to leave the extension
as-is until that lands.

## Environment

* azd AI Agent extension: v0.1.41-preview
* File references are from a local working copy; line numbers approximate.

## Related

* #7975 (closed) -- introduced post-command `Next:` guidance; explicitly scoped
to `init`, `run`, `invoke`, `show`, and `deploy` (via post-deploy hooks).
`azd provision` was out of scope.
* #8710 -- migrate next step suggestions + doctor to unified azure.yaml.
* #8730 -- post-deploy `Next:` block readability.
* #8587 -- `azd provision ` multi-service behavior.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.