chore: add version override for invoke

[JerryYang (JerryYangKai)]

Summary
Add azd ai agent invoke --version-override to test a hosted agent version without changing the endpoint’s traffic split.

Support explicit versions and latest through x-agent-version-override for Responses and Invocations.
Use isolated sessions and conversations without changing ordinary cached state.
Fail when version resolution is missing, mismatched, or falls back, including in raw output mode.
Preserve existing --version behavior.
Add regression tests, usage documentation, and CLI scenarios.
Changes are limited to the Agents extension; no core changes.

Validation
Build, unit tests, lint, and spelling checks passed.
Scenario YAML validated statically.
Live Foundry validation remains pending.

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 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]

🟡 Changes recommended

Non-2xx verification can fail open, and multi-agent Invocations overrides can prompt for the target twice.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds strict hosted-agent version overrides without changing endpoint traffic splits.

Changes:

• Adds --version-override, response verification, and state isolation.
• Documents override behavior and validation.
• Adds unit, integration, and interactive scenarios.

File summaries

File	Description
tests/.../tier2/2.14-invoke-version-override.yaml	Adds cloud E2E coverage.
tests/.../tier0/0.21-invoke-version-override-validation.yaml	Adds offline validation coverage.
tests/.../README.md	Registers new scenarios.
README.md	Documents version overrides.
internal/exterrors/codes.go	Adds verification error code.
internal/cmd/invoke.go	Integrates the new flag and isolation behavior.
internal/cmd/invoke_version_override.go	Implements validation and header verification.
internal/cmd/invoke_version_override_test.go	Adds focused unit tests.
internal/cmd/invoke_version_override_integration_test.go	Adds protocol-level integration tests.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Wei Meng (m5i-work)]

Thanks for adding the version-override flow. I noticed the traffic-split distinction appears in several user-facing places; the inline comments suggest emphasizing the behavior that is unique to this option.

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

[Copilot]

🔵 Needs a closer look

Failed verification can hide the ID of an already-started asynchronous Invocation, preventing recovery or cancellation.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

cli/azd/extensions/azure.ai.agents/internal/cmd/invoke.go:1985

• A successful 202 Accepted may already have started an Invocation, but this returns before invocationIDFromResponse runs. In friendly output the ID is then neither shown nor persisted, so the user cannot inspect or cancel the work despite the warning that execution may have occurred. For 202 responses, extract and surface the explicit ID (or a recovery command) before returning the verification error, while keeping it out of saved state.

• Files reviewed: 10/10 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The implementation is thorough, but its critical Foundry header and fallback behavior still requires the pending live validation.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[azure-sdk-automation]

azure.ai.agents PR build

Note

This is an unsigned development build. Install it only if you trust this PR.

Install the extension:

azd ext install "https://azuresdkartifacts.z5.web.core.windows.net/azd/extensions/pr/10079/azure-ai-agents.zip"

• Version: 1.0.0-beta.16.pr.10079.6848255
• Merge commit: b300e39