Invocations WebSocket Protocol Guide

The invocations_ws protocol is a duplex WebSocket pass-through. After the platform authenticates the upgrade request and routes it to your container, every frame in both directions is forwarded as-is. The agent developer defines the wire format, the framing model, and the streaming semantics. Unlike responses (OpenAI-compatible, platform-managed history) and invocations (single HTTP request/response, bytes in / bytes out), invocations_ws is a long-lived bidirectional channel under full container control.

Input/Output Contract

URL and Headers

wss://{account}.services.ai.azure.com
   /api/projects/agents/endpoint/protocols/invocations_ws
   ?project_name={project}
   &agent_name={agentName}
   &agent_session_id={sessionId}
   &foundry_features=HostedAgents=V1Preview

The container receives the upgrade on path /invocations_ws. Inside the container, read the session id from the FOUNDRY_AGENT_SESSION_ID environment variable (set by azure-ai-agentserver-invocations), or fall back to the agent_session_id query string.

⚠️ Browsers cannot set the Authorization header on a WebSocket. Browser clients must connect through a thin server-side proxy that adds the header before forwarding. This is a browser API limitation, not a Foundry requirement.

Pass-Through Semantics

The platform is a transparent relay:

• No schema validation. Binary opcodes, text JSON, protobuf, raw PCM — anything ends up at the container untouched.
• No transcoding. Sample rate, codec, byte order are entirely between caller and container.
• No history. Nothing is persisted by Foundry between connections. Use the container filesystem or an external store, keyed by agent_session_id, if you need continuity.
• No platform-managed turn taking. There is no concept of "request" vs "response" — both sides may send frames at any time. Implement your own request/reply correlation if you need it (e.g. include an id field in each JSON frame).

Common Framing Patterns

These are protocols developers build on top of the raw WebSocket. The platform does not require, parse, or validate any of them; they are listed for orientation only.

Discovering the Expected Wire Format

⚠️ Do not guess. The platform exposes no OpenAPI / AsyncAPI surface for invocations_ws agents. The contract lives in the container code.

1. Inspect the WebSocket Handler

Look at the function decorated with @app.ws_handler on an InvocationAgentServerHost (the azure-ai-agentserver-invocations SDK). The handler determines:

• Whether frames are binary, text, or mixed
• The expected first frame (handshake, capabilities, auth challenge)
• The control vocabulary (start, stop, mute, hangup, etc.)
• The response cadence (turn-based vs free-running)

2. Ask the User or Author

If the handler isn't available, ask the agent author for the framing spec before connecting.

Examples

Connect from a Python client (no browser proxy):

import os, uuid, websockets  # requires websockets >= 12 for the additional_headers kwarg below

token = os.popen("az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv").read().strip()
url = (
    "wss://{account}.services.ai.azure.com/api/projects/agents/endpoint/protocols/invocations_ws"
    "?project_name={project}&agent_name={name}"
    f"&agent_session_id={uuid.uuid4().hex}"
    "&foundry_features=HostedAgents=V1Preview"
)

# websockets >= 12 uses `additional_headers`; older versions (<12) expect `extra_headers`.
async with websockets.connect(url, additional_headers={"Authorization": f"Bearer {token}"}) as ws:
    await ws.send(b"<first frame in your wire format>")
    async for frame in ws:
        ...  # frame is bytes (binary) or str (text) depending on what the container sends

Connect from a browser — terminate a local WebSocket in a server-side proxy that injects the token, then forward frames pass-through to the upstream wss://.

Error Handling