# 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](/console/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.

```json
{
  "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](/docs/billing).

## 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](/docs/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.

---

Source: https://developers.dvaarik.com/docs/agents · every page as one file: https://developers.dvaarik.com/docs.md