feat(azure.ai.agents): add invoke-local secondary to init "everything ready" Next: (P5.1 C7)

Issue Azure#7975 lines 96-103 specify that the init "everything ready"
output should surface two commands, not one:

  Next:  azd ai agent run                      -- start the agent locally
         azd ai agent invoke --local "Hello!"  -- test it in another terminal

Pre-C7 the resolver emitted only `azd ai agent run` (plus the trailing
`azd deploy` reminder). Users hit the "now what?" wall after the agent
bound its port: they had to remember `azd ai agent invoke --local …`
and figure out the right payload for their protocol.

Source of truth: issue Azure#7975 lines 96-103. Spec example uses the
unqualified `azd ai agent invoke --local "Hello!"` form regardless of
how many services the project declares.

# Change

`ResolveAfterInit`'s default branch (everything-ready case) now appends
a second `Suggestion`:

  Command:     azd ai agent invoke --local <payload>
  Description: test it in another terminal

The trailing `azd deploy` reminder stays in place (Priority 90,
Trailing:true), so the rendered block is three lines on a fresh,
fully-provisioned project.

Payload selection:

- `len(state.Services) == 1` → `defaultInvokePayload(&state.Services[0])`
  which already maps `ProtocolInvocations` → `'{"message": "Hello!"}'`
  (JSON envelope) and everything else → `"Hello!"`. So a single-agent
  invocations-protocol project gets the JSON shape, single-agent
  responses-protocol gets the literal, matching what `ResolveAfterRun`
  has done since commit 2.3.
- `len(state.Services) != 1` (zero or multi-agent) → literal `"Hello!"`.
  Multi-agent: the unqualified `azd ai agent invoke --local` doesn't
  know which agent the user will pick at runtime, so picking one
  service's protocol arbitrarily would be wrong half the time. The
  responses-style literal is what the spec example uses.

The suppression branches are untouched:

- `hasPlaceholders` (case 2) — neither `run` nor `invoke --local`
  emitted. Running locally with literal `{{NAME}}` values produces a
  broken agent; the spec gates `run` on placeholder-clear state, and
  the invoke secondary is paired with `run` so it inherits the gate.
- `len(state.MissingManualVars) > 0` (case 1 of the default-cases
  block) — the manual-vars renderer ships its own `run` follow-up
  ("start the agent locally once the values above are set"). The
  invoke-local secondary is NOT added there: the manual-vars example
  in the spec (lines 119-127) deliberately stops at `run` to keep the
  "set values → run" call-to-action focused.

# Renderer

Both init.go (`init.go:1643`) and init_from_code.go (`:148`) call
`nextstep.PrintAllNext`, which has NO line cap (uncapped renderer
per commit 4.7's G1 fix). The new third suggestion fits cleanly;
no truncation risk.

`PrintNext`'s `maxRendered = 2` cap is irrelevant here — it's used
by mid-flow resolvers (invoke, show) where ≤2 suggestions naturally
occur.

# Tests

resolver_test.go adds `TestResolveAfterInit_EverythingReady_EmitsInvokeLocalSecondary`
with five subcases:

1. Zero services → unqualified invoke with responses payload. Pins
   the spec-mandated unqualified form. Asserts Priority ordering
   (run < invoke) so the renderer always emits them in the
   user-expected order.
2. Single-agent responses protocol → `azd ai agent invoke --local "Hello!"`.
3. Single-agent invocations protocol → `azd ai agent invoke --local '{"message": "Hello!"}'`.
   Locks the protocol-aware shape.
4. Multi-agent (mixed protocols) → invoke stays unqualified with
   responses payload. Anti-regression: protects against accidentally
   picking `state.Services[0].Protocol` for a multi-agent project.
5. Placeholders present → neither `run` nor `invoke --local` emitted.
   Anti-regression: pairs with the existing
   `TestResolveAfterInit_UnresolvedPlaceholders` table.

Existing `TestResolveAfterInit` table cases (happy path,
"existing project chosen, all vars set") still pass without
modification — they assert `out[0].Command` (still
`azd ai agent run`) and `out[len(out)-1].Command` (still
`azd deploy`); the new invoke-local slot inserts in the middle
and they don't pin block length.

# Affected callers

`init.go` and `init_from_code.go` print the new line automatically
via `PrintAllNext`. `doctor.go:243`'s no-deploy branch flows through
`ResolveAfterInit` too — pre-deploy doctor guidance gets the same
upgrade.

# Verified

- gofmt -s -w . (clean)
- go vet ./... (clean)
- go test ./... -count=1 (all packages green; nextstep 6.5s,
  cmd 17.3s, doctor 4.9s)
- golangci-lint run ./internal/cmd/... (0 issues)
- cspell lint internal/cmd/nextstep/**/*.go --config ../../.vscode/cspell.yaml (0 issues)

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

Author: Antriksh Jain

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

@@ -68,9 +68,20 @@ const (
 //     manual-vars example. The run follow-up is suppressed when
 //     UnresolvedPlaceholders are also present, since literal
 //     `{{NAME}}` values would still break the local agent.
-//   - Otherwise          → `azd ai agent run`
-//     Skipped when only UnresolvedPlaceholders are present, because
-//     running locally with literal `{{NAME}}` values is broken too.
+//   - Otherwise          → `azd ai agent run` + `azd ai agent invoke
+//     --local <payload>` secondary
+//     Spec: issue #7975 lines 96-103. The invoke-local secondary
+//     lets the user test the agent in another terminal once it's
+//     running. Payload is protocol-aware when the project has
+//     exactly one service in state (the unqualified `invoke --local`
+//     resolves to that service). For multi-agent projects the
+//     payload defaults to the responses-style `"Hello!"` and the
+//     command is left unqualified — the user picks the target at
+//     runtime via the interactive prompt or `--service` flag, the
+//     same shape the spec example uses.
+//     Both lines are skipped when only UnresolvedPlaceholders are
+//     present, because running locally with literal `{{NAME}}`
+//     values is broken.
 //
 // All paths append the static "When ready to deploy to Azure…" tail.
 func ResolveAfterInit(state *State) []Suggestion {
@@ -149,6 +160,27 @@ func ResolveAfterInit(state *State) []Suggestion {
 			Description: "start the agent locally",
 			Priority:    priority,
 		})
+		priority++
+		// Invoke-local secondary (issue #7975 lines 99-100). The
+		// spec's "everything ready" example shows the user a second
+		// command to try once the agent is running:
+		//   azd ai agent invoke --local "Hello!"  -- test it in another terminal
+		// Single-agent projects get a protocol-aware payload (matches
+		// the protocol the agent's `/invocations` or `/responses`
+		// endpoint expects). Multi-agent projects fall back to the
+		// responses-style "Hello!" literal because the unqualified
+		// command shape doesn't know which service the user will
+		// pick at runtime — mirroring the spec example which also
+		// uses the unqualified form.
+		invokePayload := invokeResponsesPayload
+		if len(state.Services) == 1 {
+			invokePayload = defaultInvokePayload(&state.Services[0])
+		}
+		out = append(out, Suggestion{
+			Command:     fmt.Sprintf("azd ai agent invoke --local %s", invokePayload),
+			Description: "test it in another terminal",
+			Priority:    priority,
+		})
 	}
 
 	out = append(out, Suggestion{

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

@@ -213,6 +213,94 @@ func TestResolveAfterInit_ManualVarsSingleEmitsEnrichedShape(t *testing.T) {
 	assert.True(t, out[2].Trailing)
 }
 
+// TestResolveAfterInit_EverythingReady_EmitsInvokeLocalSecondary locks
+// the spec-mandated two-line "everything ready" shape from issue #7975
+// lines 96-103: after `azd ai agent run`, append
+// `azd ai agent invoke --local <payload>` so the user knows what to
+// try in another terminal. Also verifies protocol-aware payload selection
+// (single-service state) and the priority ordering (run before invoke).
+func TestResolveAfterInit_EverythingReady_EmitsInvokeLocalSecondary(t *testing.T) {
+	t.Parallel()
+
+	t.Run("zero services → unqualified invoke with responses payload", func(t *testing.T) {
+		t.Parallel()
+		state := &State{HasProjectEndpoint: true}
+		out := ResolveAfterInit(state)
+		// run + invoke --local + trailing.
+		require.Len(t, out, 3)
+		assert.Equal(t, "azd ai agent run", out[0].Command)
+		assert.Equal(t, "start the agent locally", out[0].Description)
+		assert.Equal(t, `azd ai agent invoke --local "Hello!"`, out[1].Command)
+		assert.Equal(t, "test it in another terminal", out[1].Description)
+		assert.Less(t, out[0].Priority, out[1].Priority,
+			"run must precede invoke --local; the renderer sorts by Priority")
+		assert.Equal(t, "azd deploy", out[2].Command)
+		assert.True(t, out[2].Trailing)
+	})
+
+	t.Run("single-agent responses protocol → invoke uses \"Hello!\"", func(t *testing.T) {
+		t.Parallel()
+		state := &State{
+			HasProjectEndpoint: true,
+			Services:           []ServiceState{{Name: "echo", Protocol: ProtocolResponses}},
+		}
+		out := ResolveAfterInit(state)
+		require.Len(t, out, 3)
+		assert.Equal(t, "azd ai agent run", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke --local "Hello!"`, out[1].Command)
+	})
+
+	t.Run("single-agent invocations protocol → invoke uses JSON envelope", func(t *testing.T) {
+		t.Parallel()
+		state := &State{
+			HasProjectEndpoint: true,
+			Services:           []ServiceState{{Name: "echo", Protocol: ProtocolInvocations}},
+		}
+		out := ResolveAfterInit(state)
+		require.Len(t, out, 3)
+		assert.Equal(t, "azd ai agent run", out[0].Command)
+		assert.Equal(t, `azd ai agent invoke --local '{"message": "Hello!"}'`, out[1].Command)
+	})
+
+	t.Run("multi-agent → invoke stays unqualified, defaults to responses payload", func(t *testing.T) {
+		t.Parallel()
+		state := &State{
+			HasProjectEndpoint: true,
+			Services: []ServiceState{
+				{Name: "alpha", Protocol: ProtocolInvocations},
+				{Name: "beta", Protocol: ProtocolResponses},
+			},
+		}
+		out := ResolveAfterInit(state)
+		require.Len(t, out, 3)
+		assert.Equal(t, "azd ai agent run", out[0].Command)
+		// Multi-agent: the unqualified `invoke --local` doesn't know
+		// which service the user will pick at runtime, so use the
+		// safest generic payload (responses-style "Hello!") instead
+		// of picking one service's protocol arbitrarily.
+		assert.Equal(t, `azd ai agent invoke --local "Hello!"`, out[1].Command)
+	})
+
+	t.Run("placeholders present → invoke-local secondary suppressed (with run)", func(t *testing.T) {
+		// Placeholders block local run entirely — the spec's default
+		// branch is gated on !hasPlaceholders, so neither `run` nor
+		// the invoke-local follow-up should appear when literal
+		// {{NAME}} values would land in the running container.
+		t.Parallel()
+		state := &State{
+			HasProjectEndpoint:     true,
+			UnresolvedPlaceholders: []string{"FOO"},
+		}
+		out := ResolveAfterInit(state)
+		for _, s := range out {
+			assert.NotContains(t, s.Command, "azd ai agent invoke --local",
+				"invoke --local must not be emitted while placeholders are unresolved")
+			assert.NotEqual(t, "azd ai agent run", s.Command,
+				"azd ai agent run must not be emitted while placeholders are unresolved")
+		}
+	})
+}
+
 // TestResolveAfterInit_ToolboxReproRendersAllCategories locks the full
 // regression for the toolbox-sample bug end-to-end: the state contains
 // BOTH an unresolved manifest placeholder AND a missing manual env var,