feat(azure.ai.agents): qualify single-agent post-deploy Next: block (P5.1 C6, fix B9)

Fix B9 from issue Azure#7975 (lines 228-242). Pre-C6, `ResolveAfterDeploy`
stripped the agent name when there was exactly one agent service in
state, emitting:

  Next:  azd ai agent show                       -- verify the deployed agent is running
         azd ai agent invoke '<payload>'         -- send a sample request to the deployed agent

That output had two problems:

1. **`azd ai agent show` (no name)** runs interactive resolution that
   relies on the user's terminal state. When the artifact note is
   copy-pasted into a different project (or read days later when the
   single-agent project may have grown a second agent), the unqualified
   command picks the wrong target or prompts. The spec example at
   lines 231-232 shows the qualified form even in the single-agent
   case for exactly this copy-paste-safety reason.

2. **Description copy was generic** ("verify the deployed agent is
   running" / "send a sample request to the deployed agent"). Per
   spec lines 231-241 the descriptions are intentionally tighter and
   identify which agent each row refers to in the multi-agent layout.

C6 changes:

- `ResolveAfterDeploy` now always emits service-qualified commands
  regardless of `len(state.Services)`. The pre-C6 unqualified branch
  is gone.

- Descriptions reshape:
  * Single agent (`len(state.Services) == 1`):
    `verify it's running` / `test the deployment`
  * Multi-agent (`len(state.Services) >= 2`):
    `verify <name> is running` / `test <name>`

- Multi-agent layout now groups all `show` lines first, then all
  `invoke` lines (was interleaved per service). Matches spec example
  at lines 238-241. Single-agent output is unchanged in layout —
  with one service the pass-1/pass-2 split still produces show-then-
  invoke order.

- README hint placement: in the new pass-2 invoke loop the per-agent
  hint is emitted immediately after that agent's invoke line, so a
  reader can scan rows top-to-bottom and find each agent's hint in
  context. Single-agent placement is identical to pre-C6.

- `AfterDeployOpts.ForceQualified` is kept as a NO-OP for backward
  compatibility. Callers (doctor.go line 239 passes it for filtered
  states) still compile and produce identical output. The doc
  comment is updated to mark it as a no-op and explain why
  (the single-agent unqualified heuristic it overrode is gone).

Tests:

- `TestResolveAfterDeploy` rewritten — all single-agent expectations
  now assert qualified commands (`azd ai agent show echo` /
  `azd ai agent invoke echo '...'`) and per-spec descriptions.
- New subtest for multi-agent grouped ordering (shows-then-invokes)
  asserts shows in service-declaration order, then invokes in the
  same order, each row carrying the per-agent descriptive text.
- New subtest for README hint placement in the multi-agent layout
  asserts the hint follows the invoke line for the service that
  triggered it, even with the new grouped ordering.
- The two `ForceQualified` subtests are kept and rewritten as
  backward-compat assertions — they now compare against the
  no-opts baseline and prove the flag is a true no-op.

Caller impact:
- `doctor.go:235-239` passes `ForceQualified: totalServices > 1`.
  Output is identical to its old behavior (totalServices==1 used
  to emit unqualified; now emits qualified, but doctor's
  filtered-state callsite always wanted qualified anyway — that's
  literally the comment at the callsite).

Spec source: issue Azure#7975 lines 228-242 + the C6 row in the P5.1
commit plan.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor.go

@@ -218,25 +218,16 @@ func resolveDoctorTrailing(ctx context.Context, azdClient *azdext.AzdClient) []n
 	}
 
 	if anyServiceDeployed(state.Services) {
-		// Capture the total agent-service count BEFORE filtering. The
-		// resolver's `len(state.Services) == 1` heuristic ordinarily
-		// keys "should I emit no-arg show/invoke commands?" off the
-		// total count of agent services in azure.yaml. Once we filter
-		// to deployed-only, that heuristic breaks: a 2-service project
-		// with 1 deployed would emit `azd ai agent show` (no name),
-		// but runtime `resolveAgentService` still sees both services
-		// in azure.yaml and would either prompt or error. Forcing
-		// qualified suggestions whenever azure.yaml has multiple
-		// services preserves copy-paste correctness in the partial-
-		// deploy case and is a no-op when all services are deployed
-		// (the resolver naturally qualifies len > 1 anyway).
-		totalServices := len(state.Services)
-		filtered := filterDeployedServices(state)
+		// ResolveAfterDeploy always emits service-qualified
+		// `azd ai agent show <name>` / `invoke <name> ...` commands
+		// post-B9 (issue #7975), so it's safe to pass a filtered
+		// (deployed-only) State directly — the suggestions remain
+		// copy-paste correct even when azure.yaml has additional
+		// undeployed services that are absent from the filtered set.
 		return nextstep.ResolveAfterDeploy(
-			filtered,
+			filterDeployedServices(state),
 			doctorCachedPayload(ctx, azdClient),
 			doctorReadmeExists(ctx, azdClient),
-			nextstep.AfterDeployOpts{ForceQualified: totalServices > 1},
 		)
 	}
 

cli/azd/extensions/azure.ai.agents/internal/cmd/doctor_format_test.go

@@ -326,3 +326,32 @@ func TestFilterDeployedServices(t *testing.T) {
 		assert.Len(t, state.Services, 2, "clone must not modify input")
 	})
 }
+
+// TestFilterDeployedServices_ChainedIntoResolveAfterDeploy locks in the
+// end-to-end contract for doctor's post-deploy guidance block: when the
+// project has multiple agent services but only one is deployed, the
+// filtered state flowed through ResolveAfterDeploy must still emit a
+// service-qualified command — i.e. the user sees `azd ai agent show
+// <name>` rather than `azd ai agent show` (no arg). Pre-B9 this
+// invariant was enforced via AfterDeployOpts.ForceQualified at the
+// caller; post-B9 the resolver always qualifies. This test would have
+// caught a future regression that reintroduces an unqualified branch
+// keyed on len(state.Services) == 1.
+func TestFilterDeployedServices_ChainedIntoResolveAfterDeploy(t *testing.T) {
+	t.Parallel()
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{Name: "alpha", IsDeployed: true, Protocol: nextstep.ProtocolResponses},
+			{Name: "beta", IsDeployed: false, Protocol: nextstep.ProtocolResponses},
+		},
+	}
+
+	out := nextstep.ResolveAfterDeploy(filterDeployedServices(state), nil, nil)
+
+	require.Len(t, out, 2, "filtered state has one deployed service → show + invoke")
+	assert.Equal(t, "azd ai agent show alpha", out[0].Command,
+		"command must be service-qualified even when filtered list has len==1")
+	assert.Equal(t, `azd ai agent invoke alpha "Hello!"`, out[1].Command,
+		"invoke command must also be service-qualified")
+}

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver.go

@@ -415,37 +415,59 @@ func ResolveAfterShow(state *State, serviceName string) []Suggestion {
 }
 
 // AfterDeployOpts configures ResolveAfterDeploy. Optional — the
-// zero-value matches the historical post-deploy call site behavior.
+// zero-value matches the post-deploy call site behavior.
 type AfterDeployOpts struct {
-	// ForceQualified, when true, makes ResolveAfterDeploy emit
-	// service-qualified `azd ai agent show <name>` / `invoke <name> ...`
-	// commands even when len(state.Services) == 1.
+	// ForceQualified is retained for backward compatibility but is
+	// effectively a no-op as of issue #7975 fix B9: ResolveAfterDeploy
+	// now always emits service-qualified
+	// `azd ai agent show <name>` / `invoke <name> ...` commands
+	// regardless of how many services are in state.
 	//
-	// Use this when the input State has been filtered down from a
-	// larger multi-agent project (e.g., doctor showing only deployed
-	// services). The default `len(state.Services) == 1` heuristic
-	// would otherwise emit no-arg commands that ambiguity-prompt or
-	// error at runtime because resolveAgentService sees ALL azure.yaml
-	// services, not just the filtered subset.
+	// Pre-B9 callers passed ForceQualified=true to override a
+	// "single-agent → unqualified command" heuristic that no longer
+	// exists. The flag is preserved so existing callers compile and
+	// run identically; new callers may simply omit it.
 	ForceQualified bool
 }
 
 // ResolveAfterDeploy produces the Next: block embedded in the post-deploy
-// artifact note. The block is rendered per agent service: one
-// `azd ai agent show <name>` plus one `azd ai agent invoke '<payload>'`
-// line, where the payload is taken from the cached OpenAPI spec when the
-// `cachedPayload` lookup yields a non-empty string for the agent.
+// artifact note. Issue #7975 fix B9 spec (lines 228-242):
+//
+//   - Single-agent project: emit one `azd ai agent show <name>` line
+//     followed by one `azd ai agent invoke <name> '<payload>'` line.
+//     Descriptions are "verify it's running" / "test the deployment".
+//   - Multi-agent project: emit all `show <name>` lines first (one
+//     per service, in declaration order), then all `invoke <name>`
+//     lines. Descriptions include the agent name —
+//     "verify <name> is running" / "test <name>" — so the user can
+//     identify which row maps to which agent at a glance.
+//
+// In both cases commands are always service-qualified (B9). Pre-B9
+// behavior would strip the name when len(state.Services) == 1, which
+// produced ambiguous `azd ai agent show` lines in artifact notes that
+// users couldn't run directly when copy-pasted into a multi-agent
+// project later. The qualified form is unambiguous and copy-paste
+// safe in either project shape.
 //
 // cachedPayload is injected by the caller (typically a closure over
 // ReadCachedOpenAPISpec + ExtractInvokeExample) so the resolver itself
-// stays pure and unit-testable.
+// stays pure and unit-testable. The cached sample is used verbatim
+// (POSIX-escaped) when present; otherwise the protocol-appropriate
+// fallback from defaultInvokePayload is used.
 //
-// readmeExists, also injected, controls whether the "See <relPath>/README.md
-// for a sample payload" line is appended. The resolver does not touch the
-// filesystem directly.
+// readmeExists, also injected, controls whether the
+// "See <relPath>/README.md for a sample payload" line is appended
+// for a given service. The hint is emitted only when:
+// (1) no cached payload was available for that service,
+// (2) the service has a RelativePath, and
+// (3) readmeExists reports a README on disk at that path.
+// In the multi-agent layout each service's README hint is rendered
+// immediately after that service's invoke line so users can scan
+// rows top-to-bottom and find each agent's hint in context.
 //
-// opts is variadic for backward compatibility. Only the first element is
-// consulted; additional elements are ignored.
+// opts is variadic for backward compatibility but is no longer
+// consulted — every field of AfterDeployOpts is now a no-op post-B9.
+// See AfterDeployOpts.ForceQualified for the historical context.
 func ResolveAfterDeploy(
 	state *State,
 	cachedPayload func(serviceName string) string,
@@ -456,27 +478,28 @@ func ResolveAfterDeploy(
 		return nil
 	}
 
-	var forceQualified bool
-	if len(opts) > 0 {
-		forceQualified = opts[0].ForceQualified
-	}
-
+	singleAgent := len(state.Services) == 1
 	out := make([]Suggestion, 0, len(state.Services)*3)
-	singleAgent := !forceQualified && len(state.Services) == 1
 	priority := 10
 
+	// Pass 1: all `azd ai agent show <name>` lines, in service order.
 	for _, svc := range state.Services {
-		showCmd := "azd ai agent show"
-		if !singleAgent {
-			showCmd = fmt.Sprintf("azd ai agent show %s", svc.Name)
+		desc := fmt.Sprintf("verify %s is running", svc.Name)
+		if singleAgent {
+			desc = "verify it's running"
 		}
 		out = append(out, Suggestion{
-			Command:     showCmd,
-			Description: "verify the deployed agent is running",
+			Command:     fmt.Sprintf("azd ai agent show %s", svc.Name),
+			Description: desc,
 			Priority:    priority,
 		})
 		priority++
+	}
 
+	// Pass 2: all `azd ai agent invoke <name> <payload>` lines, each
+	// followed by its README hint when applicable. Grouping invokes
+	// after shows matches the spec example output (lines 238-241).
+	for _, svc := range state.Services {
 		payload := ""
 		if cachedPayload != nil {
 			payload = cachedPayload(svc.Name)
@@ -486,13 +509,13 @@ func ResolveAfterDeploy(
 			invokeArg = shellEscapeSingleQuoted(payload)
 		}
 
-		invokeCmd := fmt.Sprintf("azd ai agent invoke %s", invokeArg)
-		if !singleAgent {
-			invokeCmd = fmt.Sprintf("azd ai agent invoke %s %s", svc.Name, invokeArg)
+		desc := fmt.Sprintf("test %s", svc.Name)
+		if singleAgent {
+			desc = "test the deployment"
 		}
 		out = append(out, Suggestion{
-			Command:     invokeCmd,
-			Description: "send a sample request to the deployed agent",
+			Command:     fmt.Sprintf("azd ai agent invoke %s %s", svc.Name, invokeArg),
+			Description: desc,
 			Priority:    priority,
 		})
 		priority++

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver_test.go

@@ -716,28 +716,35 @@ func TestResolveAfterShow_NilState(t *testing.T) {
 func TestResolveAfterDeploy(t *testing.T) {
 	t.Parallel()
 
-	t.Run("single agent, cached payload available → 2 lines, no README hint", func(t *testing.T) {
+	t.Run("single agent, cached payload available → 2 qualified lines, no README hint", func(t *testing.T) {
 		t.Parallel()
 		state := &State{Services: []ServiceState{{Name: "echo", RelativePath: "./src/echo"}}}
 		cached := func(_ string) string { return `{"q":"x"}` }
 		out := ResolveAfterDeploy(state, cached, nil)
 		require.Len(t, out, 2)
-		assert.Equal(t, "azd ai agent show", out[0].Command)
-		assert.Equal(t, `azd ai agent invoke '{"q":"x"}'`, out[1].Command)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+		assert.Equal(t, "verify it's running", out[0].Description)
+		assert.Equal(t, `azd ai agent invoke echo '{"q":"x"}'`, out[1].Command)
+		assert.Equal(t, "test the deployment", out[1].Description)
 	})
 
-	t.Run("single agent, no cached payload, README on disk → 3 lines with README pointer", func(t *testing.T) {
+	t.Run("single agent, no cached payload, README on disk → 3 lines with qualified commands", func(t *testing.T) {
 		t.Parallel()
 		state := &State{Services: []ServiceState{{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolResponses}}}
 		readme := func(p string) bool { return p == "./src/echo" }
 		out := ResolveAfterDeploy(state, nil, readme)
 		require.Len(t, out, 3)
-		assert.Equal(t, "azd ai agent show", out[0].Command)
-		assert.Equal(t, `azd ai agent invoke "Hello!"`, out[1].Command)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+		assert.Equal(t, "verify it's running", out[0].Description)
+		assert.Equal(t, `azd ai agent invoke echo "Hello!"`, out[1].Command)
+		assert.Equal(t, "test the deployment", out[1].Description)
 		assert.Contains(t, out[2].Command, "src/echo/README.md")
 	})
 
-	t.Run("multi-agent → one show/invoke pair per agent, named", func(t *testing.T) {
+	t.Run("multi-agent → all shows first, then all invokes, with per-agent descriptions", func(t *testing.T) {
+		// Spec source: issue #7975 lines 238-241 — multi-agent layout
+		// groups shows before invokes (not interleaved) and bakes the
+		// agent name into the description so users can scan vertically.
 		t.Parallel()
 		state := &State{Services: []ServiceState{
 			{Name: "alpha", Protocol: ProtocolInvocations},
@@ -746,9 +753,30 @@ func TestResolveAfterDeploy(t *testing.T) {
 		out := ResolveAfterDeploy(state, nil, nil)
 		require.Len(t, out, 4)
 		assert.Equal(t, "azd ai agent show alpha", out[0].Command)
-		assert.Equal(t, `azd ai agent invoke alpha '{"message": "Hello!"}'`, out[1].Command)
-		assert.Equal(t, "azd ai agent show beta", out[2].Command)
+		assert.Equal(t, "verify alpha is running", out[0].Description)
+		assert.Equal(t, "azd ai agent show beta", out[1].Command)
+		assert.Equal(t, "verify beta is running", out[1].Description)
+		assert.Equal(t, `azd ai agent invoke alpha '{"message": "Hello!"}'`, out[2].Command)
+		assert.Equal(t, "test alpha", out[2].Description)
 		assert.Equal(t, `azd ai agent invoke beta "Hello!"`, out[3].Command)
+		assert.Equal(t, "test beta", out[3].Description)
+	})
+
+	t.Run("multi-agent README hint placement → after the corresponding invoke line", func(t *testing.T) {
+		t.Parallel()
+		state := &State{Services: []ServiceState{
+			{Name: "alpha", RelativePath: "./src/alpha", Protocol: ProtocolResponses},
+			{Name: "beta", Protocol: ProtocolResponses},
+		}}
+		readme := func(p string) bool { return p == "./src/alpha" }
+		out := ResolveAfterDeploy(state, nil, readme)
+		// 2 shows + 2 invokes + 1 README hint for alpha = 5 entries.
+		require.Len(t, out, 5)
+		assert.Equal(t, "azd ai agent show alpha", out[0].Command)
+		assert.Equal(t, "azd ai agent show beta", out[1].Command)
+		assert.Equal(t, `azd ai agent invoke alpha "Hello!"`, out[2].Command)
+		assert.Contains(t, out[3].Command, "src/alpha/README.md")
+		assert.Equal(t, `azd ai agent invoke beta "Hello!"`, out[4].Command)
 	})
 
 	t.Run("README hint skipped when cached payload is present", func(t *testing.T) {
@@ -770,35 +798,41 @@ func TestResolveAfterDeploy(t *testing.T) {
 		assert.Nil(t, ResolveAfterDeploy(nil, nil, nil))
 	})
 
-	t.Run("cached payload containing apostrophe → POSIX-escaped", func(t *testing.T) {
+	t.Run("cached payload containing apostrophe → POSIX-escaped on qualified invoke", func(t *testing.T) {
 		t.Parallel()
 		state := &State{Services: []ServiceState{{Name: "echo", RelativePath: "./src/echo"}}}
 		cached := func(_ string) string { return `{"q":"don't"}` }
 		out := ResolveAfterDeploy(state, cached, nil)
 		require.Len(t, out, 2)
-		assert.Equal(t, `azd ai agent invoke '{"q":"don'\''t"}'`, out[1].Command)
+		assert.Equal(t, `azd ai agent invoke echo '{"q":"don'\''t"}'`, out[1].Command)
 	})
 
-	t.Run("ForceQualified=true on len==1 → service-qualified commands", func(t *testing.T) {
+	t.Run("ForceQualified=true on len==1 → no-op, output identical to default", func(t *testing.T) {
+		// Backward-compat assertion: B9 makes all output qualified by
+		// default; ForceQualified is preserved as a no-op for callers
+		// (e.g., doctor) that still pass it. Result must match the
+		// "no opts" call exactly.
 		t.Parallel()
 		state := &State{Services: []ServiceState{
 			{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolInvocations},
 		}}
 		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: true})
+		baseline := ResolveAfterDeploy(state, nil, nil)
+		require.Equal(t, baseline, out)
 		require.Len(t, out, 2)
 		assert.Equal(t, "azd ai agent show echo", out[0].Command)
 		assert.Equal(t, `azd ai agent invoke echo '{"message": "Hello!"}'`, out[1].Command)
 	})
 
-	t.Run("ForceQualified=false on len==1 → unqualified (matches default)", func(t *testing.T) {
+	t.Run("ForceQualified=false on len==1 → no-op, also qualified", func(t *testing.T) {
 		t.Parallel()
 		state := &State{Services: []ServiceState{
 			{Name: "echo", RelativePath: "./src/echo", Protocol: ProtocolInvocations},
 		}}
 		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: false})
 		require.Len(t, out, 2)
-		assert.Equal(t, "azd ai agent show", out[0].Command)
-		assert.Equal(t, `azd ai agent invoke '{"message": "Hello!"}'`, out[1].Command)
+		assert.Equal(t, "azd ai agent show echo", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke echo '{"message": "Hello!"}'`, out[1].Command)
 	})
 
 	t.Run("ForceQualified=true with cached payload → qualified invoke uses payload", func(t *testing.T) {
@@ -811,7 +845,7 @@ func TestResolveAfterDeploy(t *testing.T) {
 		assert.Equal(t, `azd ai agent invoke echo '{"q":"x"}'`, out[1].Command)
 	})
 
-	t.Run("ForceQualified=true on multi-agent → qualified (already-qualified case unaffected)", func(t *testing.T) {
+	t.Run("ForceQualified=true on multi-agent → identical to default multi-agent layout", func(t *testing.T) {
 		t.Parallel()
 		state := &State{Services: []ServiceState{
 			{Name: "alpha", Protocol: ProtocolInvocations},
@@ -820,8 +854,8 @@ func TestResolveAfterDeploy(t *testing.T) {
 		out := ResolveAfterDeploy(state, nil, nil, AfterDeployOpts{ForceQualified: true})
 		require.Len(t, out, 4)
 		assert.Equal(t, "azd ai agent show alpha", out[0].Command)
-		assert.Equal(t, `azd ai agent invoke alpha '{"message": "Hello!"}'`, out[1].Command)
-		assert.Equal(t, "azd ai agent show beta", out[2].Command)
+		assert.Equal(t, "azd ai agent show beta", out[1].Command)
+		assert.Equal(t, `azd ai agent invoke alpha '{"message": "Hello!"}'`, out[2].Command)
 		assert.Equal(t, `azd ai agent invoke beta "Hello!"`, out[3].Command)
 	})