[agentserver-invocations] Serve AsyncAPI docs at /invocations/docs/asyncapi.{json,yaml}

[ZhaoChaoqun]

Summary

Adds two AsyncAPI discovery endpoints to InvocationAgentServerHost, mirroring the existing openapi.json endpoint:

• GET /invocations/docs/asyncapi.json → application/json
• GET /invocations/docs/asyncapi.yaml → application/yaml

Optional constructor args asyncapi_spec_json (dict) and/or asyncapi_spec_yaml (raw YAML str) enable each endpoint independently. Path extension is authoritative for the returned content type — no Accept negotiation, no format conversion between the two representations. Either representation returns 404 if not registered; users may register only one, only the other, or both.

Rationale: AsyncAPI is the companion to OpenAPI for streaming/bidirectional surfaces (e.g. the invocations_ws WebSocket protocol) that OpenAPI cannot express. Serving both formats natively (rather than converting server-side) matches typical AsyncAPI tooling expectations and keeps the SDK dependency-free of a YAML library.

Constructor validates arg types up front (TypeError) to prevent a stringified dict leaking to clients as YAML.

Startup log extended to record which specs are configured.

Rollout & compatibility

Backward compatible: both constructor args default to None; existing hosts are unaffected, and each endpoint returns 404 until registered. Python SDK is independently mergeable and safe to ship ahead of the others.

Part of a 5-repo change adding AsyncAPI discovery to Agent Server:

• Prose spec: coreai-microsoft/foundrysdk_specs#209
• TypeSpec: Add getAgentInvocationAsyncApiSpec{Json,Yaml} operations azure-rest-api-specs#44416
• This PR: Python SDK
• .NET SDK: [Azure.AI.AgentServer.Invocations] Serve AsyncAPI docs at /invocations/docs/asyncapi.{json,yaml} azure-sdk-for-net#60663
• Backend service (Vienna): Microsoft internal PR #2182112 (msdata/Vienna) — internal link, no external dependency; provided for context only

Test plan

• pytest tests/test_server_routes.py -v — 14/14 pass (5 new asyncapi tests + 2 type-validation tests)
• Full package suite — 195 passed, 0 failed
• Two rounds of internal code review (architecture + code-quality personas), all findings addressed

Files changed

• azure/ai/agentserver/invocations/_invocation.py — 2 constructor args, 2 routes, 2 handlers, 2 getters, type validation, startup log
• tests/test_server_routes.py — 7 new tests
• README.md — endpoint table + "Serving an AsyncAPI spec" section
• CHANGELOG.md — 1.0.0b7 (Unreleased) entry
• api.md — API surface snapshot synchronized
• _version.py — bumped 1.0.0b6 → 1.0.0b7

Fixes: AB#5407709

[github-actions]

Thank you for your contribution @ZhaoChaoqun! We will review the pull request and get back to you soon.

[Copilot]

Pull request overview

This PR adds two AsyncAPI discovery endpoints to InvocationAgentServerHost in the azure-ai-agentserver-invocations package, mirroring the existing OpenAPI endpoint. AsyncAPI complements OpenAPI for the streaming/WebSocket (invocations_ws) surface. Two optional constructor args (asyncapi_spec_json, asyncapi_spec_yaml) enable each endpoint independently, with path-extension-authoritative content types and no server-side format conversion (keeping the package free of a YAML dependency). Constructor type validation raises TypeError early, and startup logging is extended.

Changes:

• New routes GET /invocations/docs/asyncapi.json (JSON) and GET /invocations/docs/asyncapi.yaml (raw YAML), each returning 404 via the upstream error-source path when unregistered.
• New public constructor args + accessors (get_asyncapi_spec_json/get_asyncapi_spec_yaml) with upfront type validation.
• Documentation updates in README and CHANGELOG plus new route/type-validation tests.

Reviewed changes

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

File	Description
azure/ai/agentserver/invocations/_invocation.py	Adds AsyncAPI constructor args, type validation, two routes, two accessors, two endpoints, and extended startup logging (new public API not reflected in api.md).
tests/test_server_routes.py	Adds tests for JSON/YAML 404, success, independence, and constructor type validation.
README.md	Documents the new AsyncAPI endpoints and registration model.
CHANGELOG.md	Adds an 1.0.0b7 (Unreleased) Features entry (but _version.py still says 1.0.0b6).