Add invocations_ws sub-skill to microsoft-foundry#2388
Open
niuzheng168 wants to merge 10 commits into
Open
Conversation
Introduce a dedicated sub-skill for the Foundry invocations_ws duplex WebSocket protocol used by voice, real-time streaming, and signaling hosted agents. New files (skills/microsoft-foundry/foundry-agent/invocations-ws/): - invocations-ws.md - framework-agnostic build/deploy/connect workflow - references/invocations-ws-protocol.md - wire-level WS contract, agent_session_id semantics, and service-enforced connection limits (5-min idle timeout, 30-min max connection duration) - references/session-management.md - WS session model (client-supplied agent_session_id, reconnect-to-resume), keep-alive guidance, and cross-link to HTTP-protocol session management Cross-skill updates: - SKILL.md: register invocations-ws sub-skill; mention invocations_ws in the create sub-skill description - invoke/invoke.md: add invocations_ws row to protocols table noting agent_invoke does not speak WebSocket - deploy/deploy.md: add invocations_ws to container protocols list and detailed protocols table with limits and cross-link - create/create-hosted.md: add invocations_ws to greenfield protocol table, BYO sample paths, brownfield protocol inference, adapter tables (Python + .NET, both noting no hosting adapter), wrap-agent guidance, and local WebSocket test instructions - troubleshoot/troubleshoot.md: clarify that the sessionId used by /sessions/...:logstream is the client-supplied agent_session_id for invocations_ws agents - invoke/references/session-management.md: cross-link to WS-specific session-management doc - eval-datasets/references/generate-seed-dataset.md: refresh stale protocol enumeration to include invocations and invocations_ws Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Drop the 5-minute idle timeout / 30-minute max connection duration documentation from invocations-ws.md, invocations-ws-protocol.md, and session-management.md (Quick Reference rows, Connection Limits section, Service-Enforced Connection Limits section, related error-table rows, and best-practice items for keep-alives and reconnects). - Drop the 'Bring-Your-Own only / no Microsoft Agent Framework adapter / no adapter package' claims from create-hosted.md (greenfield protocol table, sample browse paths, Custom adapter table, wrap-agent block) and from the deploy.md protocols row. - Remove MCP-tool references from invocations-ws.md (Quick Reference row, comparison table row, Step 4 lead-in, and the session_logstream note). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Delete invocations-ws/references/session-management.md and fold its session-creation and lifecycle content into the existing invoke/references/session-management.md so HTTP and WebSocket session mechanics live in one place. The merged doc now has: - A short Session Creation table contrasting HTTP (session_create MCP tool, server-issued sessionId) with WebSocket (client-supplied agent_session_id on the upgrade URL, no separate create call). - A Session Lifecycle section with both flows side by side. invocations-ws.md, invocations-ws-protocol.md updated to link to the merged doc. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Cross-reference the upstream Azure docs PR (MicrosoftDocs/azure-ai-docs-pr#12220 'Build a voice agent with hosted agents') and correct factual drift plus fill gaps in the invocations_ws skill. Corrections: - URL query params use snake_case: project_name, agent_name (not project-name / agent-name). Drop the bogus api-version=v1 parameter. - Preview gate: every upgrade must carry foundry_features=HostedAgents=V1Preview (or the Foundry-Features header). Added to all URL examples and the query table. - Container handler: use InvocationsAgentServerHost + @app.ws_handler from azure-ai-agentserver-invocations (same host that serves HTTP /invocations). The host owns websocket.accept(), Ping/Pong keep-alive, exception->1011 mapping, /readiness, and metrics. Drop the manual FastAPI snippet and the port-8088 hint. - Region: invocations_ws preview is North Central US only. Added an info callout near the top and to 404 troubleshooting rows. - Auth: container does NOT see Authorization (stripped by APIM/Agents service). Don't accept an authorization query parameter. Scope is https://ai.azure.com/.default for SDK callers. - Session id (FOUNDRY_AGENT_SESSION_ID): preferred path is the env var the host injects; query string is the fallback. - agent_session_id is OPTIONAL on the upgrade. If omitted, the platform (or container) generates one; supply it explicitly only to resume an existing session. - Samples repo: microsoft-foundry/foundry-samples (was azure-ai-foundry/...). - Resource recommendation: 1 vCPU / 2 GiB minimum for voice, up to 2 vCPU / 4 GiB (matches docs PR). Session model correction in invoke/references/session-management.md: - HTTP and WebSocket hosted-agent sessions share the same model: per-session VM-isolated sandbox with persistent $HOME, sticky to the session id, with state auto-restored after idle deprovisioning. - Rewrote the WS lifecycle diagram to distinguish CONNECTION lifecycle from SESSION lifecycle (closing the WebSocket does NOT delete the session; reconnecting with the same id re-hydrates $HOME). - Removed the incorrect claim that the next connection can land on a different replica and that the container must use external storage to re-hydrate state. - Softened the id format claim: `^[A-Za-z0-9_-]{8,128}$` is documented for MCP-issued sessionId; the same character set is safe for agent_session_id (not explicitly restated in the docs). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
niuzheng168
requested review from
RickWinter,
XOEEst,
XiaofuHuang,
anchenyi,
ankitbko,
jugonzales,
tendau and
vebudumu
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds first-class documentation and troubleshooting guidance for Foundry hosted agents using the invocations_ws (duplex WebSocket) protocol, and wires this protocol into existing “deploy/create/invoke” skill docs.
Changes:
- Document
invocations_wsalongside existing HTTP protocols (responses,invocations) across skills and references - Add new
invocations_wsskill and protocol guide docs, including URL/header/session semantics and examples - Clarify session/logging behavior differences between HTTP sessions and WebSocket
agent_session_id
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/microsoft-foundry/foundry-agent/troubleshoot/troubleshoot.md | Adds troubleshooting note clarifying sessionId mapping for invocations_ws. |
| plugin/skills/microsoft-foundry/foundry-agent/invoke/references/session-management.md | Expands session lifecycle docs to cover both HTTP and WebSocket session creation/behavior. |
| plugin/skills/microsoft-foundry/foundry-agent/invoke/invoke.md | Adds invocations_ws to protocol list and clarifies agent_invoke is HTTP-only. |
| plugin/skills/microsoft-foundry/foundry-agent/invocations-ws/references/invocations-ws-protocol.md | New detailed reference for WS URL/header/session contract, semantics, and examples. |
| plugin/skills/microsoft-foundry/foundry-agent/invocations-ws/invocations-ws.md | New skill doc for building/deploying/connecting invocations_ws agents. |
| plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/generate-seed-dataset.md | Updates dataset guidance to include invocations_ws in supported protocol examples. |
| plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md | Updates deploy docs to list/support invocations_ws and link to the new skill. |
| plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md | Extends create workflow guidance to include invocations_ws and local WS testing tips. |
| plugin/skills/microsoft-foundry/SKILL.md | Registers the new invocations-ws skill and expands “create” skill scope to include it. |
- invocations-ws-protocol.md: note websockets >= 12 requirement for the additional_headers kwarg (extra_headers for older versions) - create-hosted.md: remove trailing whitespace Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
anchenyi
reviewed
May 26, 2026
| | Python + Microsoft Agent Framework + `invocations` | `samples/python/hosted-agents/agent-framework/invocations/` | | ||
| | Python + LangGraph | `samples/python/hosted-agents/bring-your-own/{protocol}/langgraph-chat/` | | ||
| | Python + Custom | `samples/python/hosted-agents/bring-your-own/{protocol}/` | | ||
| | Python + Custom + `invocations_ws` | `samples/python/hosted-agents/bring-your-own/invocations_ws/` | |
Collaborator
There was a problem hiding this comment.
Have you uploaded invocations_ws samples in foundry-samples?
There was a problem hiding this comment.
yes, but still in PR https://github.com/microsoft-foundry/foundry-samples-pr/pull/315
anchenyi
reviewed
May 26, 2026
Collaborator
There was a problem hiding this comment.
Now we have "three invocation protocols"
- 'two invocation protocols' -> 'three invocation protocols', noting they are distinct contracts and an agent may declare more than one on the same container - Split 'Key difference' into a per-protocol bullet list (responses / invocations / invocations_ws) - Fix tip: agent_invoke speaks responses + invocations only; invocations_ws requires a WebSocket client Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
yulin-li
approved these changes
May 26, 2026
anchenyi
reviewed
May 26, 2026
| from azure.ai.agentserver.invocations import InvocationsAgentServerHost | ||
| from starlette.websockets import WebSocket | ||
|
|
||
| app = InvocationsAgentServerHost() |
Collaborator
There was a problem hiding this comment.
InvocationsAgentServerHost or InvocationAgentServerHost? We are using InvocationAgentServerHost (no "s" verison) there samples
Author
There was a problem hiding this comment.
updated to InvocationAgentServerHost
anchenyi
reviewed
May 26, 2026
Collaborator
There was a problem hiding this comment.
This best practise should be updated. "Always use session_create before invoking a hosted agent" is not correct now.
Author
There was a problem hiding this comment.
update to explicit as invocations and responses
anchenyi
reviewed
May 26, 2026
Collaborator
There was a problem hiding this comment.
Now that this section introduces three protocols, “both protocols” is ambiguous. Could we make this explicit as responses and invocations?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new
invocations-wssub-skill underplugin/skills/microsoft-foundry/foundry-agent/documenting the WebSocket protocol for hosted Foundry agents (voice frameworks like Pipecat, LiveKit Agents, Microsoft Voice Live), plus cross-skill updates so existing skills point at the new content.What's new
invocations-ws/invocations-ws.md— author guide: agentserver SDK@app.ws_handlerdecorator pattern, agent.yamlprotocols:config, deploy + connect quickstart, multi-protocol coexistence example (invocations+invocations_wsin the same container).invocations-ws/references/invocations-ws-protocol.md— wire-level protocol reference: WSS URL, snake_case query params, preview gate (foundry_features=HostedAgents=V1Preview), 1 MB frame limit, close codes (1000/1001/1002/1003/1006/1008/1009/1011),Authorizationheader stripping, ping/pong (30s), env var fallbacks.Cross-skill updates
SKILL.md— surfacesinvocations-wsin the sub-skill map.create/create-hosted.md— voice-frameworks row in protocol table, multi-protocol tip, agentserver SDK pattern, expanded sample browse paths (pipecat-ws-server,pipecat-webrtc,livekit-server).deploy/deploy.md— protocols can coexist on the same container.invoke/invoke.md— pointer to invocations_ws for streaming sessions.invoke/references/session-management.md— consolidated HTTP + WS session model (per-session VM-isolated sandbox with persistent\$HOME, session id is affinity key, idle timeout 5 min deprovisions compute but state persists, max session 30 min).troubleshoot/troubleshoot.md— WS-specific errors.eval-datasets/references/generate-seed-dataset.md— minor alignment.Alignment
samples/python/hosted-agents/bring-your-own/invocations_ws/.This skill content was originally drafted as microsoft/azure-skills#127; moving here per repo-of-record guidance.