An agent is the AI voice pipeline that answers a call — the mode (cascade or duplex), the providers behind each stage, when it yields the floor, and the tools it can call. You author that pipeline once as an AgentSpec and address it by id. The Agents API is how you bind one of those agents to a live call: one call, agents.attach(sid, agentId), and the engine wires the audio bridge end to end for you. This is the “drop-in voice agent” path. You don’t open an AudioBridge or move a single frame yourself — you hand the runtime a call_sid and an agent id and it takes the call from there.
The SDK attach call takes an agent id string, not an inline spec object. The AgentSpec lives server-side — you author it in the console at agent.telequick.dev or push it through the control-plane API, then reference it by id from every call. This keeps provider keys and prompts out of your client code and lets you re-tune an agent without shipping a release. The spec fields are documented below and in full on Runtime configuration.

​
Attach an agent to a call

Given a call_sid — from voice.calls.originate, an inbound-call webhook, or voice.calls.get — bind an agent to it. The call must be live (ringing or in progress). 
import { Voice } from "@telequick/sdk";

const voice = new Voice({
  baseUrl: "https://engine.telequick.dev",
  apiKey:  process.env.TELEQUICK_API_KEY!,
  orgId:   "<workspace-id>",
});

// Bind the server-side agent "support-agent" to a live call.
await voice.agents.attach(callSid, "support-agent");
attach resolves the control-plane route voice.agents.attach with your orgId, the sid, and the agent id. On success the engine has hydrated the AgentSpec, prewarmed the providers, and connected the caller’s audio to the pipeline. The same signature exists in the Go and Rust SDKs (Agents.Attach(callSid, agent) / agents.attach(call_sid, agent)); see the SDK reference.

​
Parameters

​
callSid
string
required
The call_sid of a live call. This is the only identifier you need to address a call — the SIP dialog, media session, agent session, and telemetry all key off it.
​
agent
string
required
The id of a server-side agent (its AgentSpec). Author it in the console at agent.telequick.dev or via the control-plane API before you reference it.

​
Attach at originate time

For outbound calls you rarely need a separate attach — pass the agent id to originate and the engine binds it automatically on answer, so the agent is speaking the moment the callee picks up. 
const call = await voice.calls.originate({
  to:      "+15551234567",
  from:    "+15559876543",
  trunkId: "<trunk-id>",
  agent:   "support-agent",   // attached on answer — no second call
});
For inbound calls the agent is chosen by your dialplan / trunk routing (a DID or skill maps to an agent), so no client attach is needed at all. Use agents.attach when you want to bind or swap the agent from your own code — after screening a call, on an IVR selection, or in a webhook handler.

​
Re-attach to a different agent

Swapping agents mid-call is a transfer to an agent, not a second attach — it tears down the current pipeline cleanly before the new one takes over. Use Call.transfer with an agent (see Calls): 
await call.transfer({ agent: "billing-agent" });
Handing a live call from an AI agent to a human is a different operation — see AI ↔ human handoffs.

​
The AgentSpec

The AgentSpec is the single document that defines an agent. attach binds a call to it by id; these are the fields it resolves. Every field has a default, so a minimal spec is a name, a prompt, and any providers you want to override. This is a summary of the top-level shape — the exhaustive field-by-field reference (including every timing knob and budget) is Runtime configuration.
​
name
string
required
Human-readable agent name. Shown in the console and stamped onto call records so you can tell agents apart in the dashboards.
​
pipeline_mode
string
default:"cascaded"
The agent mode. cascaded chains three provider sessions (speech-to-text → language model → text-to-speech) for per-stage control and the widest model choice. realtime hands the whole turn to one duplex speech-to-speech model for the lowest turn latency. See BYO ASR/LLM/TTS and BYO speech-to-speech.
​
system_prompt
string
The agent’s persona and task (instructions on a realtime node). Keep replies short and spoken-friendly — a phone line reads short sentences better than paragraphs.

​
Model & provider

The provider fields you set depend on the mode. Provider keys are per-tenant and resolved from the control plane at call setup — never written into the spec. An agent whose selected providers have no usable key is refused at session creation with a clean error rather than failing mid-call.
​
asr_provider / asr_model
string
Cascade only. Streaming speech-to-text vendor and model — for example deepgram / nova-2. The engine feeds the vendor at the runtime’s 8 kHz PCM16 contract; providers that natively want 16/24 kHz are resampled for you.
​
llm_provider / llm_model
string
Cascade only. Language-model vendor and model — openai, anthropic, gemini, or self-hosted ollama, with a model id such as gpt-4o-mini or claude-sonnet-4-5. This is the stage where tool calling runs. Set llm_fallback_provider for a one-turn resilience path.
​
tts_provider / tts_voice
string
Cascade only. Text-to-speech vendor and voice id — for example elevenlabs, cartesia, deepgram, or openai, with the provider’s voice id.
​
provider / model / voice
string
Realtime only. On a realtime entry node you set one duplex provider instead of three cascade stages — for example openai / gpt-realtime / shimmer, or gemini with a Kore voice. One model listens and speaks on the same bidirectional session.
Shipped duplex providers include OpenAI Realtime, Gemini Live, and xAI Grok Voice. Serving your own open-weights duplex model on your GPUs is in preview — see self-hosted inference.

​
turn_detection

How the agent decides the caller has finished talking, and how it yields the floor when barged. Omit the block entirely for phone-safe defaults. Full behavior on Turn Detection & Barge-in.
​
turn_detection.type
string
default:"on-device VAD"
Who runs voice-activity detection. The default (omit type) runs an on-device VAD on the gateway — the right choice for cascaded agents. Set "energy" for the lightweight built-in energy gate. "server_vad" defers end-of-turn to a cloud realtime provider that already emits speech-start/stop events; the runtime auto-selects it for a realtime entry node unless you set type explicitly. A cascade with server_vad never sees a turn boundary — use the on-device default there.
​
turn_detection.silence_threshold_ms
integer
default:"500"
Trailing silence before end-of-utterance fires. Lower (~300) for snappier replies; raise (~800) for callers who pause to think.
​
turn_detection.barge_confirm_ms
integer
default:"300"
The hold-and-confirm barge-in window: a speech onset arms a pending barge that only cancels the agent if speech sustains past this window, so a backchannel (“mhm”, “ok”) never cuts the agent off. Set 0 for legacy immediate barge-in — only on echo-cancelled (browser) transports.
​
turn_detection.idle
object
The idle watchdog: soft_prompt_s re-engages a silent caller, hangup_s then ends the call. On by default with sensible ceilings so a stuck agent can’t hold a line open forever.

​
tools

The tools the agent can call mid-conversation — an HTTP endpoint, a remote MCP server, or a handler in your own SDK. This is the same tool model the Agent DAG uses under the hood: an llm (or realtime) node advertises tools by name, the model decides when to call one, and the runtime validates the arguments against the tool’s JSON Schema before dispatch. Each session also unions your tools with a built-in telephony toolset (transfer, hold, DTMF, disconnect, supervisor request); on a name collision your tool wins. Full reference on Tool calling.
​
tools
array
A list of tool definitions. Each entry shares one envelope — kind, name, description, silent, spec — with the kind-specific configuration inside spec.
​
tools[].kind
string
required
http (shipped) calls an endpoint you own; mcp (shipped) runs a JSON-RPC tools/call against a remote MCP server over Streamable HTTP; client (scaffolded) pushes the call to your connected SDK to fulfil.
​
tools[].name / description
string
required
The function name the model sees and calls, and the human-readable purpose advertised to the model. Write the description for the model — it’s the primary signal for when to call the tool.
​
tools[].spec.parameters
object
A standard JSON Schema for the tool’s arguments. On an http tool you can omit it and the runtime synthesizes one from the {{placeholder}} tokens in your URL and body.

​
Example AgentSpec

A cascaded support agent with one HTTP tool. Author this in the console or push it through the control-plane API, then reference it by id (support-agent) from agents.attach.
AgentSpec
{
  "name": "support-agent",
  "pipeline_mode": "cascaded",
  "system_prompt": "You are a friendly support agent for Acme. Keep replies short and spoken-friendly.",
  "asr_provider": "deepgram",
  "asr_model": "nova-2",
  "llm_provider": "openai",
  "llm_model": "gpt-4o-mini",
  "llm_fallback_provider": "anthropic",
  "tts_provider": "elevenlabs",
  "tts_voice": "<voice-id>",
  "turn_detection": {
    "silence_threshold_ms": 500,
    "barge_confirm_ms": 300
  },
  "tools": [
    {
      "kind": "http",
      "name": "lookup_order",
      "description": "Look up an order by its ID and return its status.",
      "spec": {
        "method": "GET",
        "url": "https://api.example.com/orders/{{order_id}}",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    }
  ]
}

Runtime configuration

The full AgentSpec field reference — every provider, timing, and budget knob.

Calls

Originate, transfer (re-attach to a different agent), and hang up.

Tool calling

Give the agent HTTP, MCP, and client tools it can call mid-conversation.

Turn detection & barge-in

The behavior behind the turn_detection block.

Sessions & audio bridge

The lower-level path when you want to move audio frames yourself.

AI ↔ human handoffs

Hand a live call from the agent to a human.