feat(ai-agents): add --inspector-port flag to azd ai agent run

[Glenn Harper (glharper)]

Summary

• add an --inspector-port flag to azd ai agent run and forward it to ai inspector launch
• forward the flag only when set, so the azure.ai.inspector extension stays the source of truth for the default UI port (8087) and existing behavior is unchanged
• reject out-of-range values instead of silently ignoring them
• document the flag in the extension README

Unblocks running two agents side by side: each agent already gets its own --port, but both Inspectors previously tried to bind 8087.

azd ai agent run --port 9091 --inspector-port 9002
# forwards: ai inspector launch --port 9091 --inspector-port 9002 --silent

The optional auto-increment-on-conflict idea from the issue is not included; that behavior belongs to the inspector extension, which owns the bind.

Testing

• go test ./internal/cmd -count=1
• go build ./...
• golangci-lint run ./internal/cmd/...
• cspell lint internal/cmd/run.go internal/cmd/run_test.go

New coverage: --inspector-port is omitted when unset and forwarded when set, the flag is registered with the documented default, and out-of-range values are rejected.

No TestFigSpec snapshot update: that snapshot installs published extension artifacts from registry.json, so it picks this flag up on the next azure.ai.agents release.

Fixes #9222

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Thank you for logging this issue; our team is reviewing it. If you need urgent prioritization, tag Rick Winter (@RickWinter) and Kristen Womack (@kristenwomack) to let us know.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
21 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Adds configurable Agent Inspector UI ports to support concurrent local agents.

Changes:

• Adds and validates --inspector-port.
• Forwards explicitly configured ports to Agent Inspector.
• Documents and tests the new flag.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
README.md	Documents custom Inspector ports.
internal/cmd/run.go	Registers, validates, and forwards the flag.
internal/cmd/run_test.go	Tests registration, validation, and forwarding.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Jon Gallant (jongio)]

Two optional hardening ideas inline, both about --inspector-port values that pass validation but still don't reach the inspector. Neither blocks.

LOW

• --inspector-port is accepted and then dropped when the local client is suppressed, and when the project is an activity agent
• --inspector-port equal to --port clears validation and fails later at bind time

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/run.go:571

• [azd-code-reviewer] This collision check runs before the activity profile is resolved, so an activity agent invoked with equal values (for example, --port 9002 --inspector-port 9002) exits here instead of reaching the documented warning-and-ignore path. The Playground never binds the inspector port; move this check into the non-activity branch after profile resolution, or make validation profile-aware.

	if flags.inspectorPort == flags.port {

[Jon Gallant (jongio)]

Incremental pass on 0103ac7. Both of my earlier points are handled. Three low-severity follow-ups inline, none blocking.

LOW

• the activity-agent warning prints after the agent process has already started, so it lands in the middle of the server's own output, and it's the one new behavior here without a test
• the --port collision check only fires when --inspector-port is set explicitly, so --port 8087 on its own still hits the same bind conflict silently
• README documents the flag but not the two new ways it can now fail

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

cli/azd/extensions/azure.ai.agents/internal/cmd/run.go:569

• [azd-code-reviewer] This collision check runs before the service is resolved, so it also rejects activity-protocol agents even though they launch the Playground and never bind an Inspector port. That contradicts the later activity path, which is designed to warn and continue when --inspector-port is irrelevant. Move this check until after resolveActivityRunProfile and apply it only to non-activity agents.

	if flags.inspectorPort == flags.port {

[Jon Gallant (jongio)]

Incremental pass on 52b87ab. One low-severity follow-up inline, not blocking.

LOW

• the new --port 8087 warning fires before azd knows whether the inspector extension is installed, so a machine without the extension gets a bind-conflict warning and then a not-installed warning

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Jon Gallant (jongio)]

One test gap remains:

• run_test.go:481: the non-default-port case short-circuits before testing the port comparison.

_{🤖 agent jongio}

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Glenn Harper (glharper)]

Rechecked the latest review state locally. GitHub currently reports 0 unresolved threads.

The one item in jongio's latest review summary (run_test.go: the non-default-port case needed to set inspectorInstalled: true) is already addressed in 4cf88be, and the underlying thread is resolved. The same commit also moved equal-port validation after activity-profile resolution, skips it for Activity agents, and keeps that validation before session-cleanup registration.

Focused regression tests pass, and a fresh local code review found no remaining issues. No additional code change or push was needed.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

cli/azd/extensions/azure.ai.agents/README.md:26

• [azd-code-reviewer] This now identifies --no-inspector as deprecated, but lines 10–13 still recommend it as the primary way to suppress the client. Update that earlier instruction and example to use the canonical --no-client flag so the README does not direct users to a deprecated option.

- with `--no-client` (or the deprecated `--no-inspector`), since no local client

cli/azd/extensions/azure.ai.agents/internal/cmd/run_test.go:307

• [azd-code-reviewer] These cases manually pass set: true, so they do not exercise the new Cobra wiring that populates inspectorPortSet. If the Flags().Changed("inspector-port") assignment regresses, this suite still passes while an explicit --inspector-port 0 is silently treated as unset again. Add a command-level assertion for that exact invocation.

		{name: "unset is allowed", port: 0},
		{name: "explicit zero is rejected", port: 0, set: true, wantErr: true},