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

[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 @RickWinter and @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.

[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 {

[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 {

[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.