@jambonz/schema 0.4.16 → 0.4.17

package/AGENTS.md

@@ -35,7 +35,7 @@ The verb schemas and JSON structure are identical in both modes. The difference
 - **Webhook**: Simple IVR, call routing, voicemail, basic gather-and-respond patterns.
 - **WebSocket**: LLM-powered voice agents, real-time audio streaming, complex conversational flows, anything requiring bidirectional communication, or asynchronous logic, or streaming tts.
 
-**IMPORTANT**: Any application that uses a speech-to-speech verb (`openai_s2s`, `gptlive_s2s`, `google_s2s`, `deepgram_s2s`, `ultravox_s2s`, `qwen_s2s`, `elevenlabs_s2s`, `s2s`, or `agent`) MUST use WebSocket transport, not webhooks. These verbs require persistent bidirectional communication for real-time audio and events.
+**IMPORTANT**: Any application that uses a speech-to-speech verb (`openai_s2s`, `gptlive_s2s`, `voicelive_s2s`, `google_s2s`, `deepgram_s2s`, `ultravox_s2s`, `qwen_s2s`, `elevenlabs_s2s`, `s2s`, or `agent`) MUST use WebSocket transport, not webhooks. These verbs require persistent bidirectional communication for real-time audio and events.
 
 ## Schema
 
@@ -64,6 +64,7 @@ Two tools are available:
 ### AI & Real-time
 - **openai_s2s** / **google_s2s** / **deepgram_s2s** / **ultravox_s2s** / **qwen_s2s** — Connect the caller to a vendor-specific LLM for real-time voice conversation. These are the **preferred** verbs when the vendor is known. Each handles the full STT→LLM→TTS flow with the vendor pre-set.
 - **gptlive_s2s** — Connect the caller to OpenAI's GPT Live API (limited-access alpha). A different wire protocol from `openai_s2s` (Realtime): `llmOptions` carries only a `session_update`, there is no `response_create`, and tool calls arrive via a Responses-targeted *delegation*. See [GPT Live S2S specifics](#gpt-live-s2s-specifics) below.
+- **voicelive_s2s** — Connect the caller to the Azure Voice Live API. Requires `connectOptions.host` (your Foundry/Speech resource). Unlike `openai_s2s`, the `session_update` uses Voice Live's flat shape and is sent verbatim, so Azure-only settings (`azure_semantic_vad`, `azure_deep_noise_suppression`, Azure TTS voices) work.
 - **elevenlabs_s2s** — Connect the caller to an ElevenLabs Conversational AI agent. **Unlike other s2s vendors**, ElevenLabs requires a pre-configured `agent_id` (created in the ElevenLabs dashboard) rather than a model and messages. See [ElevenLabs S2S specifics](#elevenlabs-s2s-specifics) below.
 - **s2s** — Generic LLM voice conversation verb. Use only when the vendor is determined at runtime (e.g. from an env var). Requires `vendor` to be specified.
 - **agent** — Higher-level voice AI agent with integrated turn detection. Mix-and-match STT, LLM, and TTS vendors.
@@ -99,7 +100,7 @@ Two tools are available:
 **IMPORTANT — Code generation rules:**
 
 1. **Always use `stream`, never `listen`** — they are synonyms; `stream` is the preferred name.
-2. **Always use the vendor-specific shortcut when the LLM vendor is known** — use `openai_s2s`, `gptlive_s2s`, `google_s2s`, `elevenlabs_s2s`, `deepgram_s2s`, `qwen_s2s`, or `ultravox_s2s`. Do NOT use `llm` or `s2s` with a `vendor` property when a shortcut exists.
+2. **Always use the vendor-specific shortcut when the LLM vendor is known** — use `openai_s2s`, `gptlive_s2s`, `voicelive_s2s`, `google_s2s`, `elevenlabs_s2s`, `deepgram_s2s`, `qwen_s2s`, or `ultravox_s2s`. Do NOT use `llm` or `s2s` with a `vendor` property when a shortcut exists.
 3. **Use `s2s` (not `llm`) when the vendor is dynamic** — e.g. the vendor comes from an env var or runtime config. Both `s2s` and `llm` are synonyms, but prefer `s2s`.
 4. **Never use `llm` in generated code** — it is a legacy name. Use either a vendor shortcut or `s2s`.
 

package/jambonz-app.schema.json

@@ -29,6 +29,7 @@
         { "$ref": "verbs/ultravox_s2s" },
         { "$ref": "verbs/qwen_s2s" },
         { "$ref": "verbs/gptlive_s2s" },
+        { "$ref": "verbs/voicelive_s2s" },
         { "$ref": "verbs/dialogflow" },
         { "$ref": "verbs/agent" },
         { "$ref": "verbs/transfer" },

package/lib/normalize.js

@@ -16,6 +16,7 @@ const verbTransforms = new Map([
   ['ultravox_s2s', {verb: 'llm', properties: {vendor: 'ultravox'}}],
   ['qwen_s2s', {verb: 'llm', properties: {vendor: 'qwen'}}],
   ['gptlive_s2s', {verb: 'llm', properties: {vendor: 'gptlive'}}],
+  ['voicelive_s2s', {verb: 'llm', properties: {vendor: 'voicelive'}}],
 ]);
 
 function applyVerbTransform(name, data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/schema",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "JSON Schema definitions and validation for jambonz verb applications",
   "main": "index.js",
   "scripts": {

package/verbs/voicelive_s2s.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/voicelive_s2s",
+  "minVersion": "11.1.0",
+  "title": "Azure Voice Live S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'voicelive'. Connects the caller to the Azure Voice Live API for real-time speech-to-speech conversation. connectOptions.host is required and names your Microsoft Foundry or Azure Speech resource (e.g. my-resource.services.ai.azure.com). auth takes either apiKey (sent as the api-key query parameter) or accessToken (a Microsoft Entra ID token, sent as a Bearer header). llmOptions.session_update is required and is sent verbatim in Voice Live's flat session shape, so Azure-only settings such as azure_semantic_vad, azure_deep_noise_suppression and Azure TTS voices are supported.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "voicelive_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "voicelive",
+      "description": "The LLM vendor (always 'voicelive' for this shortcut)."
+    },
+    "connectOptions": {
+      "type": "object",
+      "description": "Connection options for the Voice Live endpoint.",
+      "properties": {
+        "host": {
+          "type": "string",
+          "description": "Required. The Foundry/Speech resource hostname, e.g. my-resource.services.ai.azure.com."
+        },
+        "apiVersion": {
+          "type": "string",
+          "description": "The Voice Live api-version. Defaults to 2026-04-10.",
+          "examples": [
+            "2026-04-10",
+            "2026-07-15"
+          ]
+        },
+        "agentId": {
+          "type": "string",
+          "description": "Foundry Agent Service agent id. When set, the session is addressed by agent instead of model."
+        },
+        "projectId": {
+          "type": "string",
+          "description": "Foundry project id, used together with agentId."
+        },
+        "path": {
+          "type": "string",
+          "description": "Overrides the entire websocket path, including the query string. Rarely needed."
+        }
+      },
+      "required": [
+        "host"
+      ],
+      "additionalProperties": true
+    },
+    "auth": {
+      "type": "object",
+      "description": "Either apiKey (sent as the api-key query parameter) or accessToken (a Microsoft Entra ID token sent as a Bearer header).",
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Azure Voice Live API key."
+        },
+        "accessToken": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Microsoft Entra ID token for the https://ai.azure.com/.default scope."
+        }
+      },
+      "anyOf": [
+        {
+          "required": [
+            "apiKey"
+          ]
+        },
+        {
+          "required": [
+            "accessToken"
+          ]
+        }
+      ],
+      "additionalProperties": true
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "session_update is sent verbatim in Voice Live's flat session shape; response_create triggers the first response.",
+      "properties": {
+        "session_update": {
+          "type": "object",
+          "description": "The flat Voice Live session body."
+        },
+        "response_create": {
+          "type": "object",
+          "description": "The initial response.create body."
+        }
+      },
+      "required": [
+        "session_update",
+        "response_create"
+      ],
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "auth",
+    "connectOptions",
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "voicelive_s2s",
+      "model": "gpt-realtime",
+      "auth": {
+        "apiKey": "..."
+      },
+      "connectOptions": {
+        "host": "my-resource.services.ai.azure.com"
+      },
+      "llmOptions": {
+        "session_update": {
+          "modalities": [
+            "text",
+            "audio"
+          ],
+          "instructions": "You are a helpful voice assistant.",
+          "voice": {
+            "name": "en-US-Ava:DragonHDLatestNeural",
+            "type": "azure-standard"
+          },
+          "turn_detection": {
+            "type": "azure_semantic_vad",
+            "silence_duration_ms": 500,
+            "remove_filler_words": true
+          },
+          "input_audio_noise_reduction": {
+            "type": "azure_deep_noise_suppression"
+          }
+        },
+        "response_create": {}
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}