Connects to a voice agent over WebSocket. The client must send an HTTP GET with Upgrade: websocket headers. The optional realtime subprotocol is the only accepted subprotocol value. Supply the VoiceAgents=V1Preview opt-in through either the Foundry-Features header or the foundry_features query parameter.

Handshake failures are evaluated in the following order, independent of the requested transport:

1. Agent enablement (any transport): if the target agent is disabled, the handshake fails before the 101 Switching Protocols upgrade with 409 Conflict, using the shared Foundry ApiErrorResponse shape with error.code = agent_disabled. This failure is terminal until the caller enables the agent, and it takes precedence over the WebRTC-specific checks below.
2. WebRTC availability (only when transport=webrtc, and only once the agent itself is enabled): the agent must have the WebRTC transport capability configured. If the agent is enabled but WebRTC is not available for it, the handshake fails with 404 Not Found. This is distinct from the 409 agent_disabled case above, which concerns the agent itself rather than its WebRTC capability.
3. WebRTC compatibility (only when transport=webrtc): WebRTC does not support bring-your-own-model (BYOM) or hosted-agent voice agents; those requests fail with 400 Bad Request.

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

The requested WebSocket subprotocol. Omit this header or request exactly realtime.

The name of the voice agent.

A query alternative to the Foundry-Features header for clients that cannot set headers during a WebSocket handshake. Set this to VoiceAgents=V1Preview. Either this query parameter or the header is required.

Selects the connection transport. Omit or send websocket for the default, where signaling and audio are exchanged as JSON events over this WebSocket. Send webrtc to negotiate a WebRTC connection: the WebSocket then carries only SDP signaling (rtc.call.sdp.create / rtc.call.sdp.created) while media and the data channel are peer-to-peer.

Whether to persist the conversation created by this WebSocket session. If omitted, the service honors the persisted voice agent definition's configured store value. If supplied, this value overrides the definition's store setting for this session only.

Per-session values for the voice agent's declared structured_inputs, serialized as a JSON object and URL-encoded as this query parameter. Supplied values override definition defaults when rendering the agent's instructions and session-start greeting for this session only. The decoded value must be a JSON object no larger than 32 KiB with a maximum nesting depth of 16.

Selects a specific version of the voice agent for this session.

The API version to use for this operation.

The negotiated WebSocket subprotocol. Present only when the client requests realtime.

The public explanation for this block.

The public continuation instruction.

The public explanation for this block.

The public continuation instruction.