[ext-agents]: no Next: guidance after core `azd provision` (and only partial after `azd deploy`)
- 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
Assessment
This issue has not been assessed yet.