Voice Agent WebSocket

Connect to a voice agent

GET /agents/{agent_name}/endpoint/protocols/voice

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. The VoiceAgents=V1Preview opt-in is required only when the agent's definition uses a preview feature, such as Handoff (inline subagents), SIP transfer destinations, or post-call delivery. Supply it 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:

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

Paramètres d’en-tête

Foundry-Features enum

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

VoiceAgents=V1Preview

Sec-WebSocket-Protocol enum

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

realtime

Paramètres de chemin d’accès

agent_name string obligatoire

The name of the voice agent.

Paramètres de la requête

foundry_features enum

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 when the agent uses a preview feature.

VoiceAgents=V1Preview

transport string | enum

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.

Un des éléments suivants :

string

enum

websocketwebrtc

store boolean

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.

structured_inputs string

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.

agent_version_override string

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

api-version string obligatoire

The API version to use for this operation.

Réponses

The response that switches an HTTP connection to the voice-agent WebSocket protocol.

En-têtes

Sec-WebSocket-Protocol enum

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