Agents

Two doors, one agent#

• Machine: POST/GET /v2/agents, GET/PATCH/DELETE /v2/agents/{agent_id}, POST /v2/agents/{agent_id}/rotate-secret with voice:read/voice:write.
• Console: the same operations under /console/v2/projects/{project_id}/agents with the account session — what the Agents page uses.

Create a cascade agent#

Model IDs should come from /v2/provider-catalog; account IDs must belong to the project and be verified. Voice IDs are the provider's own voice names.

{
  "name": "Support",
  "prompt": "Help the caller with {{account_name}}.",
  "pipeline_mode": "cascade",
  "pipeline_config": {
    "stt": { "account_id": "<uuid>", "model": "<catalogue model>" },
    "llm": { "account_id": "<uuid>", "model": "<catalogue model>" },
    "tts": { "account_id": "<uuid>", "model": "<catalogue model>", "voice": "<provider voice>" }
  },
  "language": "en-IN",
  "greeting": "Hello, this is Support.",
  "variables": [{ "name": "account_name", "required": true }]
}

A realtime agent uses pipeline_mode: "realtime" and exactly one realtime stage with account_id, model, and voice. Arbitrary pipeline keys are rejected so plaintext credentials cannot be hidden in an agent configuration.

The contract also carries an optional display name, tool declarations and a tool_webhook_url, DTMF, recording and transcript flags, duration and idle limits, retention, backchannel and ambience settings, and a call webhook_url with transcript/recording inclusion flags. Responses add project ID, version, active state, timestamps, and has_webhook_secret.

record_calls asks your carrier to record; the audio lands in your own carrier account and Dvaarik keeps only the carrier's reference to it. A browser call has no carrier, so it has no recording. store_transcript writes the transcript to the Dvaarik database, where it is kept for 90 days and then deleted; the short insight_config summary survives that deletion. See Billing → What we store.

The webhook secret#

Creation and rotate-secret return webhook_secret once. It signs the completed-call delivery to the agent's own webhook_url using the same timestamped scheme as project webhooks — see Webhooks.

Delete#

DELETE deactivates the agent and returns { id, name, deleted, calls }; historical sessions keep their agent id and version. Numbers bound to the agent stop answering.