Guides

Voice pipelines

Choose what runs an agent's calls, and register your own voice engine as a pipeline.

A voice pipeline is the engine that runs an agent's calls: it takes the call's audio, listens, thinks and speaks. Every agent runs on exactly one pipeline, chosen with the agent's engine field. An agent without the field runs on the platform default.

In the dashboard: Agent Studio (and the graph editor's Agent setup), the Voice pipeline dropdown at the top. Settings the chosen pipeline does not use are greyed out with "Not used by …"; their values stay saved and apply again if you switch back. External pipelines are managed under Settings → Voice pipelines.

Built-in pipelines

id	Pipeline	What it is
`own`	Sonic voice engine	The platform's own engine: prompt, graph, tools and knowledge bases on the platform's models. Twilio, Plivo, Exotel and browser tests.
`oss`	Open-source engine	An optional bundled open-source engine that runs the agent's config with its own provider keys. Twilio and Plivo.
`mock`	Simulation	No phone rings: a scripted caller, for tests and demos.

A built-in pipeline the operator has not set up reports not_configured, and its calls fail until it is.

Choose a pipeline for an agent

Set engine in agent_config when you create or update the agent. List the choices with GET /pipelines.

bash

curl -X PATCH https://api.kshyamai.space/v2/agent/3c90c3cc-0d44-4b50-8822-8dd25736052a \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"agent_config": {"engine": "own"}}'

An unknown value, or another account's pipeline, is refused with 400. One call can use another pipeline with agent_data.engine on POST /call.

Register your own engine

Owners and admins can register an external voice engine. It gets an id of the form ext:<uuid> that agents of the account can choose.

bash

curl -X POST https://api.kshyamai.space/pipelines/external \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complaint desk engine",
    "description": "Our own complaint bot, with its own flow",
    "stream_url": "wss://engine.example.com/stream",
    "protocol": "exotel_voicebot",
    "shared_secret": "a-long-random-secret-of-your-own",
    "capabilities": ["pii_redaction", "recording"]
  }'

The shared secret is write-only: it is stored encrypted and every answer shows it masked. capabilities says which agent settings your engine uses; the dashboard greys out the rest for agents on it. The full list is in capability_catalog of GET /pipelines.

Wire protocols

The telephony provider streams the call to your stream_url with the stream parameters execution_id, token, pipeline_id and signature. signature is the hex HMAC-SHA256 of the execution id with your shared secret, so your engine can check the stream came from the platform.

`protocol`	Telephony	Your engine speaks
`sonic`	Twilio, Plivo, Exotel	The provider's media stream, plus the session and event callbacks of the engine protocol
`twilio_media_stream`	Twilio	Twilio Media Streams frames
`exotel_voicebot`	Exotel	Exotel Voicebot frames

An engine that calls the platform itself (registering an inbound call, reporting that it is full) sends X-Pipeline-Id: ext:<uuid> and Authorization: Bearer <shared secret>. It can only take numbers of its own account.

When a pipeline is missing or disabled

A call on a pipeline that was deleted, is disabled, is not configured, or cannot take the call's telephony provider ends with status error and the reason in error_message. It is never moved to another pipeline. Browser tests (Talk to agent) run on the Sonic voice engine only, so they are refused for agents on an external pipeline.

Note: The stream URL must be wss:// and may not point at a private address. A local address (localhost, 127.0.0.1) is accepted only on a development platform.

The endpoints are in the voice pipelines reference.